Related Pages

Related topics: Src

Overview

membook is a versioned memory store for AI coding agents. It is built around a single on-disk artifact called a Memfile whose format is defined by a published specification and consumed by both a human-facing CLI and an agent-facing MCP (Model Context Protocol) server. The project is published as a TypeScript monorepo under the getmembook/membook repository and is currently distributed at [email protected] alongside its sub-packages @membook/[email protected], @membook/[email protected], and @membook/[email protected] (Source: package.json:0; CHANGELOG:0).

Purpose and Scope

The project exists to give a long-running AI agent a durable, inspectable, and portable memory layer that a human owner can also audit. Two surfaces share that memory:

• A CLI (membook) that a developer runs in the terminal to author, verify, and review memories.
• An MCP server (@membook/mcp) that an agent talks to over the Model Context Protocol to read and write those same memories programmatically.

The release notes describe the split directly: *"membook is the human's surface where the MCP server is the agent's"* (Source: CHANGELOG of [email protected]:0). The repository therefore treats the CLI and the MCP package as two views over one underlying store rather than as independent tools.

High-Level Architecture

membook is structured as a four-package workspace. The published top-level entry point is membook at version 0.2.0, which depends on the three sub-packages below it (Source: package.json:0).

The core and spec packages carry the schema and the read/write halves of version machinery, while the CLI wraps them for terminal use and the MCP package wraps them for tools (Source: packages/spec/package.json:0; packages/core/package.json:0).

flowchart LR
    Human["Developer (terminal)"] -->|membook CLI| CLI["packages/cli"]
    Agent["AI Agent"] -->|Model Context Protocol| MCP["packages/mcp"]
    CLI --> Core["@membook/core"]
    MCP --> Core
    Core --> Spec["@membook/spec"]
    Spec --> File[("Memfile on disk")]
    MCP --> File
    CLI --> File

Memory Model and Lifecycle

A Memfile is the on-disk document the system reads and writes. Two invariants govern it: it declares a version, and it is parsed by a shared function parseMemfile that reports that declared version back to the caller. Reading the file was supported before version 0.2.0; writing it with version awareness is what landed in 0.2.0 ahead of a future v2 schema migration (Source: CHANGELOG of [email protected]:0).

When the system touches a stored memory it also classifies it. Older logic let an LLM invalidate a record, which could destroy data. A patch in @membook/[email protected] changed that verdict to land as stale instead, on the principle that *"a model may fail to restore, but it may not destroy"* (Source: CHANGELOG of @membook/[email protected]:0). membook review was also patched in 0.1.1 to re-flow hard-wrapped bodies before display and to re-prompt on unrecognized input (Source: CHANGELOG of [email protected]:0).

CLI Commands

The CLI exposes the human's full workflow against a Memfile (Source: CHANGELOG of [email protected]:0):

• membook init — initialize a new Memfile.
• membook status — report the current state of stored memories.
• membook verify — check integrity and version conformance.
• membook review — display memories, with hard-wrap reflow in 0.1.1.
• membook remember — add a new memory entry.
• membook book — finalized or pinned records.
• membook reindex — rebuild indexes used by lookup.

membook --version was improved in 0.1.2 so the CLI now reads its version from package.json at runtime instead of carrying a hardcoded string; @membook/[email protected] applied the same change to SERVER_VERSION so what the agent sees matches what was actually published (Source: CHANGELOG of [email protected]:0).

Versioning and Releases

The project uses a Changesets-style multi-package release flow where every package has its own version and changelog entry. A typical release cycle is visible across the evidence: a commit such as 47f6d4e that lands in @membook/core also bumps @membook/spec, while the MCP package records both as updated dependencies in its own patch release (here, @membook/[email protected] listing @membook/[email protected] and @membook/[email protected]) (Source: CHANGELOG of @membook/[email protected]:0). The 0.2.x line is therefore best understood as the write-half of the version machinery: the format, parsing, and on-disk Memfile.version field are in place, ready for a future v2 schema bump that the codebase has not yet introduced.

Related Pages

Related topics: Overview, Cli

Src

The src/ directories under each package form the implementation surface of the membook monorepo. They host the TypeScript modules that the membook CLI (human surface) and the @membook/mcp server (agent surface) import, plus the unit tests that pin the contract of those modules. The release notes and changelog make repeated reference to behavior that lives in this tree — for example, the parseMemfile reader, the LLM re-check invalidate -> stale downgrade, and the membook --version runtime lookup are all implemented in files under src/.

This page describes the layout, the role of each file group, and how the modules coordinate to support the documented CLI commands (init, status, verify, review, remember, book, reindex).

Package layout

The src/ tree is split across the workspace packages that [email protected] ships:

Source: packages/core/src/book.ts and packages/core/src/distill.ts provide the core domain primitives; packages/core/src/errors.ts centralizes the typed error vocabulary; packages/core/src/fake-secrets.ts isolates credential fixtures used by tests.

Core domain modules

`book.ts` — memfile lifecycle

book.ts is the module responsible for reading and writing a membook on disk. It owns the operations invoked by the membook CLI subcommands init, book, and reindex, and it is the layer that the MCP book_* tools wrap. The book.test.ts sibling pins the on-disk contract: header order, the version field, and the section layout that parseMemfile consumes.

Following [email protected], book.ts writes the Memfile.version header that parseMemfile now reports back. This is the "write half of the memfile version machinery" called out in the 0.2.0 release — the corresponding read half lives in @membook/spec. Source: packages/core/src/book.ts and packages/core/src/book.test.ts.

`distill.ts` — memory candidate resolution

distill.ts encapsulates the LLM re-check loop. Its job is to take a candidate memory and return one of three verdicts: keep, rephrase, or invalidate. The 0.1.1 changelog records the safety-critical rule that lives here: *"A model may fail to restore, but it may not destroy."* Concretely, an invalidate verdict that the LLM produces for a memory the user has already written is downgraded to stale rather than deleted. The distill.test.ts file exercises both the happy path and this downgrade path. Source: packages/core/src/distill.ts and packages/core/src/distill.test.ts.

`errors.ts` — typed failure surface

errors.ts defines the discriminated error types that propagate up to the CLI and the MCP server. Centralizing the error vocabulary lets the CLI render a human message and lets the MCP layer map the same error to a structured tool result without duplicating the catalog. Source: packages/core/src/errors.ts.

`fake-secrets.ts` — credential test fixtures

fake-secrets.ts provides deterministic credential stand-ins used by book.test.ts and distill.test.ts. Keeping the fixtures in a dedicated module prevents tests from reaching into environment variables and keeps the production code free of test-only branches. Source: packages/core/src/fake-secrets.ts.

CLI and MCP wiring

The two top-level surfaces in membook are deliberately asymmetric: the CLI is the human's surface and the MCP server is the agent's. Both call into the same core modules.

flowchart LR
  CLI[membook CLI<br/>init, status, verify,<br/>review, remember, book, reindex] --> Core
  MCP["@membook/mcp<br/>(MCP tools)"] --> Core
  Spec["@membook/spec<br/>parseMemfile, Memfile.version"] --> Core
  Core["@membook/core/src<br/>book.ts, distill.ts, errors.ts"]
  Core --> Disk[(Memfile on disk)]

Three operational details visible in the changelog sit on top of this diagram:

1. membook --version and the MCP SERVER_VERSION both resolve their version string at runtime by reading the nearest package.json, rather than embedding a build-time constant. The CLI fix landed in 0.1.2 and the MCP equivalent in 0.1.2 of @membook/mcp. Source: packages/core/src/book.ts for the CLI entry, and the MCP package counterpart.
2. membook review re-flows hard-wrapped memory bodies before display and re-prompts on unrecognized input. The re-flow logic lives next to the review command handler; errors.ts is the source of the "re-ask" branch. Source: packages/core/src/errors.ts.
3. parseMemfile now reports Memfile.version so a future v2 reader can branch on the declared version. The write side of that machinery was added in 0.2.0; the read side is consumed by callers in core. Source: packages/core/src/book.ts and packages/core/src/distill.test.ts.

Testing conventions

Each module under src/ is paired with a *.test.ts file that lives in the same directory: book.test.ts, distill.test.ts, and the implicit test for errors.ts. The tests use fake-secrets.ts to avoid hitting real credentials and pin both the read and write halves of the memfile version contract introduced in 0.2.0. Source: packages/core/src/book.test.ts, packages/core/src/distill.test.ts, packages/core/src/fake-secrets.ts.

Together, the files under src/ define the only place where memfile structure, distillation verdicts, and error semantics are encoded; the CLI and the MCP server are thin adapters over them.

Related Pages

Related topics: Src, Src

Source Files</summary>

The following source files were used to generate this page:

• packages/cli/CHANGELOG.md
• packages/cli/LICENSE
• packages/cli/README.md
• packages/cli/package.json
• packages/cli/src/cli.test.ts
• packages/cli/src/cli.ts

Cli

The membook CLI is the human-facing surface of the membook project. It lives in the packages/cli package and exposes the same memory-management primitives that the agent-facing MCP server (@membook/mcp) consumes, but in a form a developer can run from a terminal. As stated in the v0.1.0 release notes, the CLI is "the human's surface where the MCP server is the agent's" — meaning init, status, verify, review, remember, book, and reindex are the operations a user types directly, while the agent drives the same core through MCP. Source: packages/cli/CHANGELOG.md:1-15.

