CLI reference

The memory CLI is the reference interface to a brain. It’s shipped by every SDK and exposes the same subcommand surface across TypeScript, Go, and Python.

Exit codes:

• 0 — success.
• 1 — expected runtime failure (network, missing brain, invalid config).
• 2 — usage error (bad flags, missing required positional).

Global environment variables

memory init <path>

Create a new brain directory with git-backed storage.

memory init ./my-brain

Output: a JSON line {"brain":"./my-brain","ok":true}.

memory ingest <file>

Ingest a file into the brain. Chunks the content, writes it to the store, and upserts the chunks into the SQLite index.

memory ingest ./docs/hedgehogs.md --brain ./my-brain

Flags:

• --brain <path> — override the default brain directory (also set via JB_BRAIN).

Output: a JSON line with path, hash, bytes, and skipped (null when new, otherwise the reason).

memory search <query>

Run a hybrid BM25 + vector query against the brain.

memory search "where do hedgehogs live?" --brain ./my-brain
memory search "hedge*" --mode bm25 --json --limit 20

Flags:

• --brain <path> — override the default brain directory.
• --mode <hybrid|bm25|semantic|auto> — default auto. Resolves to hybrid with an embedder, bm25 without.
• --rerank — apply reranking (reserved; currently a no-op).
• --json — emit JSON results on stdout instead of human-friendly text.
• --limit <N> — maximum number of results (default 10).

memory extract

Submit a transcript so the server can asynchronously derive memorable facts. Delegates to the same logic as the memory_extract MCP tool.

memory reflect

Close a session and trigger reflection. Mirrors memory_reflect.

memory consolidate

Trigger a compaction pass over memory/ and wiki/. Mirrors memory_consolidate. Reserved; today delegates to brains.compile where available.

memory remember (Go only)

Capture a single, atomic memory note.

memory remember "I prefer British English in code" --tags style,english

memory recall (Go only)

Recall memories for a query, optionally weighted by session context.

memory recall "style preferences" --limit 5

memory serve

Start the HTTP daemon that speaks the protocol.

memory serve --host 127.0.0.1 --port 8080

Flags:

• --host <host> — bind address (default 127.0.0.1).
• --port <port> — listen port (default 8080).
• --home <path> — override JB_HOME for this process.

memory acl (TS only)

Manage OpenFGA-backed authorisation when the brain is wired to @jeffs-brain/memory-openfga. See acl.ts.

memory git (TS only)

Helpers for the git-backed store: sign a commit, push, fetch, check status. See git.ts.

memory eval (TS only)

Run the LongMemEval harness against the brain. See lme.ts and the LongMemEval page.

memory create-brain / memory list-brains (Go only)

Create or list brains hosted at the configured endpoint. Mirror memory_create_brain and memory_list_brains.

Parity matrix

All three SDKs implement the full canonical command surface. The shared HTTP conformance suite sits at 28/29 green across SDKs and the tri-SDK smoke benchmark scores identically (19/20) on each.