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: facts are invalidated rather than overwritten, raw text is the immutable source of truth, erasure on a governed handle runs through policy and is audited, embeddings are a disposable cache, and ever
2026-10-28
स्टार
—
टूल
—
अपटाइम
—
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
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.
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
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.
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 same
MemoryStore interface 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 own WHERE, before ranking and before any limit, so facts
outside it never take a place in a page. It fails closed, and beforeRead still 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. encryptionKeyRef names 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, so
verify-audit memory.db --receipt receipt.json checks 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
one event per governed write, one or two per governed read — a remember is +2, a recall +1. Nothing prunes it. At 500,000 events the trail 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.
The semantic path costs more
Everything above is the keyword path. Recall with an embedder wired goes through a
brute-force linear scan: every stored vector is read, decoded and scored against the
query. Measured the same way (bench/bench-vectors.mjs, 384-dimension float32 vectors,
the width and number type of the default on-device model), on the same laptop, since
0.8.1 stores vectors as float32 bytes (the 0.8.0 JSON-text figures in brackets):
With an embedder wired
20,000 facts
100,000 facts
File size (facts + vectors)
55 MB (172 MB)
277 MB (864 MB)
Per vector, on disk
1,536 bytes (~8,000)
1,536 bytes (~8,000)
Semantic recall, top 10 — first of a session
488 ms (765 ms)
1,619 ms (3,200 ms)
Semantic recall, top 10 — thereafter
22 ms median (36 ms)
113 ms median (187 ms)
gaugeStore measures any store file this way and checkBudgets says which numbers are over
budget.
The history of this section is worth keeping: on 2026-09-19 it measured the JSON cost,
named float32 storage as the fix, and filed it here as a weak spot. It was built six days
later, when a question about backups surfaced it. A measurement with no budget is a fact
nobody owns; that is why the gauge exists.
Where the time goes, 0.8.0 → 0.8.1. On 2026-09-19, one cold call at 100,000 facts
spent 978–1,182 ms reading the vector table and 1,418–1,744 ms in JSON.parse, against
85–127 ms for the cosine scan itself: reading and parsing 8 KB text rows was 95% of the
cost, and the scan everyone suspects was 4%. Storing float32 bytes shrank the read about
5× and removed the parse; what remains of the 1.6-second first call is reading 154 MB and
turning it into JavaScript arrays. Two consequences:
sqlite-vec is still not the next move at this size; the scan is not the cost.
The vector cache is disposable and model-tagged. Vectors live in their own table
keyed by (nodeId, model); deleting them loses nothing but time, and a vector from a
different model is skipped rather than compared. Upgrading the embedder is a re-index,
never a migration.
The scan is still linear in the number of facts, and a session's first call pays for the
whole vector table; later calls reuse a 60-second in-process cache.
Backups, restores and synced folders
A SQLite database in WAL mode is three files — brain.db, brain.db-wal, brain.db-shm —
and two ordinary habits will quietly lose a person's memory:
Restoring a backup: stop the server first, then delete brain.db-wal and
brain.db-shm before you copy the backup into place. A -wal left beside a restored
file is replayed over it on the next open, so the restore appears to succeed, reports no
error, and leaves you with the data you were trying to replace. Verified, 2026-09-19.
Which backup command:sqlite3 brain.db ".backup out.db" and
VACUUM INTO 'out.db' are the safe ones — both take a consistent snapshot of a live
database, verified while another process was writing. sqlite3 .dump works too, but it
does not carry user_version; before 0.4.2 a restored dump could not be opened at all
(duplicate column name: valid_from), and now it migrates cleanly. Never back up by
cp-ing a live database: a copy taken mid-write can be unreadable, and a readable one
can still fail PRAGMA integrity_check.
Synced folders: never put the database in iCloud, Dropbox, OneDrive or Google Drive.
WAL mode assumes one machine coordinating its own locks; a sync client copying
the three files independently, or two machines writing through one folder, corrupts the
file rather than conflicting visibly. Back the folder up by all means — copy it out on a
schedule, or use .backup/VACUUM INTO — but do not let a sync client own the live file.
The conformance score
Try it: albuddy.com — paste any memory export, nothing leaves your browser.
Recall benchmarks are saturated. Nobody scores whether a memory system can say who
asserted a fact, since when, whether it is still true, and whether the fact
survives leaving the vendor. This does, on any export you paste in:
npx al-buddy-memory conformance my-export.json # format auto-detected
npx al-buddy-memory conformance agent.af --format blocks # block-style agent files
npx al-buddy-memory conformance memories.json --format records # flat memory records
npx al-buddy-memory conformance --demo # a small governed store, for comparison
Seven dimensions, each 0–100% with the reason spelled out; a dimension the sample cannot
prove (no retired facts present, say) is reported as unproven and left out of the total
instead of counted as a failure. The reference score:
Export
Provenance
Since when
Retire without erasing
Confidence
Relations
Portability
Grade
al-buddy-memory (demo store)
100%
100%
100%
100%
100%
100%
A
Score your own export the same way: --format blocks for block-style agent files, --format records for flat memory records, or paste it into the demo at albuddy.com.
Where the numbers come from, said plainly, because this is a scorer we also score
ourselves with. Five of the seven — provenance, since when, retire without erasing,
confidence, relations — are counted off the records in the file you paste; change the
sample and they move. Two are not. Whether a system keeps a retired fact, whether its
schema is published, and whether it itemises facts are properties of the system, which
no single export can prove, so the adapter author declares them in
src/conformance/adapters.ts and they show up verbatim in the report's reason line. The
one part that is executed rather than asserted is the round-trip: for our own format the
scorer imports your artifact into a fresh store, exports it again and compares — on your
file, and it says lossy if that fails.
The rulebook, including which dimension is which and what the score does not measure
(recall quality, truth, latency), is docs/SCORING.md. The adapters are
written against export shapes, not vendors. If a system starts recording provenance, its
score goes up — that is the point. Add an adapter for your shape and open a PR; if you
think we declared a trait wrongly for yours, that is a one-line PR too.
Benchmarks
The conformance score measures what recall benchmarks leave out; it does not replace them. Two
harnesses in bench/ put numbers beside it, each with its result file, commit and
settings in bench/results/:
LongMemEval, the public recall benchmark: 500 questions over
chat histories of about 50 sessions each. Every question gets a fresh store holding its history,
one memory per message through the public API, nothing extracted or summarised; recall chooses
what the reader sees. The reader and judge prompts, the yes/no rule and the retrieval metrics are
the official ones, held to the official code by tests. The reader and judge are Claude, run
through the Claude Code CLI on a subscription, so a run spends no metered API money — and the
judge is therefore not the official gpt-4o, which is why every result ships its answers in the
official format for anyone to re-judge. node bench/longmemeval/run.mjs --limit 50 is a smoke run.
Latest full run (2026-09-30, all 500 questions, no reranker): 92.6% overall, 94.4% task-averaged,
with the recall call itself at 11.7 ms p50 / 33.5 ms p95 on a laptop — side by side with the
all-levers run in bench/results/README.md. Re-graded with the official judge
(gpt-4o-2024-08-06, the official prompts, temperature 0): 92.8% overall, 94.4% task-averaged — the
number to compare with other systems; the Claude judge gave 92.6% / 94.4%.
Stale facts, our own: things about a person that change over
time, told to the same store three ways — append-only, append-only recalled with freshness, and
through recordState, where a newer state closes the old one. It asks whether recall returns the
value true now, and the value true at a past instant. No model is called; it is deterministic.
Stale facts, as measured (result; 24 questions about
now, 11 about a past instant; keyword recall, no embedder; first 5 results):
append-only
append-only + freshness
recordState
Now: an outdated value comes first
50.0%
4.2%
0.0%
Now: an outdated value in the first 5
87.5%
37.5%
0.0%
Now: the current value comes first
16.7%
25.0%
33.3%
Then: a value not true then in the first 5
27.3%
27.3%
18.2%
Then: the value true then comes first
27.3%
9.1%
27.3%
Read it for what it is. Invalidation is what takes the outdated answer off the table: half the
"where do things stand" questions put an old value first in an append-only store. Freshness hides
that without removing it — the old value is still in the first five more than a third of the time —
and it mistakes an old fact mentioned late for a new one: asked what car I drive, it answers with
the 2019 Civic mentioned last. The current value coming first a third of the time at best is keyword
recall, for every strategy alike: short questions ("what phone do I have?") match rare words in
unrelated facts, and "I accepted an offer from Cobalt Robotics" shares only "I" with "where do I
work?". The two past-instant questions where recordState still shows a wrong value are a gap this
benchmark found: a state learned late is closed at the next state still live, not the next state in
time, so a 2018 home mentioned after the 2025 one reads as valid alongside the homes in between.
The governance MCP server
Most memory MCP servers hand the agent a fact.
This one hands it a fact it can weigh: every recall result carries provenance,
validFrom, validTo, current, confidence, which assistant wrote it and which retired
it, and — for a superseded fact — the id of what replaced it. invalidate closes a fact's validity and keeps the record; the server
has no erase tool. It serves a governed store: the owner's personalDefaults with the AI
client as the audience, so a secret an agent writes is classified Sensitive and kept out of
any AI's recall, and every call is audited — into the database itself, in the same
transaction as the fact.
al-buddy-memory-mcp is an executable inside the al-buddy-memory package, not a
package of its own, so --package= is what tells npx where to find it — npx al-buddy-memory-mcp looks for a package by that name and gets a 404. Drop the @0.12.0
to track the latest release instead of the one you tested.
Releasing? This pin is a documented version and goes stale the moment a new one
publishes — the example would then install an older server than the page describes.
Advance it in the same commit as the version bump — it has been, at 0.4.2 and 0.5.0, and was
@0.4.1 while 0.4.1 was current. Running the pinned command against a newer release
returns the older server's handshake, which is how a reader ends up reading documentation
that does not match what they just installed (Astra release review, 2026-09-19).
The memory lands in ~/.al-buddy-memory/brain.db; set AL_BUDDY_MEMORY_DB to put it
somewhere else. Give it an absolute path — a JSON config is not a shell, and a ~
in it is expanded by this server but not by everything else that may read the value.
The audit trail goes inside that database, in audit_events, appended in the same
transaction as the fact it describes — one hash chain however many assistants are running.
Check it with al-buddy-memory verify-audit ~/.al-buddy-memory/brain.db. A server from
before the table left one log per process in brain.db.audit/, and one before that a
single brain.db.audit.jsonl; those are neither adopted nor
extended (they attest to a period the table cannot, and vice versa) and the same command
reports them alongside the table. AL_BUDDY_MEMORY_AUDIT still names a JSONL file to use
instead — one process per file if you do.
A recall result looks like this — every field an agent needs to decide how much to trust the fact:
origin is which assistant wrote the fact, taken from the MCP handshake rather than from
the model, and retiredBy is which one closed it — so on memory genuinely shared between
assistants, a retired fact is an event with an actor. Both are null when the host knew
nothing.
remember answers "what might this replace?" It returns the fact it stored plus
mayConflictWith: up to three current facts that read like the new one, each with its id,
text and validFrom.
Nothing is retired automatically — the client reads them and calls invalidate on the ones
that stopped being true. That is the whole invalidate-never-overwrite loop, and until 0.4.2
nothing in the surface ever prompted it. Treat the list as facts to read: they are the
best lexical matches, not conflicts that were proven.
The firstrecall of a connection also returns the pinned tier — the person's standing
rules — as a second content block, so the tier that claims to be in every prompt gets there
without spending any of the 512-character handshake.
Tools: remember, recall, history, explain, invalidate, pin, unpin, pinned, mental_model, define_mental_model, export, and for team memory promote and withdraw (the personal server's policy refuses them; see docs/policies/scopes.md). mental_model reads a standing question's pre-written answer with its freshness and evidence (the host refreshes answers on its own schedule). explain answers why a
fact is believed: who asserted it, when it was true, what ended it, and for a conclusion the exact
words it rests on, each checked now. remember takes at
most 4,000 characters and pin 500; a recall query 1,000, an invalidate reason 500, and
an id 128. pin refuses text that reads like a secret, because the server would store it
Sensitive and no assistant could see it. invalidate's replacedBy must name a fact the
caller can see. SQLite on disk, no service, no key. The tool bodies are
a plain function over a MemoryStore (governanceTools(...), exported from
al-buddy-memory/mcp), so they run against any backend and test without a transport; pin
there needs pinning: true, which only a host on the user's own machine should pass.
Recall is hybrid — keyword and meaning, with the query's time and counting cues read
(expand), the setting the LongMemEval result was measured with. The server starts at once on
keyword recall and loads the on-device embedding model beside it; from the call after it loads,
recall uses both. The model (all-MiniLM-L6-v2, about 90 MB) is downloaded once from the Hugging
Face hub to ~/.al-buddy-memory/models (AL_BUDDY_MEMORY_MODEL_CACHE moves it) and then runs
offline; facts stored before it was there are embedded in the background, up to 5,000 per start
(AL_BUDDY_MEMORY_INDEX_LIMIT). Where it cannot load — @huggingface/transformers not installed,
no onnxruntime binary for the platform (Intel Macs, for one), no network on first run — recall
stays keyword-only and the server says so once on stderr. The model loads and runs in a worker
thread, and the background pass gives the event loop back every 20 ms, so the server keeps
answering while it indexes. AL_BUDDY_MEMORY_SEMANTIC=off never
loads it. The cross-encoder reranker is not switched on: on the full LongMemEval run it moved the
overall score by nothing (92.6% with and without) and costs a second model.
Export. The export tool returns the memory in the portable format
— inline when it is under 50 KB, otherwise written to an absolute .json path you name that does
not exist yet (it never overwrites). It exports what the assistant could recall: the policy keeps
Sensitive and Sealed facts out. Your complete backup, every fact included, is the command line's,
and import restores one:
al-buddy-memory export --out ~/memory-backup.json # or --format markdown for a readable mirror
al-buddy-memory import ~/memory-backup.json # checks the whole file first; safe to re-run
Both read AL_BUDDY_MEMORY_DB (or --db) like the server. al-buddy-memory context prints the
short briefing the Claude Code plugin shows at session start, and al-buddy-memory status the
counts, the database path, the last write and whether semantic search is available.
As a remote connector in Claude and ChatGPT
al-buddy-memory-http serves the same tools over Streamable HTTP for one owner, signed in
with OAuth 2.1 (PKCE S256, dynamic client registration, rotating refresh tokens). Each tool
declares title, readOnlyHint, destructiveHint and openWorldHint, the annotations both
assistant directories ask for. It listens on 127.0.0.1; put a tunnel in front (e.g.
tailscale funnel --bg --https=8443 http://127.0.0.1:8787) and give the apps its URL:
echo 'a long passphrase' | al-buddy-memory-http --set-passphrase # stores a scrypt hash, 0600
AL_BUDDY_MEMORY_PUBLIC_URL=https://you.example.ts.net:8443 al-buddy-memory-http
In Claude: Customize → Connectors → Add custom connector, URL https://…:8443/mcp. In
ChatGPT: Settings → Security and login → Developer mode, then add the same URL. Each app
opens a consent page once; the passphrase allows it. Only hashes of codes and tokens are
kept on disk. Five wrong passphrases from one app lock that app out for 15 minutes, and twenty
from all apps within 15 minutes lock every app out; each lock is logged. A fact an app writes
records it as the fact's origin, by the name the app registered with and the consent page
showed, and the audit event for each call names it too. Two things stay on your machine: export answers
inline and never writes a file, and pin is refused, because a pinned rule rides every
assistant's prompt; pin from an assistant on the local server (al-buddy-memory mcp), and the
remote apps get those rules with their first recall after signing in, and again with the next
one after the rules change. For an organisation, the same server can be
signed in by your own identity provider instead: docs/SIGN-IN.md.
Use it as a Claude Code plugin
The repository is also a Claude Code plugin marketplace. In Claude Code:
or from a shell, claude plugin marketplace add flytomoon/al-buddy-memory and
claude plugin install al-buddy@al-buddy. There is nothing to configure. Getting started,
commands and troubleshooting: docs/claude-plugin.md (and
albuddy.com/claude.html); privacy: docs/PRIVACY.md.
Commands, all under the plugin's al-buddy: namespace: /al-buddy:recall <question>,
/al-buddy:remember <fact>, /al-buddy:forget <fact> (retire it; kept in history),
/al-buddy:status, /al-buddy:export [file], /al-buddy:import <file> and /al-buddy:help.
the governance MCP server above, started with npx and pinned to an exact version — the first
start downloads the package (about 500 MB installed, most of it the optional model runtime);
two skills: recall (search memory before answering about past work, decisions, people or
preferences) and remember (store durable facts — never secrets, credentials or small talk);
a SessionStart hook that adds a briefing of at most 2,000 characters when a session starts, is
cleared or is compacted: your pinned rules, facts mentioning the project folder's name, and the
most recently learned facts, as the assistant is allowed to see them. It never installs anything
itself, so the very first session — while the server's first install runs — gets no briefing.
Where the data lives.~/.al-buddy-memory/brain.db, created when the server first starts; set
AL_BUDDY_MEMORY_DB to an absolute path in the environment Claude Code starts from to keep it
elsewhere. The embedding model sits beside it in ~/.al-buddy-memory/models. Nothing leaves the
machine except the two one-time downloads (the npm package and the model).
Export, back up, remove. Ask Claude to export your memory (the export tool), or run
al-buddy-memory export --out <file>.json for the complete owner backup. Uninstalling the plugin
(/plugin uninstall al-buddy@al-buddy) leaves your memory in place; delete
~/.al-buddy-memory/ to remove it, after exporting it if you want to keep it.
The Claude desktop app. A one-click extension, al-buddy-memory.mcpb (macOS), is attached to
each GitHub release from the next
one on, built by npm run build:mcpb. It carries the server and its dependencies, including the
SQLite engine compiled for the Node.js built into Claude Desktop, and it uses the same
~/.al-buddy-memory/brain.db as the plugin, so the two apps share one memory. Steps in
docs/claude-plugin.md.
Hosts other than Claude Code. The plugin is the same server: any MCP client can use the
npx configuration in The governance MCP server. Codex and the
ChatGPT desktop app share one configuration; from a shell,
codex mcp add al-buddy-memory -- npx -y al-buddy-memory mcp, or in the desktop app Settings → MCP
servers → Add server → STDIO with that command. Details in
docs/claude-plugin.md.
al-buddy-memory status prints how many facts are current, retired and pinned, where the database
is, when it was last written, and whether semantic search can run on this machine (counts only).
Needs Node.js 22 or later on the PATH; Node 20 works only where better-sqlite3 can compile
from source (it ships no Node 20 binary).
Make it automatic in the Claude apps
In the Claude desktop app, and on the web or phone through a remote connector,
one paste makes capture always on: Claude saves every exchange that has substance without being
asked — the question, its answer or recommendation and why, and the decision — and saying
"remember" only makes it save at once. In the app's settings, paste this where Claude asks for your
personal preferences (the instructions it follows in every chat):
Use Al Buddy memory automatically, without being asked. At the start of each conversation, call recall for my pinned rules and anything relevant. After each exchange that has any substance, save it with remember: the date, what I asked or said, what you answered or recommended and why, and what we decided. Mark my own words as UserInput and your answers or recommendations as AIInferred. Save the substance and the reasoning, not filler or small talk. If I say remember, save it right away. Never save secrets or passwords. When something earlier stops being true, invalidate it instead of saving a contradiction.
Then, where the app sets Al Buddy's tool permissions (or when it first asks to use a tool), let
recall and remember run without asking each time, and keep invalidate, unpin and any tool
that erases asking you first.
Why: in the Claude apps a connector is used only when something tells it to, and there is no hook
that captures a conversation automatically — in our test on 11 October 2026, Claude saved to memory
only when asked, even with the server's own instructions in place. This instruction is what makes
it continuous. The same step with a copy button: albuddy.com/claude.html.
Roadmap
The spec and the portable format, published and versioned (this repo)
al-buddy-memory conformance <export>: score any memory export on provenance, invalidation and portability, with adapters for block-style agent files and flat memory records (v0.2.0)
The governance MCP server: a memory server that returns provenance and validity with every fact (v0.2.0)
Governance hooks with an audit trail and three sample policies; provenance immutable at runtime; measured limits at 100k facts (v0.3.0)
The audit event committed in the same transaction as the fact it describes, as one chain many processes share (v0.4.2)
A comparison table and a live paste-your-export demo (albuddy.com)
Transaction time, the second half of bi-temporal: "what did we believe at X", including a fact held wrongly and later corrected (v0.5.0)
A Postgres backend behind the same MemoryStore interface, for multi-tenant and hosted deployments (SQLite stays the local-first default; the backend runs the shared conformance suite)
Framework integrations: Vercel AI SDK, LangChain/LangGraph, Mastra (v0.7.0)
Development
npm ci
npm run check # typecheck, tests, and the browser bundle — exactly what CI runs
The tests include a behavioural conformance suite every backend runs against itself.
Portable, governed, model-agnostic memory for AI agents: facts are invalidated rather than overwritten, raw text is the immutable source of truth, erasure on a governed handle runs through policy and
Portable, governed, model-agnostic memory for AI agents: facts are invalidated rather than overwritten, raw text is the immutable source of truth, erasure on a governed handle runs through policy and is audited, embeddings are a disposable cache, and ever
टूल
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
Al Buddy Memory कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Al Buddy Memory कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
Al Buddy Memory stdio पर लोकल चलता है।
Al Buddy Memory की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-10-28 को हुई। Portable, governed, model-agnostic memory for AI agents: facts are invalidated rather than overwritten, raw text is the immutable source of truth, erasure on a governed handle runs through policy and is audited, embeddings are a disposable cache, and ever
