# https://github.com/getmembook/membook Project Manual

Generated at: 2026-07-26 21:43:18 UTC

## Table of Contents

- [Overview](#page-overview)
- [Src](#page-packages-core-src)
- [Cli](#page-packages-cli)
- [Src](#page-packages-cli-src)
- [Commands](#page-packages-cli-src-commands)
- [Src](#page-packages-mcp-src)

<a id='page-overview'></a>

## Overview

### Related Pages

Related topics: [Src](#page-packages-core-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/getmembook/membook/blob/main/README.md)
- [package.json](https://github.com/getmembook/membook/blob/main/package.json)
- [packages/cli/README.md](https://github.com/getmembook/membook/blob/main/packages/cli/README.md)
- [packages/cli/package.json](https://github.com/getmembook/membook/blob/main/packages/cli/package.json)
- [packages/core/README.md](https://github.com/getmembook/membook/blob/main/packages/core/README.md)
- [packages/core/package.json](https://github.com/getmembook/membook/blob/main/packages/core/package.json)
- [packages/spec/README.md](https://github.com/getmembook/membook/blob/main/packages/spec/README.md)
- [packages/spec/package.json](https://github.com/getmembook/membook/blob/main/packages/spec/package.json)
- [packages/mcp/README.md](https://github.com/getmembook/membook/blob/main/packages/mcp/README.md)
- [packages/mcp/package.json](https://github.com/getmembook/membook/blob/main/packages/mcp/package.json)
</details>

# 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 `membook@0.2.0` alongside its sub-packages `@membook/core@0.2.0`, `@membook/spec@0.2.0`, and `@membook/mcp@0.1.3` (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 membook@0.1.0: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]()).

| Package | Version | Role |
| --- | --- | --- |
| `membook` (CLI) | 0.2.0 | Human-facing commands: `init`, `status`, `verify`, `review`, `remember`, `book`, `reindex` |
| `@membook/core` | 0.2.0 | Domain logic: parse, version, write, and re-check memories |
| `@membook/spec` | 0.2.0 | The `Memfile` schema, parser, and on-disk version reporting |
| `@membook/mcp` | 0.1.3 | MCP server exposing the same operations to agents |

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

```mermaid
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 membook@0.2.0: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/core@0.1.1` 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/core@0.1.1: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 membook@0.1.1:0]()).

### CLI Commands

The CLI exposes the human's full workflow against a `Memfile` (Source: [CHANGELOG of membook@0.1.0: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/mcp@0.1.2` applied the same change to `SERVER_VERSION` so what the agent sees matches what was actually published (Source: [CHANGELOG of membook@0.1.2: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/mcp@0.1.3` listing `@membook/spec@0.2.0` and `@membook/core@0.2.0`) (Source: [CHANGELOG of @membook/mcp@0.1.3: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.

---

<a id='page-packages-core-src'></a>

## Src

### Related Pages

Related topics: [Overview](#page-overview), [Cli](#page-packages-cli)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/core/src/book.test.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/book.test.ts)
- [packages/core/src/book.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/book.ts)
- [packages/core/src/distill.test.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/distill.test.ts)
- [packages/core/src/distill.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/distill.ts)
- [packages/core/src/errors.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/errors.ts)
- [packages/core/src/fake-secrets.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/fake-secrets.ts)
</details>

# 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 `membook@0.2.0` ships:

| Package | Role | Key entry under `src/` |
|---|---|---|
| `membook` (root CLI) | Human-facing command surface | CLI command handlers |
| `@membook/core` | Domain logic: file I/O, distillation, book state | `book.ts`, `distill.ts`, `errors.ts`, `fake-secrets.ts` |
| `@membook/spec` | Memfile version parsing and serialization | `parseMemfile` and `Memfile.version` writers |
| `@membook/mcp` | Model Context Protocol server for agents | MCP tool adapters over `core` |

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 `membook@0.2.0`, `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.

```mermaid
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.

---

<a id='page-packages-cli'></a>

## Cli

### Related Pages

Related topics: [Src](#page-packages-core-src), [Src](#page-packages-cli-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- Source: [packages/cli/CHANGELOG.md](https://github.com/getmembook/membook/blob/main/packages/cli/CHANGELOG.md)
- Source: [packages/cli/LICENSE](https://github.com/getmembook/membook/blob/main/packages/cli/LICENSE)
- Source: [packages/cli/README.md](https://github.com/getmembook/membook/blob/main/packages/cli/README.md)
- Source: [packages/cli/package.json](https://github.com/getmembook/membook/blob/main/packages/cli/package.json)
- Source: [packages/cli/src/cli.test.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.test.ts)
- Source: [packages/cli/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.ts)
</details>

Source Files</summary>

The following source files were used to generate this page:

- [packages/cli/CHANGELOG.md](https://github.com/getmembook/membook/blob/main/packages/cli/CHANGELOG.md)
- [packages/cli/LICENSE](https://github.com/getmembook/membook/blob/main/packages/cli/LICENSE)
- [packages/cli/README.md](https://github.com/getmembook/membook/blob/main/packages/cli/README.md)
- [packages/cli/package.json](https://github.com/getmembook/membook/blob/main/packages/cli/package.json)
- [packages/cli/src/cli.test.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.test.ts)
- [packages/cli/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.ts)
</details>

# Cli

The `membook` CLI is the human-facing surface of the membook project. It lives in the [`packages/cli`](https://github.com/getmembook/membook/blob/main/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:

| Command   | Purpose |
|-----------|---------|
| `init`    | Scaffold a new `Memfile` in the current project. |
| `status`  | Report the current state of memories (counts, staleness, freshness). |
| `verify`  | Run a deterministic check that memories are still consistent. |
| `review`  | Interactively walk through memories for human approval. |
| `remember`| Append or update a memory entry. |
| `book`    | Render or print the assembled memory book. |
| `reindex` | Rebuild derived indexes used by retrieval. |

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

```mermaid
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]().

---

<a id='page-packages-cli-src'></a>

## Src

### Related Pages

Related topics: [Cli](#page-packages-cli), [Commands](#page-packages-cli-src-commands)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/cli/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.ts)
- [packages/cli/src/cli.test.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.test.ts)
- [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
- [packages/cli/src/commands/distill.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/distill.ts)
- [packages/cli/src/commands/hook.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/hook.ts)
- [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
</details>

# Src

The `src/` directories inside each package form the executable surface of membook. They hold the TypeScript source that compiles to the published `membook` CLI, the `@membook/mcp` server, and the supporting `@membook/core` and `@membook/spec` libraries. The tree is split per-package, with each `src/` containing its own entry point, command modules, and co-located tests.

## Repository Layout

The repository is a pnpm/turbo monorepo. The CLI package (`packages/cli/src/`) is the human-facing surface, while the MCP package (`packages/mcp/src/`) is the agent-facing surface. Both delegate parsing, indexing, and review logic to `@membook/core`, and both consume the file format described by `@membook/spec`.

| Directory | Role |
| --- | --- |
| `packages/cli/src/` | CLI entry point and command implementations |
| `packages/mcp/src/` | MCP server tools, mirroring CLI commands |
| `packages/core/src/` | Parsing, indexing, review, and re-check logic |
| `packages/spec/src/` | Memfile format definitions and `parseMemfile` |

Source: [packages/cli/src/cli.ts:1-40]()

## CLI Entry Point

`cli.ts` wires every user-facing subcommand. It exports the yargs configuration and dispatches to the handlers under `commands/`. The module also resolves the runtime version by reading `package.json` rather than a hardcoded literal, so the published CLI and the MCP `SERVER_VERSION` stay aligned. Source: [packages/cli/src/cli.ts:1-120]()

A co-located `cli.test.ts` covers argument parsing, default command selection, and the `--version` flag. Source: [packages/cli/src/cli.test.ts:1-200]()

## Command Modules

Each command lives in its own file under `packages/cli/src/commands/`. The pattern keeps handlers small, independently testable, and easy to surface through the MCP server in parallel.

### init and status

`init.ts` bootstraps a workspace: it creates the directory layout, writes a starter `Memfile`, and prints next-step guidance. `status.ts` reports file counts, index freshness, and pending re-checks so the human can decide whether to run `verify`, `review`, or `reindex`. These two commands are the on-ramp for new repositories. Source: [packages/cli/src/commands/init.ts:1-80]()

### distill, remember, book

`distill.ts` turns raw session material into structured memory entries; `remember.ts` appends a single memory through the interactive prompt; `book.ts` curates and trims the active set. All three funnel into the same `core` write path so that versioning, signing, and index updates are consistent regardless of entry point. Source: [packages/cli/src/commands/distill.ts:1-160]()

### hook and misc

`hook.ts` registers git hooks so that `verify` and `reindex` can run automatically. `misc.ts` collects smaller commands (`verify`, `reindex`, `review`) that do not warrant their own file. `review` re-flows hard-wrapped memory bodies before display and re-asks on input it does not recognize, a behavior introduced in `membook@0.1.1`. Source: [packages/cli/src/commands/hook.ts:1-60](), Source: [packages/cli/src/commands/misc.ts:1-200]()

## Cross-Cutting Concerns

Three behaviors cut across every command and are worth knowing before reading individual handlers.

1. **Version awareness.** As of `membook@0.2.0`, `parseMemfile` reports the on-disk `Memfile.version`, and the write side stamps that field. Commands therefore branch on the declared version rather than inferring it from content. Source: [packages/cli/src/commands/misc.ts:40-90]()
2. **Safe re-check verdicts.** A model may fail to restore a memory but must not destroy it. LLM re-check `invalidate` verdicts are downgraded to `stale` so the entry survives for human review. Source: [packages/cli/src/commands/misc.ts:90-160]()
3. **Runtime version reporting.** Both `membook --version` and `SERVER_VERSION` read `package.json` at startup so the value matches the published artifact. Source: [packages/cli/src/cli.ts:1-40]()

## Test Co-location

Tests live next to the modules they exercise (`cli.test.ts` beside `cli.ts`, command-level specs beside each handler). This makes the `src/` tree self-describing: opening a directory reveals both the behavior and the contract that guards it. Source: [packages/cli/src/cli.test.ts:1-200]()

## Suggested Reading Order

For a new contributor, the most efficient path through the source tree is:

1. `packages/spec/src/` to learn the Memfile format and `parseMemfile`.
2. `packages/core/src/` to see how parsing feeds indexing and review.
3. `packages/cli/src/cli.ts` to understand command dispatch.
4. Individual files under `packages/cli/src/commands/` for the handlers you intend to change.

Source: [packages/cli/src/cli.ts:1-120](), Source: [packages/cli/src/commands/init.ts:1-80](), Source: [packages/cli/src/commands/distill.ts:1-160](), Source: [packages/cli/src/commands/hook.ts:1-60](), Source: [packages/cli/src/commands/misc.ts:1-200]()

---

<a id='page-packages-cli-src-commands'></a>

## Commands

### Related Pages

Related topics: [Src](#page-packages-cli-src), [Src](#page-packages-mcp-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/cli/src/commands/distill.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/distill.ts)
- [packages/cli/src/commands/hook.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/hook.ts)
- [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
- [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
- [packages/cli/src/commands/review.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/review.ts)
- [packages/cli/src/commands/seed.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/seed.ts)
</details>

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

| Command | Purpose |
| --- | --- |
| `init` | Bootstrap a new `Memfile` in the current directory |
| `remember` | Persist a new memory entry into the `Memfile` |
| `book` | Mark or commit a memory for retention |
| `review` | Walk through stored memories and re-flow hard-wrapped bodies for display |
| `reindex` | Rebuild the derived index used by the MCP server |
| `status` | Show the current state of the `Memfile` and index |
| `verify` | Validate memory integrity and LLM verdicts |
| `seed` | Seed an empty `Memfile` with starter content |
| `distill` | Consolidate memories into higher-level summaries |
| `hook` | Install or remove git/editor integration hooks |

Source: [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
Source: [packages/cli/src/commands/review.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/review.ts)
Source: [packages/cli/src/commands/seed.ts](https://github.com/getmembook/membook/blob/main/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](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
Source: [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
Source: [packages/cli/src/commands/seed.ts](https://github.com/getmembook/membook/blob/main/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](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/review.ts)
Source: [packages/cli/src/commands/distill.ts](https://github.com/getmembook/membook/blob/main/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](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/hook.ts)
Source: [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
Source: [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)

## Command Flow

```mermaid
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](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
Source: [packages/cli/src/commands/review.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/review.ts)
Source: [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/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.

---

<a id='page-packages-mcp-src'></a>

## Src

### Related Pages

Related topics: [Commands](#page-packages-cli-src-commands)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/membook/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/membook/src/cli.ts)
- [packages/membook/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/membook/src/index.ts)
- [packages/membook/src/commands/review.ts](https://github.com/getmembook/membook/blob/main/packages/membook/src/commands/review.ts)
- [packages/mcp/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/index.ts)
- [packages/mcp/src/server.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/server.ts)
- [packages/mcp/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/cli.ts)
- [packages/spec/src/parser.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/parser.ts)
- [packages/spec/src/version.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/version.ts)
- [packages/core/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index.ts)
- [packages/core/src/llm.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/llm.ts)
</details>

# Src

The `src/` directories in the membook monorepo host the executable TypeScript that powers both the human-facing CLI and the agent-facing MCP server. The repository is organized as a pnpm workspace with four primary packages — `membook` (CLI), `@membook/mcp` (Model Context Protocol server), `@membook/spec` (file format), and `@membook/core` (domain logic) — each with its own `src/` tree. The release notes consistently treat `src/` as the place where runtime behavior is implemented, with build outputs produced separately via the workspace's bundler. Source: [packages/membook/src/cli.ts:1-40]()

## Package Layout

The monorepo uses a clear separation between the human surface (CLI) and the agent surface (MCP), sharing a common domain layer.

| Package | Entry point | Surface | Primary role |
|---------|-------------|---------|--------------|
| `membook` | `packages/membook/src/cli.ts` | Human CLI | Commands: `init`, `status`, `verify`, `review`, `remember`, `book`, `reindex` |
| `@membook/mcp` | `packages/mcp/src/server.ts` | Agent / MCP | Exposes the same operations as MCP tools |
| `@membook/spec` | `packages/spec/src/parser.ts` | Shared | Parses and emits the on-disk memfile format |
| `@membook/core` | `packages/core/src/index.ts` | Shared | Domain logic, LLM re-check, lifecycle |

The CLI and MCP server intentionally do not duplicate domain logic; both delegate to `@membook/core`, and both speak the format defined in `@membook/spec`. Source: [packages/mcp/src/index.ts:1-30](), [packages/membook/src/index.ts:1-25]()

## CLI Source (`packages/membook/src/`)

The CLI's `src/` directory contains the command dispatcher and one file per subcommand. The `cli.ts` entry resolves the user's invocation, prints `--version` by reading `package.json` at runtime rather than from a baked-in string, and forwards to the matching command module. Source: [packages/membook/src/cli.ts:1-60]()

Command modules are responsible for their own argument parsing and output formatting. For example, the `review` command re-flows hard-wrapped memory bodies before display and re-prompts the user when input is not recognized, so that long memories do not appear as ragged prose in the terminal. Source: [packages/membook/src/commands/review.ts:1-80]()

The other commands follow a similar pattern:

- `init` — scaffolds a new memfile in the working directory.
- `status` — reports counts and lifecycle distribution.
- `verify` — runs structural and content checks against a memfile.
- `remember` — interactively captures a new memory.
- `book` — finalizes and locks a memfile.
- `reindex` — rebuilds the search index.

Source: [packages/membook/src/cli.ts:60-140]()

## MCP Source (`packages/mcp/src/`)

The MCP package is the agent-facing counterpart to the CLI. Its `src/` directory contains the protocol implementation and a CLI wrapper used to launch the server.

`server.ts` registers the tools that an LLM agent can call. These tools map one-to-one onto the CLI's subcommands, so an agent invoking `membook__status` receives the same response shape a human gets from `membook status`. The server's `SERVER_VERSION` constant is read from `package.json` at startup, matching the CLI's runtime version behavior so both surfaces report the same build. Source: [packages/mcp/src/server.ts:1-100](), [packages/mcp/src/cli.ts:1-40]()

`index.ts` is the programmatic entry; it constructs the server, wires it to the transport, and exposes a `start()` function. `server.test.ts` covers tool registration, request/response shapes, and version reporting. Source: [packages/mcp/src/index.ts:1-50](), [packages/mcp/src/server.test.ts:1-120]()

## Spec and Core Source

The shared layers live in their own `src/` trees and are imported by both CLI and MCP.

`@membook/spec/src/parser.ts` defines `parseMemfile`, which reads a memfile from disk and returns its parsed shape, including the `Memfile.version` field that records the file format version the file declared on disk. This is the read half of the memfile version machinery introduced in v0.2.0; the write half lives in `version.ts` and is what the CLI and MCP use when emitting new memfiles, landing before v2 of the format actually needs it. Source: [packages/spec/src/parser.ts:1-120](), [packages/spec/src/version.ts:1-60]()

`@membook/core/src/llm.ts` houses the LLM re-check that decides whether an existing memory is still valid. The principle enforced here is that a model may fail to restore a memory but it may not destroy one — an LLM `invalidate` verdict therefore lands as `stale` rather than deleting the entry, preserving human-set content until a human reviews it. Source: [packages/core/src/llm.ts:1-90](), [packages/core/src/index.ts:1-50]()

## Cross-Package Flow

```mermaid
flowchart LR
  H[Human] -->|membook ...| CLI[packages/membook/src]
  A[Agent] -->|MCP tools| MCP[packages/mcp/src]
  CLI --> Core[packages/core/src]
  MCP --> Core
  CLI --> Spec[packages/spec/src]
  MCP --> Spec
  Core --> Spec
  Spec --> Disk[(memfile on disk)]
```

Both surfaces share the same domain and format code, so behavior changes — such as the LLM re-check softening `invalidate` to `stale` in v0.1.1 or the memfile version machinery landing in v0.2.0 — are picked up by every consumer at once. Source: [packages/core/src/llm.ts:40-80](), [packages/spec/src/parser.ts:30-90]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: getmembook/membook

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/getmembook/membook

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: membook@0.1.0
- User impact: Upgrade or migration may change expected behavior: membook@0.1.0
- 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/getmembook/membook

## 4. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: @membook/mcp@0.1.2
- User impact: Upgrade or migration may change expected behavior: @membook/mcp@0.1.2
- 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
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: membook@0.1.2
- User impact: Upgrade or migration may change expected behavior: membook@0.1.2
- 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
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/getmembook/membook

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/getmembook/membook

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/getmembook/membook

## 9. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: @membook/core@0.1.1
- User impact: Upgrade or migration may change expected behavior: @membook/core@0.1.1
- 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
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: @membook/core@0.2.0
- User impact: Upgrade or migration may change expected behavior: @membook/core@0.2.0
- 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
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: @membook/spec@0.2.0
- User impact: Upgrade or migration may change expected behavior: @membook/spec@0.2.0
- 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
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: membook@0.1.1
- User impact: Upgrade or migration may change expected behavior: membook@0.1.1
- Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.1

## 13. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: membook@0.2.0
- User impact: Upgrade or migration may change expected behavior: membook@0.2.0
- Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.2.0

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/getmembook/membook

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/getmembook/membook

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @membook/mcp@0.1.1
- User impact: Upgrade or migration may change expected behavior: @membook/mcp@0.1.1
- Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.1

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: @membook/mcp@0.1.3
- User impact: Upgrade or migration may change expected behavior: @membook/mcp@0.1.3
- Evidence: failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.3

<!-- canonical_name: getmembook/membook; human_manual_source: deepwiki_human_wiki -->