al-buddy-memory

# al-buddy-memory

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/flytomoon/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`](https://github.com/mem0ai/mem0/blob/main/mem0/memory/storage.py)); Mem0 is Apache-2.0 and runs against local vector stores including Qdrant, Chroma, pgvector and FAISS ([vector-store docs](https://docs.mem0.ai/components/vectordbs/overview)), 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](https://blog.getzep.com/announcing-a-new-direction-for-zeps-open-source-strategy/): *"we've decided to stop maintaining and releasing Zep Community Edition."* [Graphiti](https://github.com/getzep/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](https://github.com/basicmachines-co/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`](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/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](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)** (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](https://github.com/GibsonAI/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](https://github.com/mem0ai/openmemory/tree/main/openmemory-archive)** (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`](https://github.com/mem0ai/openmemory/blob/main/openmemory-archive/api/app/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](#benchmarks).

## Start here

An empty memory gives an assistant nothing to stand on. [docs/STARTER.md](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](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](docs/portable-format.schema.json).
- `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`, `current