Membook

Membook

Memory that stays true. A verifiable memory engine for coding agents.

[](https://github.com/getmembook/membook/actions/workflows/ci.yml) [](https://www.npmjs.com/package/membook) [](https://www.npmjs.com/package/@membook/core) [](https://www.npmjs.com/package/@membook/mcp) [](https://www.npmjs.com/package/@membook/spec) [](./LICENSE) [](./package.json)

Coding agents forget. Worse, they misremember: a memory saying "we use Jest" survives the migration to Vitest and gets served to the agent as fact.

Membook anchors every memory to checkable reality — a commit, a file, a symbol — so when the code changes, the memory knows. Storage is plain markdown committed to your repo: it renders on GitHub, diffs in pull requests, and survives review like any other artifact.

> Early. The five release gates in the > [dogfood log](./docs/dogfood.md) all closed on measured evidence — cold > install, an unrehearsed staleness catch, a live recall hit, zero secrets > written — and 0.1.x is on npm with provenance. What has NOT happened yet > is time: nobody has lived with Membook for weeks, so whether it durably > helps is still being measured rather than claimed. Pre-1.0, expect breaking > changes; the Memfile format itself is versioned and read-tolerant.

Why it's different

Every memory system in the market stores text that nothing keeps honest. Membook's differentiator is the verification loop:

1. A memory is stored with one or more anchors — {path, symbol?, commit}.
2. Verification diffs commit..HEAD against the anchor paths.
3. Untouched paths re-verify for free. Touched paths get one targeted re-check.
4. The memory becomes verified, stale, or invalidated — and says so.

A memory that cannot be checked against reality is a floating sentence. The schema rejects one with no anchor.

Design commitments

These are settled, and the code enforces them:

• Files are the truth; the database is a cache. Canonical state is one

markdown file per memory. SQLite is derived, disposable, and rebuilt bit-identically by reindex. Delete it any time.

• No daemon. Nothing resident, no ports, no background processes.
• Local-first. No network telemetry, ever.
• Honest status. A memory is unverified until something actually

verifies it. This repo's own memories are unverified today, because the verify pass does not exist yet — claiming otherwise would be exactly the unfalsifiable assertion the project exists to prevent.

• MIT, genuinely. Not Elastic-licensed, not source-available.

A memory

---
memfile: 2
id: m-6dd5
type: gotcha
status: verified
scope: repo
confidence: 0.9
created: "2026-07-21T16:42:00Z"
verified: "2026-07-24T08:00:00Z"
anchors:
  - kind: git
    path: packages/core/src/index-db.ts
    symbol: openIndex
    line_range: [18, 46]
    commit: 9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d
provenance:
  origin: distilled
  session: sess-01H8X4M2
  agent: claude-code
  model: claude-opus-4-8
  source_hash: e3b0c442…
---

`better-sqlite3` must be loaded after the process sets `PRAGMA journal_mode=WAL`,
or concurrent MCP sessions on the same repo deadlock on first write.

Provenance is shaped so that presence is meaningful: a hash appears only when a real artifact stands behind it, and a human-authored memory cannot express an agent or model it never had. An auditor can reconstruct who wrote a memory, from what, and in what context, purely from which fields exist.

Status

| Package | What it is | State | | ---------------------------------- | -------------------------------------------------------- | -------------------- | | [@membook/spec](./packages/spec) | The Memfile standard — schema, anchor grammar, validator | Built, 140 tests | | [@membook/core](./packages/core) | Engine — store, index, verify, recall, book, distill | Built, 285 tests | | [@membook/mcp](./packages/mcp) | MCP server (remember / recall / session_digest) | Built, 25 tests | | Verify pass | The verification loop + fixture harness | Built | | Boot pack | MEMBOOK.md generator | Built | | The three seams | Secret scanner, LLM re-checker, instrumentation | Built | | [membook](./packages/cli) | CLI — see below | Built, 99 tests | | Distillation | Docs and sessions → candidate memories | Built | | Workspaces (v0.2) | Cross-repo anchors, verification, federated recall | Built |

Commands

membook init [--hooks]   set up; optionally install a Claude Code recall hook
membook seed             distill existing docs into candidate memories
membook distill [file]   turn session notes into candidate memories
membook recall    see what an agent would be served
membook remember   record a memory (--scope user: follows you, never committed)
membook status           what is known, and how far to trust it
membook verify           re-check memories against the current code
membook review           ratify or delete what a human has not seen
membook book             regenerate MEMBOOK.md
membook reindex          rebuild the index from the files
membook migrate          rewrite memories to the current memfile form, as a diff

seed and distill need a model (ANTHROPIC_API_KEY or OPENAI_API_KEY). Everything else works without one.

Workspaces

Federate verification and recall across the git checkouts your machine already has — no server, no sync, git pull is the propagation medium. Declare a resolution table at ~/.membook/workspace.yaml:

workspace: my-stack
members:
  payments-service:
    path: ~/dev/payments
    remote: git@github.com:acme/payments-service.git # identity check, optional
  platform-gateway:
    path: ~/dev/gateway

A memory may then anchor into another repository by member name (kind: xgit), and verify --workspace runs the same diff-and-follow logic inside that checkout: the producer merges a contract change, you pull, and your memory flips stale before an agent writes code against the old shape. A member this machine cannot use is reported unresolvable — not stale, not verified, never folded into either. status -w shows each member's resolution and how far it lags its upstream; recall -w also searches members' memories (served with from provenance, via a read-only cache — Membook never writes inside a checkout it did not init); book -w lets cross-repo memories into MEMBOOK.md only when their repositories are actually present.

Both write candidates as unverified and hand them to review: a model proposes, a person disposes. That human decision is the strongest verification Membook has, and the only ground truth it can measure a re-checker against.

Platform support

macOS and Linux for v0.1. Windows is built in CI but not gated on.

Windows installs and runs: @membook/spec passes its full suite there, and the rest is close. What fails is temp-directory cleanup — SQLite holds a file handle open, and Windows refuses to unlink a file that is open, so a handful of tests error on teardown rather than on anything they were testing.

That is a smaller and more tractable problem than it used to be — until recently better-sqlite3 could not compile there at all — but "close" is not "supported", so v0.1 does not claim it. Windows is a v0.2 question.

Development

Requires Node ≥ 20 (the repo pins 24 via mise and .nvmrc) and pnpm 9.

pnpm install

pnpm test

pnpm build && pnpm typecheck

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the workflow, and [CLAUDE.md](./CLAUDE.md) for architecture decisions and the build order — it is the build context for both humans and coding agents.

The standard

The Memfile format is documented in [packages/spec/README.md](./packages/spec/README.md) and published as a JSON Schema. It is deliberately free to implement: the format is a standard we would like others to adopt, and the verification loop is the product.

Security

Memories get committed, so a secret written into one is persisted and pushed. Every write is therefore scanned before it reaches .membook/, and the scanner is deny-biased: a false positive costs a human glance, a false negative commits a credential forever, so when a rule is torn it blocks. It is on by default in the MCP server.

Regex scanning is a floor, not a ceiling — a passing scan is not permission to paste secrets at Membook. Please report vulnerabilities privately, and a missed credential class counts — see [SECURITY.md](./SECURITY.md).

License

MIT © Stag.ai Ltd

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: getmembook
• Source: getmembook/membook
• License: MIT
• Homepage: https://membook.dev

Install and usage instructions live in the source repository linked above.