Package Layout and Dependencies

The CLI package is wired into the monorepo as @membook/cli and republished as the top-level membook binary. Its package.json declares the executable entry and pins it to the TypeScript source under src/cli.ts, which is what pnpm membook or npx membook ultimately invoke. Source: packages/cli/package.json:1-40.

Beyond the entry point, the package relies on the two lower-level siblings that define domain behavior:

• @membook/core — memory storage, verification, indexing, and invalidation logic.
• @membook/spec — the Memfile schema, parsers, and version reporting.

By delegating to core and spec, the CLI stays thin: argument parsing, prompt rendering, and exit-code mapping are the only responsibilities it owns. This is the same division that lets membook mcp (the MCP server) stay slim in its own package. Source: packages/cli/src/cli.ts:1-40.

Command Set

The command inventory was introduced in v0.1.0 and has remained stable across the patch releases. The seven top-level subcommands cover the full lifecycle of a memory file:

Source: packages/cli/CHANGELOG.md:1-15.

The v0.1.1 patch sharpened membook review behavior: it now re-flows hard-wrapped memory bodies before display, so terminal widths do not break paragraph structure, and re-prompts the user whenever input is not recognized, rather than silently swallowing typos. Source: packages/cli/CHANGELOG.md:12-20.

Version Reporting

A recurring defect in early releases was a hardcoded version string in the CLI. The v0.1.2 patch resolved this by having membook --version read package.json at runtime, so the published version always matches the actual package. The same fix was mirrored in @membook/mcp's SERVER_VERSION, which now reads from package.json instead of a string literal. The result is a single source of truth across the human and agent surfaces. Source: packages/cli/CHANGELOG.md:22-30.

The runtime read is implemented in src/cli.ts, where the binary resolves its own package.json path at startup and extracts the version field, rather than relying on a compile-time constant. Source: packages/cli/src/cli.ts:1-40.

Behavior When Models Disagree

The CLI participates in the same fail-safe policy that the core enforces: "a model may fail to restore, but it may not destroy." When an LLM re-check returns an invalidate verdict but cannot reconstruct the memory it claimed was wrong, the CLI surfaces the verdict as stale rather than deleting the entry. This matters for membook verify and membook review, where the user is the final arbiter and must never lose data to a hallucinated model correction. Source: packages/cli/CHANGELOG.md:31-40.

Testing Surface

The CLI is covered by src/cli.test.ts, which exercises command parsing, exit codes, and the version-resolution path that landed in v0.1.2. The test file is structured to run the compiled CLI as a subprocess, asserting on stdout and exit status — a pragmatic choice for a binary whose primary job is to format and exit cleanly. Source: packages/cli/src/cli.test.ts:1-40.

Architecture at a Glance

flowchart LR
    User[Human operator] -->|membook CLI| CLI[packages/cli]
    Agent[LLM agent] -->|MCP| MCP[packages/mcp]
    CLI --> Core
    MCP --> Core[packages/core]
    Core --> Spec[packages/spec]
    Spec -.Memfile schema.-> Disk[(Memfile on disk)]
    Core -.Memfile I/O.-> Disk

The diagram makes the layering explicit: both the CLI and the MCP server are thin adapters on top of core, which in turn writes and reads the Memfile defined by spec. A change in core or spec (such as the v0.2.0 version-machinery write half) is automatically visible to both the human and the agent without any CLI-side work. Source: packages/cli/src/cli.ts:1-40, packages/cli/README.md:1-20.

Operating Notes

• The CLI is published under the membook name, while the source package is @membook/cli; both resolve to the same src/cli.ts entry. Source: packages/cli/package.json:1-40.
• Project metadata is governed by the repository LICENSE, redistributed per package. Source: packages/cli/LICENSE:1-20.
• The README documents the seven commands and the --version flag introduced in v0.1.2. Source: packages/cli/README.md:1-40.
• The v0.2.0 release introduced the write half of the memfile version machinery. parseMemfile now reports the declared version, and the CLI is the primary path through which human edits become versioned writes. Source: packages/cli/CHANGELOG.md:41-55.

Related Pages

Related topics: Src, Src

Commands

The membook CLI is the human-facing surface of the membook project, while the MCP server is the agent-facing surface. Commands live under packages/cli/src/commands/ and are composed of small, focused modules wired together by the command dispatcher. Each command encapsulates a single user intent — initializing a memory file, capturing a new memory, reviewing existing ones, or maintaining the index — and delegates the heavy lifting to the core and spec packages.

Command Catalog

The CLI exposes the following user-facing commands:

Source: packages/cli/src/commands/init.ts Source: packages/cli/src/commands/review.ts Source: packages/cli/src/commands/seed.ts

Lifecycle and Maintenance Commands

The lifecycle commands establish and maintain the on-disk state of a membook workspace.

• init creates a fresh Memfile in the working directory and writes the schema header, including the Memfile.version field introduced in v0.2.0. The version is now read from the local package.json at runtime, ensuring the published version and the version a fresh Memfile declares stay in lockstep.
• status and verify are read-only inspectors. verify re-checks LLM verdicts and downgrades an invalidate decision to stale rather than dropping the memory — a model may fail to restore a fact, but it must never destroy one.
• reindex regenerates the secondary index that the MCP server reads when serving tools to agents.

Source: packages/cli/src/commands/init.ts Source: packages/cli/src/commands/misc.ts Source: packages/cli/src/commands/seed.ts

Memory Capture and Curation Commands

The capture and curation commands are the daily-driver surface of membook.

• remember writes a new entry to the Memfile, taking the body from stdin or an argument and stamping it with metadata.
• book promotes a memory to a longer-retention tier.
• review is interactive: it re-flows hard-wrapped memory bodies before display so terminals of different widths render consistently, and re-asks the user on input it does not recognize rather than guessing.
• distill reduces several related memories into a single, higher-level summary, which is then written back through the same version-aware machinery used by init.

Source: packages/cli/src/commands/review.ts Source: packages/cli/src/commands/distill.ts

Integration and Versioning Hooks

Two commands operate at the boundary between membook and the host environment.

• hook installs or removes integration glue — for example, Git hooks that re-run verify or reindex after edits to the Memfile.
• The version string surfaced by membook --version and by SERVER_VERSION in the MCP package both read package.json at runtime. Prior to v0.1.2, these were hardcoded and could drift from the published version, which is why the change was made in PR #22.

The v0.2.0 release extended this runtime-awareness to the write path: parseMemfile now reports the Memfile.version declared on disk, completing the read/write half of the version machinery ahead of the planned v2 format.

Source: packages/cli/src/commands/hook.ts Source: packages/cli/src/commands/misc.ts Source: packages/cli/src/commands/init.ts

Command Flow

flowchart LR
  A[User] --> B[CLI dispatcher]
  B --> C[init]
  B --> D[remember / book]
  B --> E[review / distill]
  B --> F[verify / status / reindex]
  B --> G[hook / seed / --version]
  C --> H[Memfile on disk]
  D --> H
  E --> H
  F --> H
  H --> I[MCP server reads]
  I --> J[Agent]

Source: packages/cli/src/commands/init.ts Source: packages/cli/src/commands/review.ts Source: packages/cli/src/commands/misc.ts

Notes for Contributors

• Keep new commands small and single-purpose; the existing modules are intentionally narrow so the dispatcher can stay trivial.
• When a command writes the Memfile, always go through the version-aware parser so the on-disk Memfile.version stays accurate.
• For interactive commands like review, prefer re-asking on unrecognized input over silent defaults — this preserves the human-in-the-loop guarantee that distinguishes the CLI from the MCP server surface.

Doramagic Pitfall Log

Found 17 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/getmembook/membook

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: [email protected]
• User impact: Upgrade or migration may change expected behavior: [email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.0

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/getmembook/membook

4. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Developers should check this runtime risk before relying on the project: @membook/[email protected]
• User impact: Upgrade or migration may change expected behavior: @membook/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @membook/[email protected]. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.2

5. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Developers should check this runtime risk before relying on the project: [email protected]
• User impact: Upgrade or migration may change expected behavior: [email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.2

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/getmembook/membook

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/getmembook/membook

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/getmembook/membook

9. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: @membook/[email protected]
• User impact: Upgrade or migration may change expected behavior: @membook/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @membook/[email protected]. Context: Observed when using windows
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/core%400.1.1

10. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: @membook/[email protected]
• User impact: Upgrade or migration may change expected behavior: @membook/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @membook/[email protected]. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/core%400.2.0

11. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: @membook/[email protected]
• User impact: Upgrade or migration may change expected behavior: @membook/[email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @membook/[email protected]. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/spec%400.2.0

12. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: [email protected]
• User impact: Upgrade or migration may change expected behavior: [email protected]
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.1

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using membook with real data or production workflows.

• [email protected] - github / github_release
• @membook/[email protected] - github / github_release
• @membook/[email protected] - github / github_release
• @membook/[email protected] - github / github_release
• [email protected] - github / github_release
• @membook/[email protected] - github / github_release
• [email protected] - github / github_release
• @membook/[email protected] - github / github_release
• @membook/[email protected] - github / github_release
• [email protected] - github / github_release
• Configuration risk requires verification - GitHub / issue