Memoir

Memory server

First committed by zhangfengcdt

Published in zhangfengcdt/memoir. Publisher page

629 GitHub starsUpdated 2026-10-27

What it is

Hierarchical Agent Memory with Git-Like Version Control

— the description by zhangfengcdt

AutoGineer overview, from the brain’s own files

Memoir is a memory system designed to replace opaque vector databases with a transparent, versioned, and cryptographically secure storage layer. By utilizing ProllyTrees, it enables hierarchical semantic paths instead of UUIDs, allowing for efficient O(log n) lookups. It addresses common AI memory issues like context contamination and token waste by providing branch, commit, merge, and rollback capabilities. Memoir integrates with various agents through plugins and an MCP server, supporting both keyword-based and LLM-powered semantic search.

How it works

Memory model: Not stated

AutoGineer overview, from the brain’s own files

Memoir organizes memory into a hierarchical structure using semantic paths, such as profile.professional.skills.python. It uses a ProllyTree-based store to manage data, allowing for Git-like operations such as branching and versioning. The system includes a classifier to categorize memories and a search engine for retrieval. It provides a CLI for manual interaction, hooks for automatic memory capture in supported agents, and an MCP server for integration with various AI development tools.

Folders
Folder	Role	Files
.github	agent-config	10
docs	docs	41
scripts	scripts	9
src	source-code	216
tests	tests	53
.agents	folder	1
.claude-plugin	folder	1
benchmarks	folder	10
packaging	folder	3
plugins	folder	187
static	folder	2

The agent writes

create_if_missing evidence: CLAUDE.md

Requirements

Runtimes: Python >=3.10

API keys (by name): ANTHROPIC_API_KEY, OPENAI_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

This brain runs code automatically: 7 hooks (claude-code, codex), 2 scripts. Review Makefile, README.md, plugins/claude-code/hooks/hooks.json, plugins/codex/hooks/hooks.json before opening the folder in Claude Code. No step below turns a hook on for you.
- Makefile: pip install -e .
- README.md: curl -LsSf https://astral.sh/uv/install.sh | sh
- plugins/claude-code/hooks/hooks.json: bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh
- plugins/claude-code/hooks/hooks.json: bash ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh
- plugins/claude-code/hooks/hooks.json: bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh
- plugins/claude-code/hooks/hooks.json: bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh
- plugins/codex/hooks/hooks.json: bash "${PLUGIN_ROOT}/hooks/session-start.sh"
- plugins/codex/hooks/hooks.json: bash "${PLUGIN_ROOT}/hooks/user-prompt-submit.sh"
- plugins/codex/hooks/hooks.json: bash "${PLUGIN_ROOT}/hooks/stop.sh"
Not scanned by AutoGineerThe author’s README also describes installing it as a Claude Code plugin marketplace. Read its install section: AutoGineer did not scan that path. https://github.com/zhangfengcdt/memoir/blob/7fd1b3ef704fc554596571d5b9c8b73d7f2b0c5d/README.md#install-a-plugin-for-your-agent
Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (7 declared). https://pypi.org/project/memoir-ai/
First committed by zhangfengcdt. Published in zhangfengcdt/memoir. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

CLI-based memory management
Automatic context injection for coding agents
Version-controlled memory branching
Semantic search across stored facts
Cross-machine memory synchronization

“memoir remember "I prefer using Python for data analysis" -p preferences.coding.languages”: Stores the fact under the specified semantic path for later retrieval.
“memoir recall "what are my coding preferences?"”: Performs a semantic search to retrieve the relevant stored memory.

Documentation by zhangfengcdt

Memoir

Git for AI Memory

Hierarchical Memory with Git-Like Version Control

</div>

Image: Python Image: License Image: Status Image: Website Image: Docs

Memoir is a high-performance semantic memory system for AI agents that brings Git-like version control to AI memory management. It replaces opaque vector databases with transparent, versioned, cryptographically secure memory storage using hierarchical semantic paths.

Project page: memoir-ai.dev — full overview, demos, and roadmap.

Why agents need versioned memory

AI memory is a Global Variable anti-pattern. Every production agent hits the same three walls: context contamination, token rent, and memory drift. Memoir brings version control to your agent's mind.

Your agent doesn't respect your git state. Context contamination happens every time you git checkout. Without branch-aware memory, your agent tries to apply experimental refactor patterns to stable production hotfixes.

You're paying "token rent" on a flat file. Using CLAUDE.md or MEMORY.md as a global store is a cache-killer. Every minor memory update invalidates your entire prefix cache, forcing you to pay full price to re-process your entire conversation.

Your agent's memory is code without version control. Today's AI memory — CLAUDE.md, vector stores, scratchpads — is treated like an append-only blob. One bad session poisons every future retrieval. Without memoir blame or memoir checkout, there's no way to audit who taught the agent a rule or revert a hallucination without wiping the whole store.

Key Features

Git-like Versioning — Branch, commit, merge, and rollback memories with cryptographic integrity.
Semantic Paths — Replace UUID keys with meaningful paths like profile.professional.skills.python.
O(log n) Lookups — Fast hierarchical search instead of expensive vector operations.
Memory Aggregation — Automatic consolidation of related memories at semantic locations.
Clean Architecture — Proper separation of storage, classification, and search layers.
Multiple Search Engines — Choose between fast keyword-based or intelligent LLM-powered search.

Install from PyPI

pip install memoir-ai

The distribution name on PyPI is memoir-ai. The Python import is import memoir and the CLI is memoir.

Install a plugin for your agent

Memoir ships as a plugin for several coding and personal-assistant agents. Expand the one you use:

