al-buddy-memory

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

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

A fact is never deleted, only invalidated. Raw text is the source of truth. Embeddings are a disposable, model-tagged cache. Everything 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:

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 public docs as of September 2026; if we have a cell wrong, a PR with a link fixes it.

Related MCP server: @memharness/mcp

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.

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).

• 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.

• buildSourceProvenance / readSourceProvenance, renderMemoryBlock, exportMemoryMarkdown, decay helpers.

Node ≥ 20. One runtime dependency (better-sqlite3); transformers.js is optional.

Prior art, with thanks: the pinned tier and the sleep-time pass take up ideas the Letta project published (memory blocks; sleep-time agents). The designs here are our own, written for a store that keeps provenance and never rewrites the raw.

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, JsonlAudit } from "al-buddy-memory";

const store = govern(new SqliteMemoryStore("brain.db"), {
  policies: [personalDefaults({ owner: "chris" })],
  context: () => ({ actor: currentActor() }),
  audit: new JsonlAudit("audit.jsonl"),
});

Three policies ship to copy: personal defaults (secrets auto-classified Sensitive and never exported by anyone but the owner), 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 four optional hooks; see docs/GOVERNANCE.md.

Without any policy the store still guarantees: Sealed facts never surface unless asked for by classification; provenance, nodeId, encryptionKeyRef and the anchor trail are immutable after write; nothing is deleted.

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.

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):

What that means: a personal assistant or a single-tenant service will not notice the store; a multi-tenant SaaS needs the Postgres backend on the roadmap. Node/TypeScript only for now; the optional on-device embedder is a 25 MB model download.

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:

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. The scorer reports what the export records, nothing more.

The rulebook, including what the score does not measure (recall quality, truth, latency), is docs/SCORING.md. The adapters are written against export shapes, not vendors, and map only what the shape records. If a system starts recording provenance, its score goes up — that is the point. Adapters live in src/conformance/adapters.ts; add one for your shape and open a PR.

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, and — for a superseded fact — the id of what replaced it. invalidate closes a fact's validity and keeps the record; nothing is ever deleted.

{ "mcpServers": { "memory": { "command": "npx", "args": ["al-buddy-memory-mcp"],
    "env": { "AL_BUDDY_MEMORY_DB": "~/.al-buddy-memory/brain.db" } } } }

A recall result looks like this — every field an agent needs to decide how much to trust the fact:

{ "id": "…", "text": "Lives in Tokyo", "provenance": "UserInput", "validFrom": "2026-06-01T00:00:00Z",
  "validTo": null, "current": true, "confidence": 1, "supersededBy": null, "derivedFrom": [] }

Tools: remember, recall, invalidate, pin, unpin, pinned. SQLite on disk, no service, no key. The tool bodies are a plain function over a MemoryStore (governanceTools(...), exported), so they run against any backend and test without a transport.

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)

• A comparison table and a live paste-your-export demo (albuddy.com)

• A Postgres backend behind the same MemoryStore interface, for multi-tenant and hosted deployments (SQLite stays the local-first default; the interface is small and the conformance suite is what a backend must pass)

• Framework integrations (LangChain, CrewAI, Vercel AI SDK)

Development

npm ci
npm run typecheck && npm test && npm run build

Tests: 135, including a behavioural conformance suite every backend runs against itself.