mnemos-pi

---

AI agents forget everything when a session ends. Mnemos gives them a place to lay it down — structured, searchable, governed by contract — so what they learn does not vanish with the closing of a window.

• Local-first. One process on your machine. SQLite + a bundled embedding model; nothing leaves the host, no API keys, works offline.
• One server, any harness. VS Code Copilot, Claude Code, Cursor, OpenCode, Codex, Windsurf, ZCode, pi, Hermes — the same MCP wire, one line each.
• The agent learns to use it. Not just tools: always-on instructions, a skill pack, and a memory-first prompt mode, deployed into your harness in one command.

---

🚀 Quick start

Three commands from an empty machine to an agent that remembers — and knows when to look.

1 · Install the server

pip install mnemos-memory-server

One package, everything included: the memory server, the mnemos CLI, the REST API, and the MCP server your agent harness talks to. The embedding model ships inside — search works fully offline, no API keys, nothing downloaded.

⚠️ Mind the name: pip install mnemos (without -memory-server) is an unrelated project.

2 · Connect your harness — and teach it to use memory

mnemos integration setup

One pass: detects the agent harnesses on your machine, registers the Mnemos MCP server in each supported one (VS Code Copilot, Cursor, ZCode, OpenCode, pi, Hermes, and everything reading the ~/.agents standard — Claude Code, Codex and friends), and deploys the behavioral pack — always-on instructions and memory skills, so the agent recalls at session start, checkpoints before its context gets compacted, and treats memory as a priority instead of forgetting the tools exist.

Running a harness that reads nothing standard? One paste block per harness: Connect Mnemos to any harness.

3 · Verify — then try it

mnemos doctor

PASS / WARN / FAIL per check: store, config, MCP transport, harness registration (--fix repairs the common warnings). Then give it a memory:

mnemos add "First memory — Mnemos remembers across sessions" \
  --tags project:mnemos,agent:me,mnemos:learning
mnemos search "remembers across sessions"

That is the whole loop: write, find, never lose it — and the agent knows when to look.

📘 Want every detail? The extended guide covers all install variants (uv tool, pipx, CLI-only, external LLM extras, installer script, container), per-harness connection walkthroughs, configuration, and troubleshooting: Getting Started — the complete first run.

---

✨ Features

One local server — and a connected agent harness gets the full memory stack.

Area	What you get
Universal connectivity	MCP server (26 tools, stdio) + REST API — any MCP-capable harness connects in one line (tools · HTTP)
Ready integrations	VS Code Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, ZCode, pi, Hermes Agent — one-line MCP presets for all of them, native deploy targets for most, multi-harness doctor (mnemos doctor)
Skill pack	14+ memory skills deployed into your harnesses
Flexible memory	Hybrid search (full-text + vector, rank fusion) over the bundled offline model mnema-embed-v1, tag contract, per-agent / per-project memory, context-filter profiles, CCR compression — 70–90% token savings, originals kept
Context assembly	assemble_context: search → compress → filter → secret scan → cache align → token budget, per-block provenance
Context bridge	on_context_rewrite — when the harness compacts history, the lossless original stays available on demand
Lifecycle hooks	pre_llm_call context injection, on_session_start, post_tool_call auto-compression of tool outputs
Publication v3.0.0	Entries visible immediately after save, background refinement with seamless swap, quarantine with neutral retraction
Self-protection	Injection / secret detectors on input and publication, every output scanned, full per-entry audit
Auto-pipeline	Background processor: clustering, deduplication, quality gate, publication. Entries awaiting refinement sit at pipeline_state=pending until the processor runs — in CLI-only deployments (no daemon) start it with mnemos processor start; mnemos doctor reports the pending-queue depth

Autonomy for an arbitrary harness and LLM-driven enrichment are partial — the full, honest map lives in docs/en/features.md.

---

🧩 What Mnemos is

A single-tenant, local-first memory server for AI agents. One in-process core, three equivalent control surfaces, and a storage layer you can read with your own eyes.

	Capability	What it gives you