<details> <summary>Claude Code</summary>

Inside a Claude Code session, run:

/plugin marketplace add zhangfengcdt/memoir
/plugin install memoir@memoir

No manual pip install needed if you have uv on PATH — the plugin auto-resolves to uvx --from memoir-ai memoir when the bare memoir binary isn't installed. Don't have uv? Install it once with the standard one-liner:

curl -LsSf https://astral.sh/uv/install.sh | sh

That's enough — the plugin handles the rest. It registers hooks for session start, user-prompt-submit, and stop, so your project gets automatic context injection and auto-captured memories. See the Claude Code plugin guide for the full slash-command and hook reference.

</details>

<details> <summary>Codex</summary>

Memoir's Codex plugin is distributed from this repository's Codex marketplace. In Codex, run /plugins, add the memoir marketplace from zhangfengcdt/memoir, restart Codex if prompted, then choose Memoir Plugins and install memoir.

You can also register the marketplace from the CLI:

codex plugin marketplace add zhangfengcdt/memoir

While developing from a local checkout, use codex plugin marketplace add /absolute/path/to/memoir instead. The repo marketplace lives at .agents/plugins/marketplace.json and points Codex at ./plugins/codex, relative to the repository root.

No manual pip install needed if you have uv on PATH — the Codex plugin resolves the Memoir CLI the same way the Claude Code plugin does: memoir on PATH first, then uvx --from memoir-ai==<pinned> memoir, then uv tool run --from memoir-ai==<pinned> memoir.

Enable Codex hooks with [features].hooks = true in ~/.codex/config.toml or pass --enable hooks for a smoke run. The Codex plugin ships lifecycle hooks; memory-recall, memoir-onboard, memoir-remember, memoir-status, and memoir-ui skills; Codex-specific transcript parsing; and local marketplace metadata. See the Codex plugin guide for setup, limitations, and the real Codex smoke-test flow.

</details>

<details> <summary>Hermes</summary>

Memoir is a memory provider for Hermes, the Nous Research personal-assistant agent. Install the plugin into your Hermes home and activate it:

hermes plugins install zhangfengcdt/memoir/plugins/hermes   # or: cp -r plugins/hermes ~/.hermes/plugins/memoir
hermes memory setup                                         # choose "memoir"

Hermes then auto-captures durable facts (people, schedule, preferences, standing instructions) each turn and exposes memoir_recall / memoir_remember / memoir_forget / memoir_sync / memoir_status tools. Capture/classification run on your host-selected model via direct provider APIs (never the claude CLI). See the Hermes plugin guide for install, configuration, model selection, and proxy routing.

</details>

<details> <summary>OpenClaw (community)</summary>

Memoir is a memory plugin for OpenClaw, the personal-assistant gateway. It lives in its own repo, zhangfengcdt/openclaw-memoir. Install it into the memory slot, allow conversation access, and restart the gateway:

openclaw plugins install https://github.com/zhangfengcdt/openclaw-memoir   # or: --link /path/to/openclaw-memoir
openclaw config set plugins.entries.memory-memoir.hooks.allowConversationAccess true
systemctl --user restart openclaw-gateway

OpenClaw then auto-captures durable facts each turn (remembered across your sessions by default) and exposes memoir_recall / memoir_remember / memoir_forget / memoir_status tools plus an in-chat /memoir command. Set a capture model + provider key in config — plugins.entries.memory-memoir.config.{model,apiKey} (OpenClaw keeps its own keys in a secret store; use a temperature=0-capable model like anthropic/claude-haiku-4-5). See the OpenClaw plugin guide for configuration, scoping, model selection, and tool-profile notes.

</details>

<details> <summary>OpenCode (community)</summary>

opencode-memoir is a community-maintained plugin that brings Memoir's long-term memory workflows to OpenCode through its native plugin system. Follow the install instructions in that repository.

</details>

<details> <summary>Any MCP host (Claude Desktop, Cursor, Cline, Windsurf, VS Code, Zed, …)</summary>

Memoir ships an MCP server (memoir-mcp) on the official Model Context Protocol SDK, so any MCP-compatible host gets git-versioned memory — including the memoir_branches / memoir_checkout / memoir_commits versioning tools no other memory server has. No install needed if you have uv; add to your host's mcpServers config:

{
  "mcpServers": {
    "memoir": {
      "command": "uvx",
      "args": ["--from", "memoir-ai[mcp]", "memoir-mcp"],
      "env": { "MEMOIR_STORE": "~/.memoir/mcp" }
    }
  }
}

Recall is LLM-free by default (keyless), with opt-in single-call or multi-level tiered LLM modes; the store auto-creates on first use. See the MCP server guide for per-host config (VS Code/Zed/Continue/LibreChat differ slightly), recall modes + LLM setup, remote HTTP for ChatGPT/Claude.ai connectors, and the one-click Claude Desktop .mcpb.

</details>

Quick look

Memoir's CLI defaults to Anthropic claude-haiku-4-5 as of v0.1.6 — set your key first:

export ANTHROPIC_API_KEY="sk-..."

Note that if you do not set any model api keys, it will try to use the claude -p command to authenticate via claude code's subscription.

Then create a store and round-trip a memory:

# 1. Create a memoir store
memoir new my-memoir-store
cd my-memoir-store

# 2. Store with an explicit path (offline, no LLM call)
memoir remember "Sarah prefers tabs and 2-space indents" -p preferences.coding.style

# 3. Store with auto-classification (LLM picks the path; needs API key)
memoir remember "I work in Pacific time"

# 4. Read back by path (offline)
memoir get preferences.coding.style

