al-buddy-memory

Al Buddy — that's Al, a name, said like "pal". Not A.I.

A memory that's yours.

Portable, governed, model-agnostic memory for AI agents.

A fact is invalidated, never overwritten; on a governed handle, erasure runs through policy and is audited. Raw text is the source of truth and cannot be edited. Embeddings are a disposable, model-tagged cache. Every fact and every link exports to one documented format. The memory outlives whatever model, runtime or company produced it.

---

Why this exists

Every agent-memory product on the market answers one question well: what does the agent recall? None of them answers the four questions that decide whether you can trust and keep that memory:

| Question | This library | Letta | Mem0 | Zep | |---|---|---|---|---| | Where did this fact come from, and who asserted it? | Provenance on every node and edge (UserInput / AIInferred / GuardianAdded / SystemGenerated) | Memory-file git history | Metadata field | Graph episodes | | When was it true, and what replaced it? | Two queryable axes: validAt answers what was true at Y; getNodeAsOf / snapshotAsOf answer what the store believed at X from full before/after versions. They combine in one call (snapshotAsOf(X, { validAt: Y })), a read the history cannot vouch for is marked, and erasure removes the history too | Git history of files, not a fact model | Change history per memory (history(): old value, new value, event, timestamps) — transaction history, not valid time | Temporal graph (its real strength): Graphiti edges carry valid_at / invalid_at alongside created_at / expired_at | | Can I take it with me, losslessly, to another runtime? | One versioned JSON export with a published schema and conformance tests | .af (agent state, framework-shaped, archival memory not yet included) | Cloud export | Cloud-only since 2025 | | Does it run with no vendor, no key, no server? | SQLite on disk, on-device embeddings | Self-host possible; cloud is the product | Self-host possible (Apache-2.0, local vector stores); needs an LLM for extraction; cloud is the product | Zep is cloud; Graphiti self-hosts (graph DB + LLM key required) |

Sources for the cells above, each checked against the project's own code or announcement on 2026-09-18: Mem0's per-memory history is a SQLite table with old_memory, new_memory, event, created_at, updated_at (mem0/memory/storage.py); Mem0 is Apache-2.0 and runs against local vector stores including Qdrant, Chroma, pgvector and FAISS (vector-store docs), with an LLM called to extract facts on the default add() path. Zep stopped maintaining Community Edition on 2025-04-02, in its own words: "we've decided to stop maintaining and releasing Zep Community Edition." Graphiti, the engine under Zep, is Apache-2.0 and self-hosts, and its stated requirements are a graph database (Neo4j, FalkorDB, Amazon Neptune, or the deprecated Kuzu) plus an LLM key — it "defaults to OpenAI for LLM inference and embedding."

The three local, keyless ones people will name, read against their own code on 2026-09-21. They answer the fourth question the way this library does — your machine, your files, no account — and they are the honest comparison, not the cloud products.

• basic-memory (AGPL-3.0; Markdown notes on disk are the truth, SQLite is a rebuildable index). It has valid time, and that is worth saying plainly: an observation can carry @effective[2026-06-10,2026-07-27) in the note itself, parsed into a time index (models/knowledge.py) and rebuilt from the file, so the file stays the source of truth. What it does not carry on a local install is who asserted a fact: created_by / last_updated_by exist and hold a cloud user id, null for local and CLI use. Portability is the strongest kind and the least specified: the notes are the format, so nothing is trapped, and there is no versioned schema to import them into something else. Capture and full-text search need no key; semantic search is opt-in and does.
• The MCP memory server (the reference implementation most agents meet first; one JSONL file). Entities, relations and observations, and nothing else: no field for who said it, no timestamps at all, and deleteObservations filters the old value out of the array, so what was true before is gone rather than closed. The file is its own export. Nothing calls a model; nothing leaves the machine.
• Memori (Apache-2.0; your own SQL database — SQLite, Postgres, MySQL, Oracle). A fact in memori_entity_fact has content, an embedding, a count and a last-seen date; who asserted it is only recoverable by walking the foreign keys back to a conversation message, not a property of the fact, and there is no valid time — date_updated replaces. "Your data stays in your database" is the portability story, with no interchange format published. It is local in the sense that matters for your data, but capture is not keyless: extraction and embeddings call an LLM, and the default SDK path expects a Memori account as well.

Also worth naming: OpenMemory MCP (Mem0, launched May 2025) shipped the same distribution idea — one local memory store shared across MCP clients — and Mem0 archived it; its README now opens "This project has been archived." Its schema is the contrast this table is about: models.py gives a memory content, created_at, updated_at, archived_at, deleted_at and a state, with no field for who asserted the fact and no valid time, and content is rewritten in place on update. It does keep a state-transition history and an access log, and it does have a ZIP export — so it is not the absence of portability that separates the two, it is provenance, valid time and an immutable raw.