🔎	Hybrid search	Vector similarity + SQLite FTS5 full-text over every memory
🧪	Knowledge pipeline	raw → processing → processed → published lifecycle with a state machine
🧠	Per-agent recall	A focused recall surface scoped to each agent's project context
⚙️	Policy engine	Schedule and trigger automation over the memory store
🧹	Context filter	Five-stage noise stripper for logs / stdout before anything hits a model
🗜️	Reversible compression (CCR)	Compress large content with zero data loss — originals cached in SQLite, retrievable via hash marker
🧷	CacheAligner	Relocate dynamic content (timestamps, UUIDs, session ids, tokens) to the tail so provider KV caches (Anthropic cache_control, OpenAI prefix caching) hit across requests
🪶	Output token reduction	Optional verbosity / effort params on mnemos_add / mnemos_search / mnemos_recall_context steer the caller's output style — backward compatible, defaults are a no-op
📂	Path-scoped rules	Ingest project rules and apply them by file path
🗂️	Obsidian vault	A markdown mirror humans can browse, edit, and grep

SQLite for metadata, a local numpy + SQLite vector index for recall, and an Obsidian-compatible vault for the humans in the loop.

Where this is going. The shipped, measured rung is stores and finds. The next rungs — collapse with checks (session → project → cross-project synthesis: automatic by default, but never unconditional in authority — every derivative traces back to its sources, nothing pins without an operator) and, later, builds understanding — open only as pre-registered experiments prove them (ADR-0025). The invariant on that road is zero silent losses: a fact is either retained, or its loss is visible. And the shape of the ambition is a nervous system, not a conductor — memory that surfaces the right thing at the right moment, never one that conducts the agent.

---

🤝 Connect any harness

Mnemos works with every MCP-capable agent harness. Three integration levels — pick the strongest one your harness supports:

Harness	Native deploy target	One-line MCP preset	Adapter template
VS Code Copilot	copilot (+ prompts via generic-copilot)	mcp-setup.sh	✓
Claude Code	via agents	preset	✓
Cursor	cursor	preset	✓
Codex	via agents	preset	✓
Windsurf	—	preset	✓
OpenCode	—	preset	✓
ZCode	zcode	—	✓
Any AGENTS.md-standard harness	agents	—	✓
pi	pi (bridge extension, also on npm as pi-mnemos)	preset	✓
Hermes Agent	hermes (native in-process MemoryProvider plugin)	—	—

• Native targets — mnemos integration setup --target <name> deploys the behavioral pack and registers the MCP server in one pass (integration guide).
• One-line presets — integrations/mcp-presets.md: every harness above, copy-paste ready.
• Adapter template — integrations/adapter-template.md: Connect / Expose / Configure + acceptance checklist for any harness that speaks MCP stdio.
• Hermes Agent runs Mnemos in-process: pip install mnemos-memory-server in the Hermes environment, then mnemos integration setup --target hermes (details).

The shared contract is the tag schema — project:<slug>, agent:<slug>, and at least one mnemos:<subtype> — that every memory entry must carry.

---

🏗️ Architecture

flowchart TB
    subgraph CLIENTS["Clients"]
        C1(["Agent harness\nstdio MCP"])
        C2(["CLI — mnemos …"])
        C3(["HTTP API client"])
    end

    subgraph IFACE["Interface Layer"]
        MCP["mcp_server.py"]
        FAPI["api/main.py · FastAPI"]
        TYPER["cli/main.py · Typer"]
    end

    MGR(["MemoryManager\nmanager.py"])

    subgraph PROC["Processing Subsystems"]
        CF["Context Filter\nfilter/"]
        PP["Knowledge Pipeline\npipeline/"]
        RE["Recall Engine\nrecall/"]
        PE["Policy Engine\npolicy/"]
    end

    subgraph BG["Background Services"]
        WA["Watchers\nwatchers/"]
        AC["Auto-collect\nauto_collect.py"]
    end

    subgraph STORE["Storage Layer"]
        SQ[("SQLite\nFTS5 · traces · projects")]
        VS[("Vector Store\nnumpy + SQLite")]
        VLT[("Obsidian Vault\nmarkdown mirror")]
    end

    C1 -->|"stdio"| MCP
    C2 --> TYPER
    C3 --> FAPI
    MCP --> MGR
    TYPER --> MGR
    FAPI --> MGR
    MGR --> CF
    MGR --> PP
    MGR --> RE
    MGR --> SQ
    MGR --> VS
    MGR --> VLT
    CF -.->|"raw + clean"| SQ
    PP -->|"status transitions"| SQ
    PP -->|"published upsert"| VS
    RE -->|"FTS5 MATCH"| SQ
    RE -->|"cosine search"| VS
    PE -->|"schedule / trigger"| MGR
    WA -->|"file events"| MGR
    AC -.->|"checkpoint reminder"| MCP

