engram-vault 0.3.1

Engram — local-first personal memory layer for AI agents: markdown vault + hybrid retrieval, exposed over MCP.

Engram

A local-first shared brain for AI agents. One markdown file per fact, on your disk — written and recalled by every agent on your machine over MCP, and by you with grep.

pip install engram-vault          # or: uvx engram-vault

Wire it into Claude Code in one line:

claude mcp add engram --scope user -- uvx engram-vault

Or any MCP client:

{ "mcpServers": { "engram": { "command": "uvx", "args": ["engram-vault"] } } }

Why

Agents forget everything between sessions, and every framework wants to own your data in a database you can't read. Engram inverts both: memory is plain markdown in a folder you own (~/Library/Application Support/KB, or KB_DIR), with retrieval and coordination layered on top — no lock-in, no cloud, greppable forever.

What you get

Memory — add / update / supersede / pin facts with tags, scopes, and entity links. Confidence decays unless reinforced; superseded facts keep their history.

Retrieval that's actually fast — hybrid search (semantic ⊕ BM25 ⊕ entity) fused with reciprocal-rank fusion and MMR diversification: ~140 ms warm on a 9k-fact vault. recall is the "ask your memory" verb.

A real multi-agent layer — multiple agents (Claude Code sessions, apps, workers) share one vault as a team brain:

• Authenticated identity (TOFU) — first register_agent mints a per-name token (sha256-only at rest); every message is stamped via: with the authenticated sender, and presence shows verified only when proven. Impersonation can't hide.
• Messaging, handoffs, rooms — DMs, broadcasts, threads, ticket-style handoffs with read/done status, membership-gated rooms.
• Wake on send, not polling — a message fires the recipient's alarm (desktop banner, SMS, in-app queue, or re-invoked agent session). Pollers that remain use inbox(since=…) cursors: an idle tick reads zero files.
• Fleet views — engram CLI (kb agents, kb feed equivalents via the engram entry point) and kb top, a full terminal mission control (fleet, ticket kanban, live comms).

Contracts, not conventions — COORD.md documents the wire format any second implementation must honor; a bundled agent skill teaches the full protocol so a new agent can join the fleet cold.

The dogfood loop

Engram is built by the agent fleet that runs on it — the same vault coordinating its own development surfaced and fixed a thread-loading bug, an unauthenticated-sender gap, and a GC regression within hours of each shipping. The traces are the QA.

Links

• Source & docs: https://github.com/arjan-experiments/kb
• Changelog: https://github.com/arjan-experiments/kb/blob/main/CHANGELOG.md
• License: Apache-2.0