Recall benchmarks (LOCOMO, LongMemEval, DMR) measure what an agent remembers. None of them scores a memory system on provenance, invalidation or portability. This library is built for that axis, and the conformance scorer below is one attempt at measuring it. The table is our reading of each project's own code and public docs, dated above; if we have a cell wrong, a PR with a link fixes it.

We run LongMemEval anyway, so a recall number people recognise sits beside the conformance score rather than in place of it, along with a small benchmark of our own for the part recall benchmarks skip: when a fact changes, does recall return the value that is true now? See Benchmarks.

Start here

An empty memory gives an assistant nothing to stand on. docs/STARTER.md seeds yours in ten minutes: pin who the person is and how they want to be treated (including "never a yes-person"), choose the rules the store enforces, and let it derive the rest nightly.

Upgrading from an earlier version: CHANGELOG.md marks anything that changes what an existing caller gets back. 0.4.0 has breaking changes (immutable content, governed erasure, a new listNodes on the store interface, the MCP exports moved to al-buddy-memory/mcp), so read that entry before you upgrade.

What is in the box

• MemoryStore: a storage-agnostic interface; SqliteMemoryStore and InMemoryStore ship, with a conformance suite any backend can run against itself.
• ProjectMemory: one brain scoped by project or person, each in its own SQLite file.
• HybridRetriever: lexical + semantic recall with decay-aware confidence; embeddings on-device via transformers.js (no API key). Recall can be scoped (memory type, tags, minimum confidence, privacy and retention tiers), and the scope applies to the keyword and the vector side alike. Two opt-in aids for questions whose answer is spread across conversations, both computed at read time and never stored: a reranker (LocalReranker, an on-device cross-encoder) that rereads the question with each candidate and reorders them, and expand, which reads a question's time and counting cues (analyzeQuery: "in April", "the past two weeks", "how many", "A and B") and recalls for each.
• exportPortable / importPortable: the lossless interchange format, versioned, with a JSON Schema.
• PinnedBlocks: a size-capped tier of facts that belong in every prompt, editable by the agent itself, on top of the governed store.
• consolidate: a sleep-time pass that reads recent raw memory and writes new derived facts with provenance edges back to their sources; the raw is never rewritten and nothing is summarised away.
• verifyDerived: every conclusion stores the exact words it rests on (evidence), checked when it is written; this re-checks them any time, and retracts, never deletes, one whose evidence no longer holds.
• Mental models: standing questions with answers kept current in the background, so reading one costs no model call (defineMentalModel, refreshMentalModels, getMentalModel). Every answer quotes the facts it rests on, keeps its history ("what did we think in June"), and reads as stale the moment one of those facts stops being true or is erased.
• Current state: "where does X stand now?" held as one live memory per subject (recordState, currentStates, statesMentionedIn). A newer state closes the one it replaces and keeps it as history; a state that arrives late never overturns a newer one. Recall can also weigh recency (freshness), so the newest of several matching notes comes first.
• explainFact: why a fact is believed, in one call — provenance and origin, validity and what replaced it, a conclusion's evidence with each quote checked, and its history. Through a governed handle a source the reader may not see is named as withheld, never shown.
• Conclusions go with their facts: a fact that stops being true retracts what was concluded from it (kept, marked); a fact that is erased takes everything built from it (SPEC §8a).
• listConsolidations / undoConsolidation: review what each pass concluded, with the evidence for every fact, and take back one pass's conclusions. Undo retracts (validTo) and records who withdrew each fact and why; it never deletes, so the history still shows what was believed, when it was withdrawn, and the reason.
• buildSourceProvenance / readSourceProvenance, renderMemoryBlock, exportMemoryMarkdown, decay helpers.
• Integrations: al-buddy-memory/ai-sdk (Vercel AI SDK tools + middleware), al-buddy-memory/langchain (a LangGraph long-term memory store + LangChain tools), al-buddy-memory/mastra (an input processor + tools). The frameworks are optional peer dependencies; every write is governed and records which agent made it. Guides in docs/integrations.

Node ≥ 20. One runtime dependency (better-sqlite3, with prebuilt binaries for Node 22, 24, 25 and 26 on macOS, Linux and Windows; on Node 20 it compiles from source, which needs Python and a C++ toolchain). Postgres (pg), the MCP SDK and the on-device model (transformers.js) are optional: they load only if you use them, and npm install --omit=optional leaves them out.

Prior art: the Letta project published the idea of a pinned memory tier and a background pass over memory (memory b