engram-vault 0.3.2

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

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"] } } }

Teach your agent to remember

Copy this straight into your agent's system prompt (CLAUDE.md, custom instructions, anywhere it reads on boot):

You have Engram, a local-first shared memory, available over MCP
(tools: add, search, recall, register_agent, send_message, inbox, ...).

Recall — at the start of any substantive task, and whenever prior context
would help (past decisions, projects, people, preferences), call `search`
with a few keywords before answering.

Capture — when you produce knowledge worth keeping (facts about the user,
decisions, learnings, debugging breakthroughs), call `add` without asking.
One atomic fact per add. Tag consistently: project:<name>, person:<name>,
pref, decision, learning. Set source to your client name.

Fleet (optional) — call `register_agent` once per session to join the team
brain under a stable name; check `inbox` for teammate messages and reply
with `send_message`. Never claim another agent's name.

That's the whole onboarding: recall before answering, capture liberally, identify honestly.

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