A deeper walkthrough — data model, state machines, security boundaries, operational concerns — lives in architecture/overview.md.

---

🎛️ Three surfaces, one core

The same MemoryManager powers all three interfaces. Pick the one that fits your client.

Surface	Use it when…	Reference
MCP — mnemos mcp-server	You are an agent harness — the path every connected agent takes	mcp-tools.md
CLI — mnemos …	You live in a shell, want fast ad-hoc add / search, or are scripting cron jobs	cli-reference.md
HTTP — mnemos serve	You have a non-MCP client — a web dashboard, a mobile app, a CI runner	http-api.md

The HTTP surface also exposes the A2A Sessions API — a persistent backend for multi-step agent conversations that survive restarts. See a2a-sessions.md.

---

📚 Documentation

Page	What it covers
docs/README.md	Documentation landing — language picker (EN / RU)
getting-started.md	First run: install → first memory → first search → connect your harness
mcp-presets.md	Connect Mnemos to any harness — one-line MCP presets (VS Code, Claude Code, Cursor, OpenCode, Codex, Windsurf, pi, Hermes)
integration-guide.md	The behavioral pack: instructions, skills, prompt mode, deploy targets, agent wiring, Hermes plugin
features.md	What works out of the box, what is partial, what is planned
architecture/overview.md	System shape, data model, state machines, security boundaries
cli-reference.md	Every mnemos subcommand with flags, defaults, examples
mcp-tools.md	Every mnemos_* tool exposed to agent harnesses
http-api.md	Every HTTP endpoint (memory CRUD, workflow, hooks, A2A Sessions)
tag-contract.md	The project: / agent: / mnemos: schema enforced on every memory
security.md	Threat model, SSRF guard, FTS5 escape, auth model
runbooks/	Install, migrate, backup / restore, dependency updates, container deployment
adr/	Architectural decision records — the why behind the design
CHANGELOG.md	Release notes — Keep a Changelog format
CONTRIBUTING.md	Development setup, git workflow, quality gate

---

📖 The lore

In Hesiod's Theogony, Mnemosyne (Μνημοσύνη) is the Titaness of memory — she who, by Zeus, gave birth to the nine Muses and through them made the world's remembering possible. Her name is the root of mnemonic, and she is what every singer, poet, and philosopher prays to before they begin.

This software carries her name because it is built for the same task: to make remembering possible for the things that think. AI agents, unmoored from any single conversation, lose everything that came before. Mnemos gives them a place to lay it down — structured, searchable, governed by contract — so that what they learn does not vanish with the closing of a session. The Muses, after all, were not for the gods' benefit. They were for the songs.

---

⚖️ License & contributing

Apache-2.0 — see LICENSE and NOTICE. Source: github.com/Korrnals/mnemos.

Contributions are welcome — CONTRIBUTING.md has the development setup, the branch and commit conventions, and the quality gate a change must pass.

---

🛠 CI / Релизы — кластерный конвейер release-pipeline

Этот проект подключён к общему кластерному конвейеру релизов (Korrnals/release-pipeline, K3s abyss-ai-agent, namespace release-pipeline). GitHub Actions не используется (биллинг аккаунта заблокирован) — конвейер и есть штатный путь релизов. Релизный артефакт подписывается трёхслойно: SHA256 → SBOM → cosign → GPG.

Релиз новой версии:

1. VERSION → релизный коммит (конвенция репо) → тег vX.Y.Z → push.
2. Обновить версию проекта в projects[] файла ~/.cache/release-pipeline-values.yaml и применить:

   helm upgrade --install release-pipeline \
     ~/LABs/Projects/Project-Umbra/release-pipeline/chart/release-pipeline \
     --kube-context abyss-ai-agent -n release-pipeline \
     -f ~/.cache/release-pipeline-values.yaml
   

3. Наблюдение: kubectl --context abyss-ai-agent -n release-pipeline get jobs, логи: kubectl ... logs -f job/release-<proj>-<ver>.

Подробности (типы проектов, kaniko-контейнеры, teardown): README конвейера.