{"id":51405839,"url":"https://github.com/Perseus-Computing-LLC/perseus-vault","last_synced_at":"2026-07-23T02:00:56.715Z","repository":{"id":362993014,"uuid":"1261564890","full_name":"Perseus-Computing-LLC/perseus-vault","owner":"Perseus-Computing-LLC","description":"Persistent, encrypted memory for AI agents: one Rust binary, one file, no cloud. 55+ MCP tools, hybrid recall (BM25 + dense + RRF), bi-temporal history, AES-256-GCM. 73.8% on LongMemEval. Local-first, air-gap ready, MIT.","archived":false,"fork":false,"pushed_at":"2026-07-17T15:55:06.000Z","size":3970,"stargazers_count":30,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-19T20:09:48.455Z","etag":null,"topics":["agent-memory","ai-agents","context-engineering","encryption","fts5","llm","local-first","mcp","mcp-server","mimir","model-context-protocol","open-source","persistent-memory","rust","semantic-search","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"http://mimir.perseus.observer/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Perseus-Computing-LLC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tcconnally"],"opencollective":"perseus","polar":"perseus-computing","ko_fi":"perseus"}},"created_at":"2026-06-06T21:31:46.000Z","updated_at":"2026-07-19T03:37:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Perseus-Computing-LLC/perseus-vault","commit_stats":null,"previous_names":["tcconnally/engram-rs","tcconnally/mneme","tcconnally/mimir","perseus-computing-llc/mimir","perseus-computing-llc/mneme","perseus-computing-llc/perseus-vault"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/Perseus-Computing-LLC/perseus-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Perseus-Computing-LLC","download_url":"https://codeload.github.com/Perseus-Computing-LLC/perseus-vault/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fperseus-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35671387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","context-engineering","encryption","fts5","llm","local-first","mcp","mcp-server","mimir","model-context-protocol","open-source","persistent-memory","rust","semantic-search","sqlite","vector-search"],"created_at":"2026-07-04T11:00:23.194Z","updated_at":"2026-07-23T02:00:56.712Z","avatar_url":"https://github.com/Perseus-Computing-LLC.png","language":"Rust","funding_links":["https://github.com/sponsors/tcconnally","perseus","https://polar.sh/perseus-computing","https://ko-fi.com/perseus"],"categories":["💿 Products"],"sub_categories":["Open-Source"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\".github/banner.png\" alt=\"Perseus Vault — Persistent Memory. Encrypted, local-first, one portable file.\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n# Perseus Vault\n\n\u003c!-- mcp-name: io.github.Perseus-Computing-LLC/perseus-vault --\u003e\n\n\u003e **Persistent, encrypted memory for AI agents. One Rust binary, one file, no cloud.**\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://rust-lang.org)\n[![Version](https://img.shields.io/badge/version-2.20.2-green.svg)](https://github.com/Perseus-Computing-LLC/perseus-vault/releases)\n[![LangGraph](https://img.shields.io/badge/integrations-LangGraph-blue)](integrations/langgraph/)\n[![CrewAI](https://img.shields.io/badge/integrations-CrewAI-orange)](integrations/crewai/)\n[![AutoGen](https://img.shields.io/badge/integrations-AutoGen-purple)](integrations/autogen/)\n[![MCP Tools](https://img.shields.io/badge/MCP%20tools-55%2B-brightgreen)]()\n[![Listed on mcpservers.org](https://img.shields.io/badge/listed-mcpservers.org-blue)](https://mcpservers.org/servers/perseus-computing-llc/perseus-vault)\n\nGive your agents memory that survives the session, so they stop re-deriving what they\nalready learned and stop repeating past mistakes. Hybrid recall (BM25 + dense + RRF),\nbi-temporal history, and **AES-256-GCM** at rest, exposed as **55+ MCP tools** that work\nwith any host. **73.8% on LongMemEval's official harness** (vs Zep 63.8%, Mem0 49.0%).\n**One binary. One file. No Docker. No Postgres. No cloud.** Local-first, air-gap ready, MIT.\n\n## One-Line Install\n\n```bash\ncurl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh\n```\n\nThat's it. Perseus Vault is installed to `~/.local/bin/perseus-vault`. Start it:\n\n```bash\nperseus-vault serve --db ~/.mimir/data/perseus-vault.db\n```\n\n\u003e **macOS note (Apple Silicon).** A freshly built or copied binary is\n\u003e SIGKILLed on first run (`Killed: 9`, no other output) by the OS binary\n\u003e policy — even with no quarantine attribute. The one-line installer and the\n\u003e `bootstrap.sh` build-from-source installer ad-hoc code-sign Perseus Vault for\n\u003e you. If you build the binary yourself, sign it once **after each rebuild**:\n\u003e\n\u003e ```bash\n\u003e cargo build --release\n\u003e cp target/release/perseus-vault ~/.local/bin/perseus-vault\n\u003e codesign --force --sign - ~/.local/bin/perseus-vault   # required on Apple Silicon; fixes \"Killed: 9\"\n\u003e ```\n\u003e\n\u003e `--force` re-signs an already-signed binary (needed after every rebuild); the\n\u003e step is harmless on Intel macOS and unnecessary on Linux/Windows.\n\nThen wire your MCP client(s) — and the full recall/capture loop — in one command:\n\n```bash\nperseus-vault install-client --hooks --rules\n```\n\nThis autodetects Claude Code / Codex / Cursor (pass `--client \u003cname\u003e` for\nclaude-desktop, hermes, windsurf, vscode, zed, or generic; `--all-detected`\nwires every detected client), merges the MCP server registration into the\nclient's config without clobbering anything (a `.bak-perseus` backup is\nwritten first), points every client at **one shared memory database**,\nregisters the session lifecycle hooks (recall injection on SessionStart,\nhygiene on session end — the `docs/lifecycle-hooks.md` contract), and appends\nthe memory usage rules to `CLAUDE.md`/`AGENTS.md`. Re-running is a no-op; add\n`--dry-run` to preview every file it would touch.\n\nOr connect any MCP host by hand (Claude Desktop, Cursor, Hermes Agent, Perseus, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"perseus-vault\": {\n      \"command\": \"perseus-vault\",\n      \"args\": [\"serve\", \"--db\", \"~/.mimir/data/perseus-vault.db\"]\n    }\n  }\n}\n```\n\n## 30-Second Quickstart\n\n```bash\n# Start Perseus Vault\nperseus-vault serve --db memory.db \u0026\nsleep 1\n\n# Remember a fact (via MCP JSON-RPC on stdio)\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"mimir_remember\",\"arguments\":{\"category\":\"demo\",\"key\":\"hello\",\"body_json\":\"{\\\"text\\\":\\\"Hello from Perseus Vault!\\\"}\"}}}' | perseus-vault serve --db memory.db\n\n# Search for it\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"mimir_recall\",\"arguments\":{\"query\":\"Hello\"}}}' | perseus-vault serve --db memory.db\n```\n\n## Works With Every MCP Client\n\nPerseus Vault is a standard MCP **stdio** server — the same `perseus-vault serve` command works\neverywhere. Run `perseus-vault doctor` to validate your install and print this matrix locally.\n\n| Client | Status | Config | \n|---|---|---|\n| Claude Desktop | ✅ | `claude_desktop_config.json` |\n| Claude Code / Hermes | ✅ | `.mcp.json` / `config.yaml` |\n| Cursor | ✅ | `.cursor/mcp.json` |\n| Windsurf | ✅ | `mcp_config.json` |\n| VS Code + Continue.dev | ✅ | `config.json` |\n| Zed | ✅ | `settings.json` |\n| Codex CLI | ✅ | `~/.codex/config.toml` |\n\nCopy-paste config snippets for each: **[docs/clients/](docs/clients/)**.\n\nThen wire the **recall → work → capture → consolidate** loop to your client's\nsession events (SessionStart/Stop hooks for Claude Code, Codex, and Cursor,\nplus a portable AGENTS.md fallback): **[docs/lifecycle-hooks.md](docs/lifecycle-hooks.md)**.\n\nComposing with a memory washer (CoalWash) and a runtime output compactor\n(Noisegate) for end-to-end context-budget control:\n**[docs/integration/context-budget-stack.md](docs/integration/context-budget-stack.md)**.\n\n## Why Perseus Vault\n\nPerseus Vault is the **only** memory engine that is simultaneously MCP-native,\nlocal-first, zero-dependency, AND agent-first.\n\n### LongMemEval QA (official harness)\n\nRecall quality measured on LongMemEval's **official** harness, not a home-grown script:\n\n| Memory engine | QA accuracy |\n|---|---|\n| **Perseus Vault** | **73.8%** |\n| Zep | 63.8% (published) |\n| Mem0 | 49.0% (published) |\n\n`longmemeval_s` (500 questions), gpt-4o-2024-08-06 answerer + LongMemEval's official judge; competitor numbers are their published values. Perseus Vault's 73.8% is the plain mean of 3 runs; 79.0% with official CoT. [Methodology \u0026 content-hashed (sha256) results →](benchmark/longmemeval/COMPARISON.md)\n\n### LOCOMO (mem0's own harness)\n\nMeasured on mem0's own LOCOMO harness ([our fork](https://github.com/Perseus-Computing-LLC/memory-benchmarks)), not ours — cats 1–4, 1,540q, top-200, gpt-5 answerer + judge:\n\n| Engine | Overall | Single | Temporal | Multi | Open-domain |\n|---|---|---|---|---|---|\n| **Perseus Vault 2.20.2** | **87.9%** | 89.1 | 92.2 | 85.1 | 70.8 |\n| Mem0 Platform Starter | 82.2% | 85.0 | 82.9 | 78.0 | 67.7 |\n| Zep Cloud Flex | 33.8% | 36.9 | 6.9 | 50.0 | 49.0 |\n\nCat-5 adversarial (446q): Perseus 63.5, Mem0 55.6, Zep 49.8. Our Mem0 measurement is 9.4pts below their published file (judge/platform drift — disclosed). [Full leaderboard →](https://github.com/Perseus-Computing-LLC/memory-benchmarks)\n\n### Bi-temporal time-travel (three-axis)\n\nOur strongest structural differentiator — full **SQL:2011 bi-temporal** history\n(transaction-time *and* valid-time) — measured against a reproducible,\n**fully offline** gauntlet. It drives the real shipped binary over MCP stdio\nthrough the hard cases single-axis competitors get wrong (retroactive\ncorrections, proactive future-dated facts, out-of-order arrival, belief-vs-truth\ndivergence, closed periods):\n\n| Axis | Question it answers | Checks | Pass |\n|---|---|---|---|\n| **valid-time** (`valid_at`) | \"what was true in the world at T\" | 10 | 10 |\n| **transaction-time** (`as_of`) | \"what did we believe at T\" | 1 | 1 |\n| **bi-temporal** (`bitemporal`) | \"as of belief at T, what was true at V\" | 2 | 2 |\n| **Total** | | **13** | **13 (100%)** |\n\nReproduce with a single command (no API key, no network, no LLM):\n\n```bash\ncargo build --release\npython benchmark/temporal/gauntlet.py --bin target/release/perseus-vault\n```\n\nThe PASS/FAIL verdicts are deterministic (wall-clock timestamps vary, verdicts\ndo not), so a correct build re-runs to an identical `signature_sha256`. The\ncommitted [`gauntlet_report.json`](benchmark/temporal/gauntlet_report.json) is\nthe reference. [Methodology \u0026 dataset →](benchmark/temporal/README.md)\n\n### Comparison Matrix\n\n| | Perseus Vault | Mem0 | Letta | Zep |\n|---|---|---|---|---|\n| **Deployment** | Single binary | Cloud + self-host | Docker/Postgres | Docker/Neo4j |\n| **Dependencies** | None (SQLite embedded) | Python + vector DB | Postgres + Python | Neo4j + Go (Graphiti) |\n| **MCP-Native** | ✅ 55+ tools | ❌ Not MCP-native | ❌ Not MCP-native | ❌ Not MCP-native |\n| **Offline/Local** | ✅ Fully local | Cloud-dependent | Docker needed | Docker needed |\n| **Encryption** | AES-256-GCM ✅ | ❌ | ❌ | ❌ |\n| **Hybrid Search** | BM25 + Dense + RRF | Vector only | Vector only | Vector + Graph |\n| **Entity Lifecycle** | Decay + Promote + Archive | ❌ | ❌ | ❌ |\n| **Entity Graph** | Link + Traverse | ❌ | ❌ | ✅ |\n| **Journal Audit Trail** | ✅ Immutable | ❌ | ❌ | ❌ |\n| **State Management** | ✅ Key-value + TTL | ❌ | ❌ | ❌ |\n| **MCP Tools** | 55+ | 5 | 8 | 0 |\n| **License** | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 |\n\n[Full comparison: Perseus Vault vs Mem0 →](docs/comparison/mimir-vs-mem0.md)\n[vs Letta →](docs/comparison/mimir-vs-letta.md)\n[vs Zep →](docs/comparison/mimir-vs-zep.md)\n\n### Stress Test: 100K Entities\n\nPerseus Vault handles production workloads on modest hardware. The numbers\nbelow are from the committed artifact\n[`benchmark/scale/report.json`](benchmark/scale/report.json): the real release\nbinary driven over MCP stdio (one persistent process per corpus size), AMD64\n16-core, Windows 11, every write durable before the next is sent.\n\n| Metric | 10K | 100K |\n|---|---|---|\n| **Write throughput, sustained (MCP stdio)** | 479 docs/s | 40 docs/s |\n| **Hybrid recall p50** | 19.03 ms | 79.73 ms |\n| **FTS5 recall p50** | 3.14 ms | 15.67 ms |\n\nFull percentiles, `as_of` point lookups, temporal recall, and cold-start\nnumbers are in [`benchmark/scale/`](benchmark/scale/README.md).\n\nRun it yourself: `python benchmark/scale/run.py`\n\n### Recall Accuracy at Scale: Keyword Collapses, Hybrid Holds\n\nSpeed is table stakes — the question that matters for agent memory is *does the\nright memory actually surface?* Measured on distinct-content corpora (first-party,\nreproducible; see [`benchmark/lambda/`](benchmark/lambda/)), recall@k by mode:\n\n**100,000 entities** (1×H100, `nomic-embed-text` on Ollama):\n\n| recall@k | keyword (BM25/FTS5) | dense | **hybrid (RRF)** |\n|---|---|---|---|\n| @1 | 0.003 | 0.680 | **0.785** |\n| @5 | 0.015 | 0.859 | **1.000** |\n| @10 | 0.029 | 0.899 | **1.000** |\n\nAt 100K entities, hybrid recall is **perfect @5 while keyword search lands ~1.5%\nof the time** — a **~66× gap**. And it *widens* with scale: at 10K entities keyword\nrecall@5 was 0.008 while hybrid was already 1.000; keyword-only memory silently\ndegrades as an agent accumulates history, hybrid (BM25 + dense + reciprocal-rank\nfusion) does not. This is the core argument for Perseus Vault's hybrid retrieval.\n\n**Head-to-head, same box, same corpus, all fully local** (1×H100, Ollama —\nidentical fact set, queries, and substring judge for every system):\n\n| System | Recall accuracy | p50 latency | Notes |\n|---|---|---|---|\n| **Perseus Vault** (hybrid) | **1.00** | 35.6 ms | single self-contained binary, in-process |\n| Letta (archival / pgvector) | 1.00 | 135.5 ms | server + Postgres/pgvector |\n| Mem0 (vector) | 0.60 | 37.9 ms | Python + vector DB |\n| Zep (Graphiti temporal KG) | 0.20 | 49.7 ms | server + Neo4j; graph extracted by local model |\n\nEvery competitor was **stood up and run live** on the same box against the same\nlocal Ollama (`qwen2.5:14b-instruct` + `nomic-embed-text`) — no cloud, no fabricated\nnumbers. Letta ran as the `letta/letta` server (bundled Postgres/pgvector) and matched\nPerseus Vault at 1.00. Zep's self-hosted Community Edition server is deprecated and its\n`zep_python` memory API is now Zep Cloud-only, so we measured Zep's actual OSS engine —\nGraphiti temporal KG on Neo4j — with entity/edge extraction *and* embeddings on the same\nlocal Ollama. Its 0.20 reflects the honest cost of building a knowledge graph with a\n**local** model (structured extraction is lossy: 5 entities / 2 edges from 6 facts) — not\nZep Cloud, which uses frontier models. Full artifact + methodology:\n[`benchmark/lambda/results/competitors.json`](benchmark/lambda/results/competitors.json).\n\n**Cold-start:** a bare GPU box reaches its **first grounded RAG answer in 3.3s**\n(models staged on disk).\n\nReproduce: [`benchmark/lambda/scale_bench.py`](benchmark/lambda/scale_bench.py) and\n[`competitors_bench.py`](benchmark/lambda/competitors_bench.py).\n\nDeploying beside a model server on a GPU host (vLLM on MI300X/H100)? See the\n[AMD MI300X deployment reference](docs/deployment-amd-mi300x.md) — measured\nco-residency numbers plus the `/dev/shm`, PID-1, and version-pinning gotchas\nthat break these stacks in practice.\n\n## Framework Integrations\n\nReady-to-use adapters that make Perseus Vault the default memory backend for\npopular AI agent frameworks:\n\n| Framework | Integration | Type |\n|---|---|---|\n| [**LangGraph**](integrations/langgraph/) | `MimirStore` | `BaseStore` implementation |\n| [**CrewAI**](integrations/crewai/) | `MimirMemoryTool` | Agent tool |\n| [**AutoGen**](integrations/autogen/) | `MimirMemory` | `Memory` implementation |\n\nEach adapter:\n- Connects via MCP stdio subprocess (persistent session)\n- Maps the framework's memory interface to Perseus Vault tools\n- Comes with a README quickstart (5 minutes to working)\n- Has passing tests with mocked MCP transport\n\nAny MCP-compatible framework works with Perseus Vault directly. See\n[Awesome Mimir](awesome-mimir.md) for the full list.\n\n## 55+ MCP Tools\n\n\u003e **Tool names \u0026 the `perseus_vault_` prefix.** The tables below use the\n\u003e historical `mimir_*` names, but by default the server now advertises each tool\n\u003e **once**, under its canonical `perseus_vault_*` name (e.g. `perseus_vault_remember`).\n\u003e The legacy `mimir_*` and `mneme_*` names remain fully *callable* — every prefix\n\u003e dispatches to the same handler — they are just no longer advertised in\n\u003e `tools/list`. This keeps the advertised manifest to one name per tool instead\n\u003e of tripling it (3× alias bloat), so connected clients don't reload a tripled\n\u003e tool-schema payload on every request. To restore the historical behaviour of advertising all three\n\u003e prefixes, set `PERSEUS_VAULT_TOOL_ALIASES=all` (the legacy env\n\u003e `MIMIR_TOOL_ALIASES` is also honoured; `PERSEUS_VAULT_` takes precedence).\n\u003e\n\u003e **Client compatibility (#633).** Clients that *gate on the advertised list* —\n\u003e they check `tools/list` before calling and skip tools they don't see — will\n\u003e silently skip legacy `mimir_*` calls against a 2.x vault even though the call\n\u003e itself would succeed. Known case: the `perseus` CLI **≤ 1.0.22** hard-codes\n\u003e `mimir_recall` and degrades to empty local-only recall. Fix either side:\n\u003e upgrade the CLI to **≥ 1.0.23** (calls canonical names, with dynamic\n\u003e fallback), or set `PERSEUS_VAULT_TOOL_ALIASES=all` on the vault as a bridge\n\u003e while older clients remain deployed.\n\n### Entity CRUD\n| Tool | Description |\n|---|---|\n| `mimir_remember` | Store/update entity. Idempotent by (category, key); a content change snapshots the prior version into history. |\n| `mimir_recall` | Search with FTS5/dense/hybrid modes, filters, stemming expansion. Query contract (#562): `query=\"\"` is match-all enumeration (the \"list all\" path); `\"*\"` and other wildcards are literal FTS5 terms, **not** globs — `\"*\"` matches nothing. |\n| `mimir_scan` | Deterministic paginated enumeration of a category or the whole store (#562): immutable `id ASC` keyset pages with a `next_cursor`/`has_more` contract, so export/sync/reset callers can walk every entity exactly once. Read-only — no retrieval-count/decay side-effects, no offset cap. |\n| `mimir_hygiene` | Read-only startup-memory hygiene report (#675): scores active memories by \"actionability\" (concrete anchors — issue keys, #refs, paths, URLs, decisions — vs vague/date-only/short) and lists the worst offenders with reasons, for archive/consolidate curation. |\n| `mimir_recall_layer` | Recall from a specific biomimetic layer (world, episodic, semantic). |\n| `mimir_recall_when` | Proactive just-in-time recall: surface entities whose `recall_when` triggers match. |\n| `mimir_get_entity` | Fetch one entity by ID with full `body_json`. |\n| `mimir_as_of` | Transaction-time time-travel: the version of a fact (category + key) that was *believed* at a past instant. |\n| `mimir_valid_at` | Valid-time lookup: the version that was *actually true in the world* at an instant, per current knowledge (SQL:2011 APPLICATION_TIME). |\n| `mimir_bitemporal` | Full 2-axis bi-temporal query: \"as of transaction time T, what did we believe was true at valid time V\" — the exact rectangle cell. |\n| `mimir_history` | List superseded versions of a fact (category + key), newest first — paginated (`limit` default 20, plus `offset`); `total` reports the full trail size (companion to `mimir_as_of`). |\n| `mimir_forget` | Soft-delete (archived=1). |\n\n### Search \u0026 RAG\n| Tool | Description |\n|---|---|\n| `mimir_ask` | RAG: recall context, query LLM, return grounded answer with sources. |\n| `mimir_embed` | Generate dense vectors via the bundled model, Ollama, or OpenAI-compatible endpoint. |\n| `mimir_semantic_search` | Dense-only semantic search shortcut — find entities by meaning, ranked purely by embedding similarity (no keyword fallback). |\n| `mimir_context` | Pre-formatted markdown block for session injection. Recall-first by default: pass `query` (the current task/message) and only topically relevant entities are injected, clamped to a per-model budget; the legacy unconditional dump requires `mode: \"always_inject\"`. |\n| `mimir_ingest` | Trigger connector syncs (GitHub, file watcher). |\n| `mimir_ingest_file` | Locally extract a document's text (plaintext/markdown always; DOCX/PDF with the `multimodal` feature) and store it as a recallable entity. |\n| `mimir_extract` | Local, deterministic, rule-based knowledge extraction (facts / preferences / temporal events / episodes) from text or a stored entity. Read-only. |\n| `mimir_capture` | Opt-in in-session capture (#520): distill a transcript/insight payload (text, markdown, or JSONL) into durable entities (root-cause / pitfall / decision / pattern / takeaway) the moment a problem is solved. Local rule-based distiller by default, optional `llm: true` with graceful fallback; near-dup merging stays ON plus a per-invocation cap (anti-flood). Also a CLI verb: `perseus-vault capture`. |\n| `mimir_memories` | Anthropic memory-tool compatible file interface (`view`/`create`/`str_replace`/`insert`/`delete`/`rename` under `/memories`), backed by vault entities. |\n\n\u003e 📖 **[docs/retrieval-modes.md](docs/retrieval-modes.md)** — one enumerated reference for every retrieval mode (keyword · dense · hybrid · graph · GraphRAG · proactive `recall_when` · temporal `as_of`): mechanism, when to use, invocation, and examples.\n\n### Graph\n| Tool | Description |\n|---|---|\n| `mimir_link` | Create typed relationship links between entities. |\n| `mimir_unlink` | Remove entity links. |\n| `mimir_traverse` | Walk entity link graph up to configurable depth. |\n| `mimir_communities` | GraphRAG community detection over the link graph (deterministic label propagation or greedy-modularity \"louvain\"; pure Rust, offline). |\n| `mimir_community_summary` | Extractive (optionally LLM-polished) summary of one community, materialized as an entity with `evidence_for` links to members. |\n| `mimir_global_recall` | GraphRAG global search: breadth over community summaries, then depth into the best communities' members — holistic answers across clusters. |\n\n### Journal\n| Tool | Description |\n|---|---|\n| `mimir_journal` | Append structured event with actor attribution. |\n| `mimir_check_failure_pattern` | Deja-vu guard: check an action against previously recorded failures (journal + failure/pitfall entities) before retrying it. Read-only. |\n| `mimir_timeline` | Query journal by time range with filters. |\n\n### State\n| Tool | Description |\n|---|---|\n| `mimir_state_set` | Set key-value state with optional TTL. |\n| `mimir_state_get` | Get state value. Returns null if expired. |\n| `mimir_state_delete` | Delete state entry. |\n| `mimir_state_list` | List state keys, optionally filtered by prefix. |\n\n### Lifecycle\n| Tool | Description |\n|---|---|\n| `mimir_decay` | Recalculate Ebbinghaus decay scores (batched 1000-entity transactions). |\n| `mimir_prune` | Bulk archive by category, decay threshold, or age. |\n| `mimir_purge` | Permanently delete archived entities + VACUUM. Destructive. |\n| `mimir_cohere` | Autonomous coherence grooming pass — promote, decay, link, archive. |\n| `mimir_autocohere` | Full atomic grooming: cohere → decay → compact in one pass (supports dry-run). |\n| `mimir_compact` | Archive entities below decay threshold. |\n| `mimir_reindex` | Rebuild FTS5 search index from entities table. |\n| `mimir_consolidate` | Merge overlapping/duplicative entities in a category into durable, evidence-tracked observations (mirror image of `mimir_conflicts`). |\n| `mimir_dream` | Sleep-time LLM consolidation: reflect over clusters of related episodic memories via the configured LLM and write back durable semantic insights, provenance-linked to every source. Idempotent (evidence-set hash), contradiction-aware, bounded; requires `--llm-endpoint`. |\n\n### Quality\n| Tool | Description |\n|---|---|\n| `mimir_score` | Assign quality score (0.0-1.0). |\n| `mimir_conflicts` | Detect conflicting entities via trigram similarity; opt-in `resolve=true` invalidates the lower-certainty side into history (reversible, dry-run by default). |\n| `mimir_correct` | Structured correction capture for learning from errors. |\n| `mimir_supersede` | Mark a new fact as superseding an old one (sets the old entity to `deprecated`). |\n| `mimir_follow` | Record whether an entity was actually FOLLOWED or MISSED — follow-rate efficacy signal that feeds both decay scoring and outcome-weighted recall ranking (#681). |\n\n### Keystones (policy rules)\n| Tool | Description |\n|---|---|\n| `mimir_keystone_set` | Author a Keystone — a mandatory policy rule that survives context compaction (#683). Scoped (tenant/fleet/agent), weight-ranked, crypto-chained on every mutation; authoring is trust-tier-gated. |\n| `mimir_keystone_get` | Fetch the merged Keystones for a scope, ordered by weight (highest first) then scope specificity — the deterministic session-start counterpart to recall. A renderer injects these ahead of all other context. |\n| `mimir_agent` | Register/update or look up an agent in the multi-agent registry (#684): identity + trust tier (0-3) + fleet. Trust tier gates sensitive ops (e.g. authoring keystones needs tier ≥ 2) and drives visibility enforcement on recall. |\n\n### Vault \u0026 Federation\n| Tool | Description |\n|---|---|\n| `mimir_vault_export` | Export entities to .md files with YAML frontmatter. |\n| `mimir_vault_import` | Import from .md vault directory (idempotent). |\n| `mimir_federate` | Copy entities between workspaces. This is a local export / workspace-rename / re-import (file based, no network peers); the Windows-safe default path is tracked in #704. |\n| `mimir_share` | Share one entity (by category + key) into another workspace, preserving content. |\n| `mimir_workspace_list` | List all distinct entity categories. |\n\n### Metrics \u0026 Ops\n| Tool | Description |\n|---|---|\n| `mimir_stats` | Full DB statistics across all tables. |\n| `mimir_health` | Server and DB health check. |\n| `mimir_bench` | Performance benchmark tracking. |\n| `mimir_maintenance` | DB maintenance: dedup, orphan detection, VACUUM, FTS5 reindex (supports dry-run). |\n| `mimir_synthesize` | LLM session synthesis — extract lessons from transcripts. |\n| `mimir_migrate` | Migrate v0.1.x DB to current schema. |\n\n## CLI\n\n```bash\n# Server\nperseus-vault serve --db /data/perseus-vault.db\nperseus-vault serve --web --port 8767 --encryption-key ~/.mimir/secret.key\nperseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3\nperseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token\n\n# Maintenance (operate directly on DB, no server needed)\nperseus-vault stats          --db /data/perseus-vault.db\nperseus-vault forget         --db /data/perseus-vault.db --category decision --key stale-choice --reason \"superseded\"\nperseus-vault prune          --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run\nperseus-vault purge          --db /data/perseus-vault.db --dry-run\nperseus-vault decay          --db /data/perseus-vault.db\nperseus-vault reindex        --db /data/perseus-vault.db\nperseus-vault vault-export   --db /data/perseus-vault.db --vault-dir ./export/\nperseus-vault vault-import   --db /data/perseus-vault.db --vault-dir ./export/\nperseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/          # one-shot export to an Obsidian vault\nperseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/ --watch  # continuous sync on every memory change\n\n# Key management\nperseus-vault keygen --key-file ~/.mimir/secret.key\n```\n\n\u003e **Manual DB edits.** The maintenance verbs above and the normal MCP write path\n\u003e keep the FTS5 index in sync automatically. Editing the `entities` table\n\u003e **directly** with `sqlite3` (a manual `DELETE`/`UPDATE`) bypasses that sync and\n\u003e can leave orphaned index rows — \"ghost\" recall hits for content that is already\n\u003e gone. After any direct SQL edit, run `perseus-vault maintain --db \u003cpath\u003e` (or\n\u003e `perseus-vault reindex`) to reconcile the FTS index.\n\n### Flags\n\n| Flag | Description |\n|---|---|\n| `--db` | SQLite database path (default: `~/.mimir/data/perseus-vault.db`) |\n| `--web` | Start web dashboard |\n| `--port` | Dashboard port (default: 8767) |\n| `--web-bind` | Dashboard bind address (default: 127.0.0.1) |\n| `--transport` | MCP transport: `stdio` (default), `sse`, or `http` |\n| `--mcp-token` | Bearer token for SSE/HTTP transport auth |\n| `--encryption-key` | AES-256-GCM key file path |\n| `--llm-endpoint` | LLM API endpoint for `mimir_ask` and embeddings |\n| `--llm-model` | LLM model name (default: llama3) |\n| `--llm-api-key` | API key for LLM endpoints (OpenAI, Azure, etc.) |\n| `--embedding-endpoint` | OpenAI-compatible embedding endpoint |\n| `--connectors-config` | Path to connectors.yaml |\n\n### Database location\n\nThe **canonical** database path is:\n\n```\n~/.mimir/data/perseus-vault.db\n```\n\nAlways pass `--db` (or set `$MIMIR_DB_PATH`) in scripts, MCP host configs, and\ncron/harvest jobs so every invocation targets the same file. When neither is\nset, Perseus Vault resolves the default in this order and uses the **first that\nalready exists** (so upgraders and legacy single-user installs are picked up\ninstead of silently starting empty):\n\n1. `~/.mimir/data/perseus-vault.db` — canonical (current name)\n2. `~/.mimir/data/mneme.db` — pre-rename\n3. `~/.mimir/data/mimir.db` — pre-rename\n4. `~/mimir.db` — legacy single-user install location\n\nIf none exist, it creates `~/.mimir/data/perseus-vault.db`. If **more than one**\nof these exists and you did not pass `--db`/`$MIMIR_DB_PATH`, Perseus Vault\nprints a stderr warning naming the chosen file and the others it ignored, so an\nambiguous multi-database state is visible rather than silent. Setting `--db` or\n`$MIMIR_DB_PATH` explicitly always wins and suppresses the warning.\n\n## Your AI Memory in Obsidian\n\nPerseus Vault is your AI agent's long-term memory — and it doubles as **your** second\nbrain. Every entity your agent remembers exports to a plain Markdown note with\nYAML frontmatter, so your AI's memory becomes a navigable personal knowledge\nbase inside the tools you already use: **Obsidian, Logseq, or Notion.**\n\n```bash\n# Export your entire memory to an Obsidian vault as linked Markdown notes\nperseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/\n\n# Keep it live — re-export automatically on every memory change\nperseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch\n```\n\nOpen the vault in Obsidian and you get a graph of your agent's knowledge.\n\n**WikiLink backlinks.** When one entity links to another (via `mimir_link` or a\n`depends_on` / `implements` / `references` relationship), the exported note gets\na `## Links` section with `[[WikiLink]]` backlinks that resolve natively in\nObsidian's graph view:\n\n```markdown\n---\nid: cli-de8dfb8364b6\ncategory: architecture\nkey: api\ntype: insight\ndecay_score: 0.5000\n---\n\n{\"content\":\"axum service\"}\n\n## Links\n\n- [[cli-99756b494c7d|database]] (depends_on)\n```\n\nLinks resolve **by entity id** (notes are written as `\u003cid\u003e.md`) so they never\nbreak, and Obsidian shows the human-readable `key` as the link label. Open the\ngraph view and your agent's architecture, decisions, and insights become a\nclickable knowledge map.\n\n**`--watch`** polls Perseus Vault's cheap, deterministic state digest on an interval and\nre-exports only when memory actually changes. It naturally catches every\n`mimir_remember` write with no filesystem-watcher dependency and no coupling to\nthe server. Tune the interval with `MIMIR_SYNC_INTERVAL_SECS` (default: 2s).\n\n### Other PKM tools\n\n| Tool | How |\n|---|---|\n| **Obsidian** | `perseus-vault obsidian-sync \u003cvault\u003e` — WikiLinks resolve in the graph view out of the box. |\n| **Logseq** | Point `obsidian-sync` at your Logseq graph directory. Logseq reads the same `[[WikiLink]]` syntax and Markdown frontmatter. |\n| **Notion** | Run `perseus-vault vault-export`, then use Notion's *Import → Markdown \u0026 CSV* to pull the notes in. |\n\nUnlike cloud-only \"second brain\" tools, Perseus Vault runs **100% local**, is written in\n**Rust**, encrypts at rest with **AES-256-GCM**, and applies **decay scoring** so\nstale memories fade — your knowledge base stays yours and stays fresh.\n\n## Features\n\n### Semantic Search (on by default)\n- **Bundled, in-process embeddings** — a quantized all-MiniLM-L6-v2 model\n  (384-dim) is compiled into the binary, so dense/semantic search works with\n  **zero config and zero network**: no Ollama, no API key, no model download.\n  This is the default build (`bundled-embeddings` feature).\n- **Auto-embed on write (#271)** — `mimir_remember` embeds each new (or\n  content-changed) entity **synchronously** as it is written, using the bundled\n  model. Single-entity embedding is deterministic and LRU-cached, so it is cheap\n  and adds no background tasks. Embedding failures are non-fatal (logged to\n  stderr); the write always succeeds.\n- **Hybrid is the default recall mode (#271)** — `mimir_recall(query=...)` with\n  no `mode` flag automatically selects **hybrid** (dense + keyword fused via RRF)\n  whenever embeddings exist, and transparently falls back to **fts5** keyword\n  search when none do. No manual `mimir_embed` step, no flags to remember.\n- **`mimir_semantic_search(query, limit)`** — a one-tool shortcut for pure\n  dense, meaning-based search (no keyword fallback) when you just want \"find\n  things like this\".\n- **Optional alternate embedder** — to use **Ollama** or any OpenAI-compatible\n  `/v1/embeddings` endpoint instead of the bundled model, set `--llm-endpoint`\n  (and `--embedding-endpoint` / `--llm-api-key` as needed). This is entirely\n  optional; the bundled model is used by default.\n- Build a lean binary without bundled embeddings via\n  `cargo build --no-default-features` — recall then defaults to keyword search\n  unless a remote embedder is configured.\n\n### Hybrid Search internals\n- **FTS5 keyword search** with LIKE fallback and Porter stemming expansion\n- **Dense vector search** via cosine similarity on stored embeddings\n- **Reciprocal Rank Fusion (RRF)** — combine keyword + vector results\n- **Query expansion** — automatic stemming variants for broader recall\n### Memory Lifecycle\n\nPerseus Vault models memory using three biomimetic layers, inspired by human memory pathways:\n\n- **World (Core):** Slow-decaying, global facts about the environment.\n- **Episodic (Buffer):** Fast-decaying, session-specific interaction history.\n- **Semantic (Working):** Medium-decaying, general knowledge and learned concepts.\n\nYou can interact with these layers directly using the `mimir_recall_layer` tool or by specifying the `layer` parameter in `mimir_remember`.\n\n- **Ebbinghaus decay** — memories naturally fade unless retrieved (refresh on access)\n- **Layer promotion** — buffer → working → core based on access frequency\n- **Automatic archival** — stale entities archive; purge to permanently delete + VACUUM\n- **Always-on entities** — pin identity-critical memories for session injection (hard-capped under recall-first; prefer `recall_when` triggers)\n\n### Recall-First Context Injection\n\nThe vault is the query layer — it retrieves the few facts a turn needs instead of\nhanding the host a standing blob to staple into every system prompt.\n`mimir_context` and `perseus-vault prepare` are **recall-first by default**:\n\n- **Relevance gating** — pass `query` (the current task/message) and only entities\n  whose `recall_when` triggers or indexed content match it are injected. No query,\n  no topical injection: the block is a compact retrieval pointer, byte-stable\n  across unrelated vault writes (prefix-cache friendly).\n- **Per-model recall budget** — output is clamped to a character budget resolved\n  from the host model: default/lean profile 1500 chars; large-window (\"opus\")\n  profile 6000 chars; `max_context_chars` overrides both.\n- **Capped always-on** — `always_on: true` still works for identity-critical\n  facts, but the recall-first set is hard-capped (top 5) and overflow emits a\n  warning steering you to `recall_when` triggers.\n- **Legacy opt-in** — the old unconditional top-N dump is still available with\n  `mode: \"always_inject\"` (`--legacy-context` for `prepare`), unclamped unless\n  you pass a budget.\n\n```bash\nperseus-vault prepare --task \"deploying the payments service\" --model claude-sonnet-4-6\nperseus-vault prepare --task \"...\" --max-context-chars 800     # explicit budget\nperseus-vault prepare --task \"...\" --legacy-context            # old dump, opt-in\n```\n\n### RAG \u0026 Embeddings\n- **`mimir_ask`** — natural language Q\u0026A over stored memories via any LLM (Ollama, OpenAI, etc.)\n- **`mimir_embed`** — generate and store dense vectors via Ollama or OpenAI-compatible `/v1/embeddings`\n- Supports single-entity and batch-category embedding\n\n### Encryption\n- **AES-256-GCM** transparent encryption for entity `body_json`\n- Opt-in via `--encryption-key` flag\n- `perseus-vault keygen` subcommand for key generation\n- FTS5 index stays plaintext for search\n\n### Web Dashboard\n- Built-in Axum HTTP server (`perseus-vault serve --web --port 8767`)\n- Dark-themed dashboard with search, entity table, vis.js graph, timeline\n- Default bind: `127.0.0.1` (use `--web-bind 0.0.0.0` to expose)\n- Separate SQLite connection in WAL mode for concurrent reads\n\n### External Connectors\n- **GitHub issues connector** — ingest issues/PRs by repo, rate-limit aware\n- **File watcher** — scan directories for `.md`/`.txt`/`.json` files with content-hash dedup\n- YAML-based connector config via `--connectors-config`\n\n### Multi-Transport\n- **stdio** (default) — zero-config, works with any MCP host\n- **SSE** — Server-Sent Events for HTTP-based MCP clients\n- **HTTP** — REST-style MCP endpoint\n- **Bearer token auth** — for SSE/HTTP transports\n\n## Perseus Integration\n\nPerseus Vault is the default memory backend for [Perseus](https://perseus.observer):\n\n```yaml\nmimir:\n  enabled: true\n  transport: \"stdio\"\n  command: [\"perseus-vault\", \"serve\", \"--db\", \"~/.mimir/data/perseus-vault.db\"]\n  timeout_s: 30.0\n  merge_strategy: \"local_first\"\n  fallback_to_local: true\n  context_categories: [\"decision\", \"architecture\", \"convention\"]\n  context_limit: 10\n```\n\n## Government \u0026 Federal Procurement\n\nPerseus Vault is built for government deployment from the ground up.\n\n| Capability | Status |\n|---|---|\n| **License** | MIT — no copyleft, no GPL/AGPL |\n| **SBOM** | [Published](./docs/SBOM.md) — NTIA minimum elements |\n| **Air-gapped** | Fully offline — no telemetry, no API calls, no network by default |\n| **Encryption at rest** | AES-256-GCM, transparent, opt-in |\n| **Audit trail** | Immutable journal with chain-of-custody |\n| **Supply chain** | SLSA attestation in progress |\n\n**For federal buyers:** See [docs/federal-buyers.md](./docs/federal-buyers.md) for\nprocurement information, compliance status, and deployment models (air-gapped,\non-premises, classified environments).\n\nPerseus Computing LLC is a US-owned small business. SAM.gov registration in progress.\nNAICS: 541715, 541511, 541512.\n\n## Privacy Policy\n\nPerseus Vault is a **local-first MCP server** — it runs entirely on your machine.\n\n### Data Collection\n- **No data collection.** Perseus Vault does not collect, transmit, or phone home any user data, usage statistics, or telemetry.\n- All data remains in your local SQLite database file.\n\n### Data Usage \u0026 Storage\n- All memory entities, journal entries, and state are stored locally in a SQLite database at the path you specify via `--db`.\n- Optional **AES-256-GCM encryption at rest** is available — when enabled, entity bodies are encrypted before storage.\n- No data is shared with Perseus Computing LLC or any third party.\n\n### Third-Party Sharing\n- **None.** Perseus Vault is fully air-gapped by default. No API calls, no cloud services, no external network requests.\n- The optional dense vector embeddings feature uses a locally-compiled model — no external embedding API is called.\n\n### Data Retention\n- You control retention: entities can be soft-deleted (`mimir_forget`), archived (via decay/compact), or permanently purged (`mimir_purge`).\n- No automatic off-machine backup is performed.\n\n### Contact\n- **Email:** privacy@perseus.observer\n- **GitHub:** [Perseus-Computing-LLC/perseus-vault](https://github.com/Perseus-Computing-LLC/perseus-vault)\n\n## Release Verification\n\nRelease binaries are built from tagged commits via [GitHub Actions](.github/workflows/release.yml). Every release ships:\n\n| Artifact | Description | Verification |\n|----------|-------------|-------------|\n| `perseus-vault-\u003ctarget\u003e.tar.gz` | Full build (bundled embeddings, glibc) | SHA-256 checksum in `.sha256` sidecar |\n| `perseus-vault-lite-\u003ctarget\u003e.tar.gz` | Lean build (`--no-default-features`, musl/static) | SHA-256 checksum in `.sha256` sidecar |\n| SLSA provenance attestation | Sigstore-signed build provenance | `gh attestation verify \u003carchive\u003e --repo Perseus-Computing-LLC/perseus-vault` |\n\n### Verify a release binary\n\n```bash\n# 1. Verify SHA-256 checksum\nsha256sum -c perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz.sha256\n\n# 2. Verify SLSA build provenance (requires gh CLI + OIDC session)\ngh attestation verify perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz \\\n  --repo Perseus-Computing-LLC/perseus-vault\n\n# 3. Confirm the binary identity\n./perseus-vault --version\n# Should show both the release version AND the git commit hash, e.g.:\n#   perseus-vault 2.20.2 (v2.20.2-0-gabcdef1)\n\n# 4. Confirm the doctor reports the same identity\n./perseus-vault doctor --db /tmp/test.db | head -1\n#   perseus-vault doctor — v2.20.2 (v2.20.2-0-gabcdef1)\n```\n\n### Build reproducibly from source\n\n```bash\n# The exact same binary (bit-for-bit) requires matching:\n#   - Rust toolchain version (see rust-toolchain.toml)\n#   - Locked dependencies: `cargo build --locked`\n#   - Build flags: `--release` for release builds\n\ncargo build --locked --release\n./target/release/perseus-vault --version\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPerseus-Computing-LLC%2Fperseus-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPerseus-Computing-LLC%2Fperseus-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPerseus-Computing-LLC%2Fperseus-vault/lists"}