Provides governed, model-agnostic local memory for AI agents with full provenance, temporal validity, and lossless portability.
Also known as flytomoon/al-buddy-memory
- Stars
- 3
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- 0.12.0
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is al-buddy-memory MCP?
al-buddy-memory provides governed, model-agnostic local memory for AI agents with full provenance, temporal validity, and lossless portability. It exposes 11 tools, such as remember, recall, history.
Summary generated from the project's README
About al-buddy-memory MCP server
al-buddy-memory provides a governed, model-agnostic memory system designed for AI agents that require high levels of trust and data integrity. Unlike standard memory solutions, this server treats raw text as the immutable source of truth and uses embeddings only as a disposable cache. It operates locally using SQLite on disk, ensuring that your data remains on your machine without requiring external API keys or cloud accounts.
Developers can use this tool to manage agent knowledge through specific mechanisms like PinnedBlocks for essential facts and a consolidate process that derives new facts from raw memory without overwriting the original text. The system tracks provenance for every piece of information, noting whether a fact was a UserInput, AIInferred, GuardianAdded, or SystemGenerated. It also supports temporal validity, allowing agents to query what was true at a specific point in time using tools like snapshotAsOf. This makes it ideal for building agents that need to maintain a verifiable and portable history of their interactions.
What you can do with it
- 1Maintain temporal accuracyQuery the memory store to determine what the agent believed to be true at a specific past date.
Written from the project's README. Every use case is checked against a quote from it.
How to install al-buddy-memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall al-buddy-memory MCP in Claude Code
$ claude mcp add --env 'AL_BUDDY_MEMORY_AUDIT_KEY=<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>' al-buddy-memory -- npx -y al-buddy-memory mcpInstall al-buddy-memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"al-buddy-memory": {
"command": "npx",
"args": [
"-y",
"al-buddy-memory",
"mcp"
],
"env": {
"AL_BUDDY_MEMORY_AUDIT_KEY": "<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"
}
}
}
}Install al-buddy-memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"al-buddy-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"al-buddy-memory",
"mcp"
],
"env": {
"AL_BUDDY_MEMORY_AUDIT_KEY": "<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"
}
}
}
}Install al-buddy-memory MCP in VS Code CLI
$ code --add-mcp '{"name":"al-buddy-memory","type":"stdio","command":"npx","args":["-y","al-buddy-memory","mcp"],"env":{"AL_BUDDY_MEMORY_AUDIT_KEY":"<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"}}'Install al-buddy-memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"al-buddy-memory": {
"command": "npx",
"args": [
"-y",
"al-buddy-memory",
"mcp"
],
"env": {
"AL_BUDDY_MEMORY_AUDIT_KEY": "<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"
}
}
}
}Install al-buddy-memory MCP in Codex
$ codex mcp add al-buddy-memory --env 'AL_BUDDY_MEMORY_AUDIT_KEY=<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>' -- npx -y al-buddy-memory mcpInstall al-buddy-memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.al-buddy-memory] command = "npx" args = ["-y", "al-buddy-memory", "mcp"] [mcp_servers.al-buddy-memory.env] AL_BUDDY_MEMORY_AUDIT_KEY = "<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"
Install al-buddy-memory MCP in Gemini CLI
$ gemini mcp add -s user -e 'AL_BUDDY_MEMORY_AUDIT_KEY=<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>' al-buddy-memory npx -- -y al-buddy-memory mcpInstall al-buddy-memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"al-buddy-memory": {
"command": "npx",
"args": [
"-y",
"al-buddy-memory",
"mcp"
],
"env": {
"AL_BUDDY_MEMORY_AUDIT_KEY": "<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for al-buddy-memory 0.12.0 in an isolated container with no network and no keys. It answered and listed 11 tools.
al-buddy-memory MCP tools 11
Read from the server with tools/listrememberActionStore a fact with its provenance. Returns the fact with validFrom, provenance and confidence, plus mayConflictWith: current facts this one may be correcting — read them and invalidate any that stopped being true.
recallRead-onlyFind facts. Every result says who asserted it, since when it has been true, whether it is still current, what superseded it, and which assistant wrote or retired it. The first call of a session, and the first after they change, also returns the user's pinned rules — treat those as standing rules for the conversation.
historyRead-onlyShow the recorded changes to one fact, including each change time and the full mutable state before and after it.
explainRead-onlyWhy a fact is believed: who asserted it, when it was true and what ended or replaced it, and for a conclusion the exact words it rests on, each checked against its source now.
mental_modelRead-onlyRead a standing question's pre-written answer (no model call): the answer, whether it is fresh or stale and why, and the exact words it rests on. Omit id to list every mental model.
define_mental_modelActionDefine a standing question to keep answered (e.g. "What does the user care about when choosing tools?"), optionally limited to facts carrying some tags. The host's scheduled refresh writes the answer.
invalidateActionA fact stopped being true: close its validity (never delete), optionally naming what replaced it.
pinActionPin a fact into the always-in-prompt tier. Only rules that belong in every conversation; it is a small, budgeted tier.
unpinActionUnpin a fact (its validity closes; it is kept).
pinnedRead-onlyThe pinned tier, as a list and as the rendered prompt block.
exportActionExport the user's memory in the portable format, with provenance and validity. Only when the user asks for an export or backup. Without a path it is returned inline if under 50000 bytes; otherwise give an absolute path ending in .json that does not exist yet (never overwrites).
Configuration
AL_BUDDY_MEMORY_AUDIT_KEYSecretOptional HMAC key for the audit chain. Keep it away from the trail.
AL_BUDDY_MEMORY_AUDITOptional JSONL file for the audit chain instead of the database's own table. One writing process per file.
AL_BUDDY_MEMORY_DBThe SQLite memory file. A leading ~ is expanded.
AL_BUDDY_MEMORY_INDEX_LIMITMost facts embedded in the background per start (0 skips it).
AL_BUDDY_MEMORY_MODEL_CACHEWhere the on-device embedding model (about 90 MB, downloaded once) is kept.
AL_BUDDY_MEMORY_OWNERWhose memory this is; the owner's policy applies to every call.
AL_BUDDY_MEMORY_PUBLIC_URLAL_BUDDY_MEMORY_SEMANTICSet to off for keyword-only recall; the on-device embedding model is then never downloaded.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubal-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_byexist 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
deleteObservationsfilters 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_facthas 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_updatedreplaces. "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;SqliteMemoryStoreandInMemoryStoreship, 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: areranker(LocalReranker, an on-device cross-encoder) that rereads the question with each candidate and reorders them, andexpand, 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 blocks; sleep-time agents). What is different here: every derived fact must cite the raw it rests on or it is refused, the raw is never rewritten, and a whole pass can be reviewed and undone, with the undo and its reason kept on record.
import { SqliteMemoryStore, ProjectMemory, PinnedBlocks, exportPortable } from "al-buddy-memory";
const store = new SqliteMemoryStore("./brain.db");
await store.addNode({ provenance: "UserInput", memoryType: "Lesson", content: { text: "Chris prefers decisions over options." }, /* …governance fields… */ });
const pins = new PinnedBlocks(store);
await pins.pin({ text: "Never present options without a recommendation.", label: "rule" });
const snapshot = await exportPortable(/* … */); // → docs/portable-format.schema.json
Full contract: docs/SPEC.md. Design record: docs/DECISION-2026-07-07.md.
Python, and other languages
The MCP server and the portable format are the language-neutral surface: a Python agent can use the governance server today, and any language can read the export (it is plain JSON with a schema). A native Python package is planned; open an issue if you need it sooner and say what you would use first.
License
Apache-2.0. See LICENSE.
Governance is enforced, not implied
The vocabulary — Public / Private / Sensitive / Sealed, retention tiers, provenance on
every fact and relation — ships with the store. govern() is what enforces it: policies
in front of every write, update, read and export, and an append-only audit trail of who
read what and why.
import { SqliteMemoryStore, govern, personalDefaults, storeAudit } from "al-buddy-memory";
const inner = new SqliteMemoryStore("brain.db");
const store = govern(inner, {
policies: [personalDefaults({ owner: "chris" })],
context: () => ({ actor: currentActor() }),
// The trail goes in the database, hash-chained, in the same transaction as
// the fact it describes. `new ChainedAudit("audit.jsonl")` puts it in a file
// instead — for a store that is not SQLite, or when you want it outside the
// file it describes. See docs/GOVERNANCE.md for what each one proves.
audit: storeAudit(inner),
});
To make sure nothing is ever erased by accident, add memoryLock() to the policies: while it
is there, erasure is refused for everyone, the owner included, until you take it out (or flip
the switch it reads). Invalidating a fact still works; that is not erasure. The raw store and
the database file are outside any policy, so keep backups.
And to make a deletion something you can take back, pass recentlyDeleted: { days: 14 } to
govern(): a delete then moves the fact out of recall for 14 days, restoreDeleted brings it
back, and purgeDeleted erases it for good once the days are up (asking the policies again, so
the lock still wins). Nothing runs on a timer, and until it is purged the fact is still in
exports and backups.
Check the trail with al-buddy-memory verify-audit brain.db. It names the first event that
was edited, removed, inserted or reordered. What it establishes, and the two things it does
not, are written out in docs/GOVERNANCE.md —
short version: the chain is tamper-evident; a tail cut off a log file is invisible to it,
a tail cut off the table is caught as long as nobody resets the table's own counter, and
only a head you anchor somewhere else catches a rewrite or a restored backup.
Three policies ship to copy: personal defaults (secrets auto-classified Sensitive; Sensitive facts never reach, leave with, or get erased by anyone but the owner in person; only the owner changes a fact), guardian mode (only a guardian may write or change a guardian's fact), enterprise audit (low-confidence inferences hidden from non-reviewers; exports gated to exporters). A policy is a plain object with five optional hooks; see docs/GOVERNANCE.md.
Without any policy the store still guarantees: Sealed facts never surface in a search unless
asked for by classification; provenance, nodeId, encryptionKeyRef, raw content and the
anchor trail are immutable after write, through every path including import; every instant is
stored in one canonical UTC spelling. Two things it does not do, said plainly: provenance is what
the writer asserts (immutable once written, not verified — bind actors to provenance in a policy);
and encryptionKeyRef names a key you manage, it does not encrypt the file.
The governed handle is the boundary. govern(store, …) puts policies in front of every
operation that can change a fact or reveal one — including erasure, which is refused unless a
policy explicitly allows it. Whoever holds the inner store is not governed by anything, so hand
out the governed one.
The rules an assistant on this memory is held to are published in docs/policies: ethical behaviour, user sovereignty and privacy, lifecycle and guardians, data stewardship — and an honest ledger of what the code enforces, what a prompt carries, and what is still a person's decision. They change in the open.
Enterprise
The same store for an organisation: a shared database, rules about who sees what, encryption the operator controls, and erasure on request. SQLite stays the default, and nothing here changes a local setup.
- Postgres.
PostgresMemoryStore(pgvector 0.8 or newer) sits behind the sameMemoryStoreinterface and passes the same conformance suite. Every read and write is confined to one tenant key, and the audit chain is kept per tenant in the same transaction as each governed write;verify-audit --postgres --tenant <key>checks it. A write reads and writes only the rows it acts on, so its cost does not grow with the tenant: measured flat from 1,000 to 100,000 facts (about 1–3 ms a write, 3–6 ms governed and audited, in-process PGlite). docs/POSTGRES.md - Boundaries. A policy can declare who sees what as data:
readBoundary, fact labels against the asking actor's attributes, with equality, membership, AND and OR. SQLite and Postgres compile it into their ownWHERE, before ranking and before anylimit, so facts outside it never take a place in a page. It fails closed, andbeforeReadstill has the final word. docs/policies/boundaries.md - Sign-in. The HTTP server can accept OIDC/JWT bearer tokens from your own identity provider (Okta, Microsoft Entra, Google Workspace, any OIDC issuer) instead of the owner's passphrase. Signature (the issuer's JWKS), issuer, audience and expiry are checked with jose; configured claims become the actor attributes boundaries read, and one claim can name the tenant. Any failed check is a 401. docs/SIGN-IN.md
- Encryption at rest is not something this library does. On Postgres it belongs to the
database: storage encryption with KMS-managed keys, encrypted backups, TLS. Locally the SQLite
file is plaintext, owner-only (0600 in a 0700 directory), so use full-disk encryption
(FileVault, BitLocker, LUKS). For file-level encryption, a SQLCipher build of SQLite is the
route, but it is not built or tested here.
encryptionKeyRefnames a key you manage; it encrypts nothing. - Erasure.
eraseWhere({ label: "subject", equals: "person-42" })erases every fact carrying that label that the actor can see, along with what was concluded from them. Each fact goes through the erase policies, so a memory lock still refuses and Recently deleted still holds. The call returns a receipt: selector, actor and time; counts erased, refused (with reasons) and held; ids hashed. Its digest is chained into the audit trail, soverify-audit memory.db --receipt receipt.jsonchecks it. Backups and exports made before the erasure are outside it, and the receipt says so. It behaves the same on SQLite and Postgres. docs/ERASURE.md
Enterprise edition
The core stays free and Apache-2.0, including everything above. A commercial enterprise edition adds:
- multi-process safety for serverless deployments
- data-API query executors
- database row-level security
- an enterprise readiness suite
The seams these plug into are public, and so is read audit: PostgresMemoryStore with
accessAudit: { sink, reads: true } hears every read and write of a tenant, inside the call's own
transaction. docs/EXTENSION-POINTS.md
To ask about it, contact the repository owner, @flytomoon.
Limits, measured
One SQLite file, one process, one writer. Measured on an M1 Pro laptop with 100,000
facts (bench/bench.mjs, better-sqlite3, WAL):
| Operation (100,000 facts) | Measured |
|---|---|
| Insert, one fact per call | 5,400–5,900 facts/s (17–18 s for all 100k) |
| Keyword recall, top 10 (FTS5 + decay re-rank) | 30–50 ms median, ~150 ms worst of five terms; first query after open ~320–380 ms (cold cache) |
| Keyword recall through a governed handle, top 10 | ~75 ms for a word in 10% of facts, ~135 ms for two such words, ~850 ms for a word in every fact — see below |
| Recall by filters only, top 10 | 0.5–1 ms |
| Get by id | 0.1 ms |
| Invalidate a fact | 0.5 ms |
Reconstruct snapshotAsOf |
2.19 s with 100,001 versions |
| File size | 69 MB for the 100,000 facts; each recorded change adds ~738 bytes (140 MB after one update to every fact) |
Audit event into audit_events, in the fact's own transaction |
+0.04 ms per governed write, +0.5 ms per governed read (a read is audited too, so it takes the write lock briefly) |
Checking the chain — verify-audit <db> |
linear, ~3 µs/event: 83 ms at 20,000 events, 325 ms at 100,000, 1.5 s at 500,000. Each process pays it once, before its first governed write and outside the write transaction, so it delays that process and blocks no other. Constant memory (the walk streams) |
| How fast the trail grows | A governed recall adds an audited access write for each returned hit (at most 50 through MCP), plus read audit events. Nothing prunes the trail. At 500,000 audit events it is ~128 MB, which can exceed the facts it describes; if you drive a store that hard, keep an eye on it |
Ranges are three runs of the same script on 0.4.0. Paging is exact: a page of ten is the first ten of the full ordered read. When facts have genuinely decayed, the store may have to read past its 200-row candidate pool to keep that promise — the worst case is a full read of the matching facts (~300 ms at 100k), and it only happens when a decayed fact and a fresher one would otherwise trade places.
The transaction-time measurement is one run on the same M1 Pro: 100,000 facts, one recorded reinforcement per fact, and one earlier invalidation. Reconstructing all 100,000 facts from 100,001 versions took 2.19 s. It is an in-memory linear reconstruction, not an indexed point lookup.
A governed keyword search is slower on purpose. It reads every match, keeps the ones the actor may see, and ranks them with word rarity counted over those visible matches alone: the store's BM25 counts rarity across all facts, hidden ones included, so it would let a hidden fact reorder visible results. At a personal memory's size (a few thousand facts) the speed difference does not show, and a test holds its quality: twelve facts asked for in plain questions ("what is the wifi login") among two hundred distractors all land on the first page.
What that means: a personal assistant or a single-tenant service will not notice the
store. Hosted deployments can use PostgresMemoryStore with explicit tenant keys;
SQLite remains the default. Node/TypeScript only for now; the optional on-device
embedder is a 25 MB model download.
al-buddy-memory MCP questions
How do I add al-buddy-memory MCP to Claude Code?
Run claude mcp add --env 'AL_BUDDY_MEMORY_AUDIT_KEY=<YOUR_AL_BUDDY_MEMORY_AUDIT_KEY>' al-buddy-memory -- npx -y al-buddy-memory mcp in your terminal. Add --scope user to make it available in every project.
How do I add al-buddy-memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does al-buddy-memory MCP provide?
It exposes 11 tools, including remember, recall, history, explain, mental_model.
How does the memory handle updates to facts?
A fact is invalidated rather than overwritten, ensuring that history is preserved and the store knows what was true at a specific time.
Does this require an external API key for embeddings?
No, it supports on-device embeddings using transformers.js, allowing for keyless local operation.
How is the origin of a fact tracked?
Every node and edge includes provenance, identifying whether the information was UserInput, AIInferred, GuardianAdded, or SystemGenerated.