# 5. Semantic search (LLM-backed)
memoir recall "what does Sarah prefer?"

# 6. Watch a file by indexing it on the fly
memoir watch add ~/papers/transformer.pdf -n research

# 7. Search the indexed content
memoir search "transformer attention mechanism"

# 8. Open the visual explorer (auto-opens in your browser)
memoir ui

Curious what the UI looks like before installing? Browse the UI Gallery.

Prefer a different model? memoir recall "..." --model gpt-4o-mini (needs OPENAI_API_KEY), or set MEMOIR_LLM_MODEL in your shell. Resolution order: --model flag → MEMOIR_LLM_MODEL → claude-haiku-4-5.

See the full Quickstart for the Python API and version-control workflow.

Documentation

Full docs live at zhangfengcdt.github.io/memoir:

Quickstart — five-minute tour of the core loop.
CLI Reference — every command, flag, and exit code.
UI — the visual explorer (Tree / Graph / Timeline / Places + /stats).
Claude Code — plugin install, slash commands, hooks, lifecycle.
Codex — plugin install, hooks, skills, transcript parsing, smoke-test evidence.
Architecture — taxonomy, classifier, store, search.
API Reference — Python SDK.
Examples — context branching, memory debugging, reproducible testing.

Contributing

Memoir is alpha and contributions are very welcome — especially from people building coding agents, since that's the audience we're optimizing for. Good first paths in:

Pick an issue from the issue tracker or open one describing a gap.
Fork the repo, branch off main, and run make ci before opening a PR (lint, tests, docs build must be green).
Bug reports with a minimal reproducer and benchmark / taxonomy proposals for coding-agent use cases are particularly appreciated.

License

Apache License 2.0 — see LICENSE.

docs/hermes.md

Hermes Plugin

Memoir ships a memory-provider plugin for Hermes, the Nous Research personal-assistant agent. Activate it and Hermes gains versioned, semantic long-term memory: a git-like store (branch / commit / merge) over a Prolly-tree with semantic paths and cryptographic provenance. Unlike vector-only backends (Mem0, Zep, Letta), every write is a commit you can inspect (memoir log), attribute (memoir blame), and time-travel.

The plugin lives in the repo at plugins/hermes/.

How it fits Hermes

Hermes has a pluggable MemoryProvider slot — exactly one external provider is active at a time, selected by memory.provider in ~/.hermes/config.yaml. The built-in MEMORY.md / USER.md layer stays active alongside it. Memoir fills that slot.

It is a directory plugin, not a pip/entry-point package: Hermes loads memory providers by scanning $HERMES_HOME/plugins/<name>/, so the plugin is installed as a directory there. It holds no memoir code in-process — it shells out to the memoir CLI over a stdlib-only subprocess bridge, so the Prolly-tree self-resolves concurrent (fire-and-forget) writes with no locking.

Install

The plugin needs two things on the machine: the plugin directory in your Hermes home, and the memoir CLI reachable on PATH.

1. Install the memoir CLI

pip install memoir-ai        # or: pipx install memoir-ai / uv tool install memoir-ai

The bridge resolves memoir on PATH first, falling back to a pinned uvx --from memoir-ai==<pin> memoir (then uv tool run) when it isn't installed. A direct install is faster (no warmup).

2. Install the plugin

Via the Hermes CLI (once the plugin is on the repo's default branch):

hermes plugins install zhangfengcdt/memoir/plugins/hermes

Hermes clones the repo, takes the plugins/hermes subdirectory, reads its plugin.yaml (name: memoir), and installs it to ~/.hermes/plugins/memoir/.

By copy (works today, from a local checkout):

cp -r plugins/hermes ~/.hermes/plugins/memoir
rm -rf ~/.hermes/plugins/memoir/tests ~/.hermes/plugins/memoir/__pycache__

3. Activate it

hermes memory setup        # interactive picker — choose "memoir"

hermes memory setup writes memory.provider: memoir to ~/.hermes/config.yaml. (You can also set that key by hand.) Activating memoir displaces any other external provider (mem0, honcho, …) — only one runs at a time.

The store is created automatically on first run at <hermes_home>/memoir-store (override with store_path in config). You'll need a provider API key in the Hermes environment — see LLM backend.

What ships

Component	Count	Role
Tools (model-facing)	7	`memoir_summarize`, `memoir_get`, `memoir_recall`, `memoir_remember`, `memoir_forget`, `memoir_sync`, `memoir_status`
Lifecycle hooks	5	Auto-capture, recall context, store mirroring
CLI subcommands	2	`hermes memoir status`, `hermes memoir ui`
Slash command	1 (opt-in)	`/memoir …` — in-session passthrough to the memoir CLI

The model-facing tools above are the primary in-chat surface (the model calls them). There's also an opt-in /memoir slash command for power users — see The /memoir command.

Tools

The model decides when to call these (guided by their descriptions and the injected system-prompt block); they are not typed by the user.

Recall is caller-driven by default: the model calls memoir_summarize to see the stored paths, picks the relevant ones, then memoir_gets them — the model selects what to read, with no in-memoir LLM call. memoir_recall remains as a one-shot keyword shortcut.

Tool	Purpose
`memoir_summarize`	Step 1 of recall. List stored paths as a histogram grouped by the first `depth` taxonomy segments; `prefix` narrows a branch. The model reads this and picks paths. LLM-free.
`memoir_get`	Step 2 of recall. Fetch the exact memories at the paths the model chose. Missing keys are omitted. LLM-free.
`memoir_recall`	One-shot recall shortcut: `summarize` → batched `get`, ranked by lexical overlap with the query. LLM-free.
`memoir_remember`	Store an explicit durable fact. Classified into a semantic path and committed. Guarded against obvious secrets.
`memoir_forget`	Delete a fact by its exact taxonomy path (the model finds the path via `memoir_recall` first). Pre-checks existence so a wrong path can't create a no-op delete commit; prior versions remain in git history (recoverable).
`memoir_sync`	Promote a session fork's memories into `main`. No args → list fork branches with un-merged memories (preview counts); `branch` → merge it into `main` (`dry_run` to preview). Additive (insert/update, never delete).
`memoir_status`	Store status: branch, commit count, memory count.

Lifecycle hooks

These are called by Hermes automatically — they don't depend on the model invoking a tool, so capture is guaranteed even if the model never calls memoir_remember.

Hook	When	Purpose
`initialize`	agent startup	Derive + ensure the store, resolve the model, cache an overview.
`system_prompt_block`	prompt assembly	Inject recall guidance + a short store overview.
`sync_turn`	after every turn	Fire-and-forget `memoir capture --profile assistant` over the turn.
`on_pre_compress` / `on_session_end`	compression / session end	Capture the uncaptured message tail.
`on_session_switch`	`/branch`, `/resume`, `/reset`	Route the store's branch to match the session — see Session branching.
`on_memory_write`	built-in memory edit	Mirror Hermes's `MEMORY.md` / `USER.md` writes into versioned memoir paths.

Capture runs on a background thread and never blocks the response. Writes are skipped for non-primary agent contexts (subagent / cron / flush) so they can't corrupt the user's representation.

The `/memoir` command

An optional in-session slash command that passes through to the memoir CLI on your store — handy for inspecting memory without leaving the chat:

/memoir status
/memoir summarize --depth 3
/memoir recall "travel plans"
/memoir branch
/memoir blame profile.personal.identity

/memoir with no args prints usage. It's user-invoked (not the model), so it simply runs memoir -s <store> <your args> and returns the output.

It's opt-in and separate from the memory provider. Hermes loads in-session slash commands only for plugins listed in plugins.enabled, which is distinct from memory.provider. So to get /memoir, enable the plugin as well:

hermes memory setup          # activates the provider (tools + auto-capture)
hermes plugins enable memoir # additionally registers the /memoir command

Without the enable step everything else still works — you just won't have the slash command. (Mechanism: the plugin ships kind: standalone so the general plugin manager can load it for the command; its register() feature-detects the load context and registers the provider or the command accordingly.)

Configuration

Config lives in <hermes_home>/memoir.json (all keys optional). Set it via hermes memory setup or by hand.

Key	Default	Meaning
`store_path`	`<hermes_home>/memoir-store`	Store location.
`capture`	`true`	Auto-capture facts from each turn. `false` disables the `sync_turn` / boundary capture; recall and tools still work.
`model`	host's selected model	Pin the LLM model for capture/classification. Empty = follow Hermes `model.default`. See Model selection.
`base_url`	provider default	Custom provider endpoint (LLM gateway/proxy). Empty = call the provider directly. See Routing through a proxy.
`session_branching`	`true`	Mirror Hermes session forks onto memoir branches. `false` keeps everything on `main`. See Session branching.
`scope`	`off`	Isolate memory per chat/profile via a namespace: `chat` (per platform+chat), `profile` (per Hermes profile), `off` (one shared store). See Scoped memory.

Example — pin cheap Haiku for per-turn capture regardless of your chat model:

{ "model": "claude-haiku-4-5" }

Model selection

memoir resolves the capture/classification model in this order:

model pin in memoir.json — always wins.
Host-selected model — Hermes model.default, tracked across mid-session model switches (on_turn_start).
memoir's built-in default — claude-haiku-4-5.

So out of the box, capture runs on the same model your Hermes session uses. That can be expensive: if your session model is Opus, every per-turn extraction is an Opus call. Pin a cheaper model (e.g. claude-haiku-4-5) in memoir.json to decouple capture cost from your chat model.

Which provider key is used?

memoir routes by model name, not by which keys are present — so setting both OPENAI_API_KEY and ANTHROPIC_API_KEY is unambiguous:

Model	Provider → key
`claude-` / `anthropic/`	Anthropic → `ANTHROPIC_API_KEY`
`gpt-*`	OpenAI → `OPENAI_API_KEY`
`gemini/*`	Gemini → `GEMINI_API_KEY`
`ollama/*`, or any model with `base_url` set	that endpoint (no key check)

Each key is consulted only when a model of its provider is selected. memoir's default model is claude-haiku-4-5 (Anthropic), so with no model specified anywhere it uses ANTHROPIC_API_KEY.

Session branching

Hermes lets you fork a conversation (/branch), jump between conversations (/resume), and start fresh (/reset / /new). With session_branching enabled (the default), the plugin mirrors that onto memoir branches so a fork's memories stay isolated from your main timeline:

/branch (fork) → creates and checks out hermes/<session-id> off the current branch. Everything captured in the fork lands there, not on main.
/resume → checks out that session's branch if it has one, otherwise returns to main. So resuming a normal (never-forked) conversation always comes back to your main timeline.
/reset / /new → back to main.
context compression → no branch change (it's the same conversation continuing under a rolled-over id, so captures stay on the current branch).

The mapping is stateless — it's derived from the session id and the branches that exist in the store — so it survives Hermes restarts. Forks branch off whatever is currently checked out, so nested forks work too. Inspect or merge branches with the memoir CLI (memoir branch, memoir merge, memoir -s <store> summarize per branch).

Set session_branching: false in memoir.json to disable this and keep all captures on main.

Promoting a fork's memories back to main. A fork's captures stay isolated on its branch. When the user wants to keep them, the memoir_sync tool promotes them into main: with no arguments it lists fork branches that have un-merged memories (with a preview of what each would add); with a branch it merges that branch into main. The merge is additive — it inserts/updates keys and never deletes — and the model drives the choose/confirm flow in conversation. (This mirrors the Claude Code plugin's /memoir:sync.) On exit the store is left on main, so forks don't accumulate as the active branch.

Single-store caveat: branch state is the store's checked-out branch, so this assumes one active session per store at a time (the personal-assistant CLI case). Concurrent sessions sharing one store would contend on the checkout.

Scoped memory

If you run Hermes across multiple chats/platforms/profiles (e.g. a private DM and a public group on the same gateway), global memory is a privacy foot-gun: a fact captured in the DM would otherwise be injected into the group. Set scope in memoir.json to isolate memory structurally:

`scope`	Each scope is…	Namespace
`off` (default)	one shared store	`default`
`chat`	a platform + chat/channel	`scope_<platform>_<chat_id>`
`profile`	a Hermes profile	`scope_profile_<name>`

How it works:

Hermes already passes platform, chat_id, and agent_identity (profile) into the provider's initialize(), so the scope key needs no extra config.
Captures and memoir_remember write to the scope's namespace.
memoir_recall reads the scope namespace ⊕ default — so global (unscoped) facts are visible everywhere, but a scoped fact never appears in another scope. Cross-scope leakage is impossible by construction (default-deny), not dependent on an injection-time filter.
memoir_forget deletes from the scope namespace, falling back to default.

Namespace vs. branch. Scoping uses memoir namespaces (parallel, composable partitions), which is the right primitive here — distinct from session branching, which uses branches (divergent timelines you can merge). They compose: a scoped session can still /fork. Namespaces are also routed per call (no shared checkout), so concurrent scoped sessions don't contend.

v1 resolves the scope once at initialize() (the session's chat/profile). Per-message re-scoping for a single provider serving many concurrent gateway sessions is future work — the namespace primitive supports it.

LLM backend

The plugin drives memoir with its litellm (direct provider API) backend only — it never shells out to the claude CLI, even when a claude binary is on PATH. A Hermes host has its own configured provider, and a typical Hermes box has no Claude Code install.

memoir reads the provider credentials from the Hermes process environment (e.g. ANTHROPIC_API_KEY in <hermes_home>/.env). If the selected model's provider key is missing, capture fails loudly ("ANTHROPIC_API_KEY required") rather than silently switching backends.

Recall is LLM-free, so it works even without a provider key. Auto-capture and explicit memoir_remember classification do need one.

Routing through a proxy

By default memoir calls the provider directly (e.g. api.anthropic.com) and does not route through any gateway Hermes itself uses — Hermes keeps its gateway/base-URL internal to its own client and never exports it to the environment. To send memoir's calls through a proxy/gateway too, set base_url in memoir.json:

{ "base_url": "https://your-gateway/v1" }

The bridge exports this as MEMOIR_LLM_BASE_URL; the credential in the environment must be valid for that endpoint.

Verify

hermes memory status            # provider: memoir
hermes memoir status            # store branch / commit count / memory count
memoir capture --help           # confirms the CLI on PATH has `capture`

End-to-end: start a Hermes session and state a durable fact ("from now on call me Captain; my dog Rex sees the vet every March"). Capture runs in the background (a few seconds), then:

memoir -s <hermes_home>/memoir-store summarize --depth 3     # captured paths
memoir -s <hermes_home>/memoir-store blame <path>            # provenance

In a new session, ask "what's my name?" — the agent should call memoir_recall and answer from memory.

Environment variables

The bridge sets these for the memoir subprocess automatically from memoir.json; you normally don't set them by hand.

Variable	Set from	Effect
`MEMOIR_LLM_BACKEND`	always `litellm`	Forces direct provider APIs; suppresses the claude-cli fallback.
`MEMOIR_LLM_MODEL`	resolved model	Model for capture/classification.
`MEMOIR_LLM_BASE_URL`	`base_url` config	Custom provider endpoint, when set.

Provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) are inherited from the Hermes process environment — set them in <hermes_home>/.env.

Manifest

plugins/hermes/plugin.yaml:

name: memoir
version: 0.1.0
description: "Memoir — versioned, semantic long-term memory with git-like branch/commit/merge and cryptographic provenance. Shells out to the memoir CLI; no Python deps."

No pip_dependencies: the provider talks to the memoir CLI over a subprocess bridge (PATH memoir, else a pinned uvx --from memoir-ai).

Limitations (v1)

Local store only. Multi-device sync (the merge-based wedge) is future work; it needs a memoir remote story.
One external provider at a time. Activating memoir displaces any other Hermes memory provider.

Advantages

Provides Git-like version control for AI memory, allowing for branching, merging, and rolling back. evidence: README.md
Uses hierarchical semantic paths for O(log n) lookups, offering better performance than traditional vector databases. evidence: README.md

Limitations

Requires an API key for LLM-powered features like intelligent classification and semantic search. evidence: README.md
Some advanced features like document watching require additional dependencies or manual configuration. evidence: pyproject.toml

Security

Risk level: Medium risk

This brain runs

Git hooks (5)

.pre-commit-config.yaml: pre-commit hooks from https://github.com/pre-commit/pre-commit-hooks at v6.0.0 (contributor tooling: runs only after pre-commit install) · uses the network
.pre-commit-config.yaml: pre-commit hooks from https://github.com/pycqa/isort at 6.0.1 (contributor tooling: runs only after pre-commit install) · uses the network
.pre-commit-config.yaml: pre-commit hooks from https://github.com/astral-sh/ruff-pre-commit at v0.12.9 (contributor tooling: runs only after pre-commit install) · uses the network
.pre-commit-config.yaml: pre-commit hooks from https://github.com/PyCQA/bandit at 1.8.6 (contributor tooling: runs only after pre-commit install) · uses the network
.pre-commit-config.yaml: pytest

Agent instructions that run or fetch something (73)

CLAUDE.md: `make ci` runs the full pipeline (lint, test, security, docs).
CLAUDE.md: tests use the fake gateway in `tests/fake_cloud.py` (real `git http-backend`, no network).
CLAUDE.md: When touching the mod run `claude plugin validate plugins/claude-code` and `claude plugin test plugins/claude-code`;
CLAUDE.md: Run with `pytest`.
CLAUDE.md: Deep structural details (layouts, refactor history, per-file line counts) intentionally omitted — use `rg` / `git log` when you need them.
CLAUDE.md: flipping it later (`git init`, or `rm -rf .git`) surfaces a warning at SessionStart but does not block writes.
CLAUDE.md: When changing a prompt, **run the harness against haiku before merging**.
CLAUDE.md: The harness has two modes: **gate** (deterministic shell-hook tests, no LLM, sub-second per case — pins the recall-trigger gate in `hooks/user-prompt-submit.sh`) and **LLM mode** (`run` / `case` / `adhoc` against `claude -p` for prompt templates).
CLAUDE.md: # Gate mode — no LLM cost, run on every commit.
CLAUDE.md: plugins/claude-code/tests/prompt-harness/runner.py run --prompt stop_capture --model haiku
CLAUDE.md: plugins/claude-code/tests/prompt-harness/runner.py run --prompt stop_capture --model sonnet
CLAUDE.md: Every run drops `system.txt` (the assembled prompt actually sent), `input.txt`, `output.txt`, `command.sh` (replayable), and `result.json` per case under `/tmp/memoir-prompt-tests/<UTC-timestamp>/`.
CLAUDE.md: Skill prompts (`skills/<name>/SKILL.md`) are evaluated by the orchestrating Claude rather than dispatched as system prompts to a model, so they are *not* covered by this harness — to test those, run the slash command in a real session and inspect behavior.
CLAUDE.md: **Build the docs locally:** `make docs` (mkdocs) → `site/index.html`, or `make docs-live` for auto-reload.
plugins/claude-code/skills/memoir-onboard/SKILL.md: bash -c 'source "${CLAUDE_PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; in_git_repo && echo codebase:onboard || echo project:onboard'
plugins/claude-code/skills/memoir-onboard/SKILL.md: Store: !`bash -c 'if [ -n "${MEMOIR_STORE:-}" ];
plugins/claude-code/skills/memoir-onboard/SKILL.md: `$MEMOIR` is a wrapper that resolves the right invocation for this machine — `memoir` on PATH if installed, otherwise `uvx --from memoir-ai==<pin> memoir`, otherwise `uv tool run --from memoir-ai==<pin> memoir` (pin lives in `scripts/resolve-memoir-cli.sh`).
plugins/claude-code/skills/memoir-onboard/SKILL.md: Wrap **every** memoir call — both branches A and B, both reads and writes — in a subshell that cd's into the store first, and use `"$MEMOIR"` (NOT bare `memoir`) so the call works on machines without a global memoir install:
plugins/claude-code/skills/memoir-onboard/SKILL.md: `test.strategy` — test layout, how to run tests, what coverage emphasizes.
plugins/claude-code/skills/memoir-onboard/SKILL.md: bash -c 'source "${CLAUDE_PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; concurrent_session_warning'
plugins/claude-code/skills/memoir-onboard/SKILL.md: If the command prints anything, stop and report: "Concurrent session detected — run /memoir:onboard after the other session finishes, or set a distinct MEMOIR_STORE."
plugins/claude-code/skills/memoir-onboard/SKILL.md: `git log --oneline -20` and `git log --stat -5` for recent change patterns (informs lessons / rules).
plugins/claude-code/skills/memoir-onboard/SKILL.md: Run `git log --stat <last_sha>..HEAD` to enumerate changed paths since the last onboarding pass.
plugins/claude-code/skills/memoir-onboard/SKILL.md: Run the confirmation check (`memoir status` → path == `$STORE_PATH`) before doing any writes.
plugins/claude-code/skills/memoir-onboard/SKILL.md: `python3 ${CLAUDE_PLUGIN_ROOT}/skills/memoir-onboard/extractors.py walk <root>` — JSON list of `{path, size, mtime_ns, kind}` plus `snapshot_hash`.
plugins/claude-code/skills/memoir-onboard/SKILL.md: `python3 ${CLAUDE_PLUGIN_ROOT}/skills/memoir-onboard/extractors.py extract <path>` — `key=value` blob for one file (with `kind=` first, `extractor.stdlib.fields=[…]` for provenance).
plugins/claude-code/skills/memoir-onboard/SKILL.md: `python3 ${CLAUDE_PLUGIN_ROOT}/skills/memoir-onboard/extractors.py snapshot-hash <root>` — just the hash.
plugins/claude-code/skills/memoir-onboard/SKILL.md: `python3 ${CLAUDE_PLUGIN_ROOT}/skills/memoir-onboard/extractors.py tree <root>` — pruned tree.
plugins/claude-code/skills/memoir-onboard/SKILL.md: `python3 ${CLAUDE_PLUGIN_ROOT}/skills/memoir-onboard/extractors.py shape <root>` — `{shape, overview}` JSON.
plugins/claude-code/skills/memoir-onboard/SKILL.md: bash -c 'source "${CLAUDE_PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; concurrent_session_warning'
plugins/claude-code/skills/memoir-onboard/SKILL.md: For each file in the walk result, run `extractors.py extract <path>` and capture the structured blob.
plugins/claude-code/skills/memoir-onboard/SKILL.md: python3 -c "import json,sys; print('\n'.join(e['path'] for e in json.loads(sys.argv[1])['files']))" "$WALK_JSON" \
plugins/claude-code/skills/memoir-onboard/SKILL.md: **added** (in walk, not in store) → run `extract <path>`, write `files.<san>.meta` and `files.<san>.summary`.
plugins/claude-code/skills/memoir-onboard/SKILL.md: **modified** (same path, different `(size, mtime_ns)`) → re-run `extract <path>`, write both keys.
plugins/claude-code/skills/memoir-onboard/SKILL.md: If a cold run fails partway through, the `_meta.*` keys act as commit markers.
plugins/claude-code/skills/memory-recall/SKILL.md: Run this preamble first and reuse `$STORE` and `$MEMOIR` for every memoir invocation below:
plugins/claude-code/skills/memory-recall/SKILL.md: `$MEMOIR` is a wrapper that resolves the right invocation for this machine — `memoir` on PATH if installed, otherwise `uvx --from memoir-ai==<pin> memoir`, otherwise `uv tool run --from memoir-ai==<pin> memoir` (pin lives in `scripts/resolve-memoir-cli.sh`).
plugins/claude-code/skills/memory-recall/SKILL.md: that way recall works on machines where memoir isn't `pip install`ed but `uv` is.
plugins/codex/skills/memoir-onboard/SKILL.md: bash -c 'source "${PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; in_git_repo && echo codebase:onboard || echo project:onboard'
plugins/codex/skills/memoir-onboard/SKILL.md: Store: !`bash -c 'if [ -n "${MEMOIR_STORE:-}" ];
plugins/codex/skills/memoir-onboard/SKILL.md: python3 - "$manifest" <<'PY'
plugins/codex/skills/memoir-onboard/SKILL.md: `$MEMOIR` is a wrapper that resolves the right invocation for this machine — `memoir` on PATH if installed, otherwise `uvx --from memoir-ai==<pin> memoir`, otherwise `uv tool run --from memoir-ai==<pin> memoir` (pin lives in `scripts/resolve-memoir-cli.sh`).
plugins/codex/skills/memoir-onboard/SKILL.md: Wrap **every** memoir call — both branches A and B, both reads and writes — in a subshell that cd's into the store first, and use `"$MEMOIR"` (NOT bare `memoir`) so the call works on machines without a global memoir install:
plugins/codex/skills/memoir-onboard/SKILL.md: `test.strategy` — test layout, how to run tests, what coverage emphasizes.
plugins/codex/skills/memoir-onboard/SKILL.md: bash -c 'source "${PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; concurrent_session_warning'
plugins/codex/skills/memoir-onboard/SKILL.md: If the command prints anything, stop and report: "Concurrent session detected - run memoir-onboard after the other session finishes, or set a distinct MEMOIR_STORE."
plugins/codex/skills/memoir-onboard/SKILL.md: `git log --oneline -20` and `git log --stat -5` for recent change patterns (informs lessons / rules).
plugins/codex/skills/memoir-onboard/SKILL.md: Run `git log --stat <last_sha>..HEAD` to enumerate changed paths since the last onboarding pass.
plugins/codex/skills/memoir-onboard/SKILL.md: Run the confirmation check (`memoir status` → path == `$STORE_PATH`) before doing any writes.
plugins/codex/skills/memoir-onboard/SKILL.md: `python3 ${PLUGIN_ROOT}/skills/memoir-onboard/extractors.py walk <root>` — JSON list of `{path, size, mtime_ns, kind}` plus `snapshot_hash`.
plugins/codex/skills/memoir-onboard/SKILL.md: `python3 ${PLUGIN_ROOT}/skills/memoir-onboard/extractors.py extract <path>` — `key=value` blob for one file (with `kind=` first, `extractor.stdlib.fields=[…]` for provenance).
plugins/codex/skills/memoir-onboard/SKILL.md: `python3 ${PLUGIN_ROOT}/skills/memoir-onboard/extractors.py snapshot-hash <root>` — just the hash.
plugins/codex/skills/memoir-onboard/SKILL.md: `python3 ${PLUGIN_ROOT}/skills/memoir-onboard/extractors.py tree <root>` — pruned tree.
plugins/codex/skills/memoir-onboard/SKILL.md: `python3 ${PLUGIN_ROOT}/skills/memoir-onboard/extractors.py shape <root>` — `{shape, overview}` JSON.
plugins/codex/skills/memoir-onboard/SKILL.md: bash -c 'source "${PLUGIN_ROOT}/hooks/common.sh" >/dev/null 2>&1; concurrent_session_warning'
plugins/codex/skills/memoir-onboard/SKILL.md: For each file in the walk result, run `extractors.py extract <path>` and capture the structured blob.
plugins/codex/skills/memoir-onboard/SKILL.md: python3 -c "import json,sys; print('\n'.join(e['path'] for e in json.loads(sys.argv[1])['files']))" "$WALK_JSON" \
plugins/codex/skills/memoir-onboard/SKILL.md: **added** (in walk, not in store) → run `extract <path>`, write `files.<san>.meta` and `files.<san>.summary`.
plugins/codex/skills/memoir-onboard/SKILL.md: **modified** (same path, different `(size, mtime_ns)`) → re-run `extract <path>`, write both keys.
plugins/codex/skills/memoir-onboard/SKILL.md: If a cold run fails partway through, the `_meta.*` keys act as commit markers.
plugins/codex/skills/memoir-onboard/SKILL.md: A subsequent forced memoir-onboard run will rewrite cleanly.
plugins/codex/skills/memoir-remember/SKILL.md: python3 - "$manifest" <<'PY'
plugins/codex/skills/memoir-remember/SKILL.md: bash "$PLUGIN_ROOT/scripts/ensure-store.sh" "$STORE" >/dev/null
plugins/codex/skills/memoir-status/SKILL.md: Run:
plugins/codex/skills/memoir-status/SKILL.md: python3 - "$manifest" <<'PY'
plugins/codex/skills/memoir-status/SKILL.md: bash "$PLUGIN_ROOT/scripts/status-cmd.sh"
plugins/codex/skills/memoir-ui/SKILL.md: Run:
plugins/codex/skills/memoir-ui/SKILL.md: python3 - "$manifest" <<'PY'
plugins/codex/skills/memoir-ui/SKILL.md: bash "$PLUGIN_ROOT/scripts/memoir-ui-ctl.sh" start "$STORE"
plugins/codex/skills/memory-recall/SKILL.md: Run this preamble first and reuse `$STORE` and `$MEMOIR` for every memoir invocation below:
plugins/codex/skills/memory-recall/SKILL.md: python3 - "$manifest" <<'PY'
plugins/codex/skills/memory-recall/SKILL.md: `$MEMOIR` is a wrapper that resolves the right invocation for this machine — `memoir` on PATH if installed, otherwise `uvx --from memoir-ai==<pin> memoir`, otherwise `uv tool run --from memoir-ai==<pin> memoir` (pin lives in `scripts/resolve-memoir-cli.sh`).
plugins/codex/skills/memory-recall/SKILL.md: that way recall works on machines where memoir isn't `pip install`ed but `uv` is.

Install scripts (2)

Makefile (make install): pip install -e .
README.md: curl -LsSf https://astral.sh/uv/install.sh | sh · uses the network

MCP servers (1)

README.md (memoir): uvx --from memoir-ai[mcp] memoir-mcp

Hooks (7)

plugins/claude-code/hooks/hooks.json (SessionStart): bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh
plugins/claude-code/hooks/hooks.json (UserPromptSubmit): bash ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh
plugins/claude-code/hooks/hooks.json (Stop): bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh
plugins/claude-code/hooks/hooks.json (SessionEnd): bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh
plugins/codex/hooks/hooks.json (SessionStart): bash "${PLUGIN_ROOT}/hooks/session-start.sh"
plugins/codex/hooks/hooks.json (UserPromptSubmit): bash "${PLUGIN_ROOT}/hooks/user-prompt-submit.sh"
plugins/codex/hooks/hooks.json (Stop): bash "${PLUGIN_ROOT}/hooks/stop.sh"

Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:2)
Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:23)
Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:30)
Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:40)
Medium risk: runs-install-script-remote-exec (README.md:86)
Medium risk: runs-mcp-server-unpinned-runner (README.md:153)
Low risk: network-instructions (Makefile:37)
Low risk: scripts-present (benchmarks/classifier.py)
Low risk: scripts-present (benchmarks/locomo/run.py)
Low risk: scripts-present (plugins/claude-code/hooks/session-end.sh)
Low risk: scripts-present (plugins/claude-code/hooks/session-start.sh)
Low risk: scripts-present (plugins/claude-code/hooks/stop.sh)
Low risk: scripts-present (plugins/claude-code/hooks/user-prompt-submit.sh)
Low risk: network-instructions (plugins/claude-code/skills/memory-recall/SKILL.md:20)
Low risk: scripts-present (plugins/codex/hooks/session-start.sh)
Low risk: scripts-present (plugins/codex/hooks/stop.sh)
Low risk: scripts-present (plugins/codex/hooks/user-prompt-submit.sh)
Low risk: network-instructions (plugins/codex/skills/memory-recall/SKILL.md:36)
Low risk: network-instructions (pyproject.toml:57)
Low risk: scripts-present (scripts/cc-smoke/run.sh)
Low risk: scripts-present (scripts/check_version_consistency.py)

Attribution and licence

First committed by

zhangfengcdt

Declared authors

zhangfengcdt (declared in pyproject.toml)

Publisher

Feng Zhang (Community)

Source

zhangfengcdt/memoir · commit 7fd1b3e

Licence

Apache License 2.0 (files served here)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-12

Contributors

zhangfengcdt, rapidSpace, disafronov, KevFoxCodeCraft, Ottohere-Mourn

AutoGineer is not affiliated with or endorsed by zhangfengcdt.

Install from source

489 of its files are not served here, so there is no ZIP. zhangfengcdt/memoir at 7fd1b3e

What it is

How it works

Requirements

Set it up

Usage

Documentation by zhangfengcdt

Memoir

Why agents need versioned memory

Key Features

Install from PyPI

Install a plugin for your agent

Quick look

Documentation

Contributing

License

Hermes Plugin

How it fits Hermes

Install

1. Install the memoir CLI

2. Install the plugin

3. Activate it

What ships

Tools

Lifecycle hooks

The /memoir command

Configuration

Model selection

Which provider key is used?

Session branching

Scoped memory

LLM backend

Routing through a proxy

Verify

Environment variables

Manifest

Limitations (v1)

See also

Advantages

Limitations

Security

This brain runs

Attribution and licence

Install from source

The `/memoir` command