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/openclaw.md

OpenClaw Plugin

Memoir ships a memory plugin for OpenClaw, the personal-assistant gateway. Activate it and OpenClaw 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 — and each conversation is isolated by default, so a side chat never pollutes your global profile.

The plugin lives in its own repository: zhangfengcdt/openclaw-memoir (OpenClaw's plugins install for git sources expects the plugin at the repo root). It is the OpenClaw counterpart of the in-repo Hermes plugin and shares its conventions.

How it fits OpenClaw

OpenClaw has a single-select memory slot (plugins.slots.memory, default memory-core). Installing this plugin claims that slot with memory-memoir. It holds no memoir code in-process — it shells out to the memoir CLI over a zero-dependency subprocess bridge, so the Prolly-tree self-resolves concurrent (fire-and-forget) writes with no locking.

It registers through OpenClaw's native seams: registerTool (model-facing tools), registerMemoryCapability (memory-guidance prompt section + disabling the MEMORY.md flush), api.on(...) hooks (capture + recall), registerCommand (the in-chat /memoir), and registerCli (openclaw memoir …).

Install

You need three things: the memoir CLI, the plugin in the memory slot, and a provider key + capture model in the plugin's config (OpenClaw keeps its own keys in a secret store and does not export them to subprocesses — see Model & API key).

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.

2. Install the plugin

# from the git repo root (no subdir form — the plugin is a root-level repo)
openclaw plugins install https://github.com/zhangfengcdt/openclaw-memoir

# …or link a local checkout while developing
openclaw plugins install --link /path/to/openclaw-memoir

Installing auto-switches the memory slot to memory-memoir (you'll see "Exclusive slot 'memory' switched from 'memory-core' to 'memory-memoir'"). To set it by hand:

openclaw config set plugins.slots.memory memory-memoir

3. Allow conversation access (for auto-capture)

Non-bundled plugins must opt in before their hooks can read conversation content:

openclaw config set plugins.entries.memory-memoir.hooks.allowConversationAccess true

Without this the tools and /memoir still work, but automatic capture and recall-injection are disabled.

4. Restart the gateway

systemctl --user restart openclaw-gateway      # or: openclaw gateway restart

The store is created automatically on first use under OpenClaw's state dir (see Store location).

What ships

Component	Count	Role
Tools (model-facing)	4	`memoir_recall`, `memoir_remember`, `memoir_forget`, `memoir_status`
Lifecycle hooks	4	Auto-capture, recall-context injection, store bootstrap
Memory capability	1	Tool-aware guidance section; disables the MEMORY.md flush
In-chat command	1	`/memoir …`
CLI subcommands	2	`openclaw memoir status`, `openclaw memoir ui`

Tools

The model decides when to call these (guided by the memory-guidance prompt section). They are exposed to the agent only when its tool profile allows memory tools — see Tool exposure.

Tool	Purpose
`memoir_recall`	Fetch stored facts about the user (preferences, people, commitments, decisions). LLM-free: `summarize --depth 3` → batched `get`; `metrics.*` excluded.
`memoir_remember`	Store an explicit durable fact. Routed through `memoir capture` so the taxonomy classifier picks a valid semantic path (never a guessed key); guarded against obvious secrets.
`memoir_forget`	Delete a fact by its exact taxonomy path (find it with `memoir_recall` first). Pre-checks existence so a wrong path can't create a no-op delete; prior versions stay in git history.
`memoir_status`	Store status: branch, memory count, scope.

Automatic behavior

These don't depend on the model invoking a tool, so the memory loop works even when the tools are filtered out of the agent's profile:

Hook	When	Purpose
`session_start`	new session	Ensure the store exists.
`before_prompt_build`	prompt assembly	Inject a `<memoir-memory>` block of relevant facts (passive recall).
`agent_end`	after every turn	Fire-and-forget `memoir capture --profile assistant` over the turn.
`before_compaction`	before summarization	Capture the message tail before it's discarded.

Capture runs in the background and never blocks the reply. The memory-capability promptBuilder adds a short guidance line that names memoir_recall / memoir_remember only when those tools are actually exposed — otherwise it points the user at /memoir.

The `/memoir` command

An in-chat command (not a tool, so it's never filtered by the tool profile):

/memoir status
/memoir recall [query]
/memoir remember <fact>
/memoir forget <key>
/memoir branch [name]      # versioning: diverge a timeline
/memoir checkout <name>
/memoir sync               # promote the current branch into main

CLI

openclaw memoir status     # branch / memory count / scope
openclaw memoir ui         # open the memoir web UI for the store

Configuration

Config lives under plugins.entries.memory-memoir.config.* (set with openclaw config set …). All keys optional.

Key	Default	Meaning
`store`	`<state-dir>/memoir/<agent>`	Store path override.
`capture`	`true`	Auto-capture facts from each turn.
`recall`	`true`	Inject the memory overview into the prompt.
`scope`	`profile`	Isolation: `profile` (per-agent — shared across all that agent's sessions, the default), `chat` (per-conversation), `off` (one shared store). Recall always also reads the shared `default` namespace. See Scoped memory.
`model`	—	Model for capture/remember extraction. Required in practice — see below.
`apiKey`	—	Provider API key for capture extraction. Required — see below.
`baseUrl`	—	Custom provider endpoint (proxy). Sets `MEMOIR_LLM_BASE_URL`.

openclaw config set plugins.entries.memory-memoir.config.model  anthropic/claude-haiku-4-5
openclaw config set plugins.entries.memory-memoir.config.apiKey  "$ANTHROPIC_API_KEY"

Model & API key

Capture/remember run an extraction step through memoir's litellm client. Two things matter:

1. The key must be in the plugin config. OpenClaw authenticates providers through its own secret store and does not export ANTHROPIC_API_KEY (etc.) into subprocesses. So memoir — a separate process — can't see it unless you provide it via apiKey. The plugin routes it to the right env var based on the model:

Model	Provider → key
`claude-` / `anthropic/`	Anthropic → `ANTHROPIC_API_KEY`
`gpt-` / `openai/`	OpenAI → `OPENAI_API_KEY`
`gemini*`	Gemini → `GEMINI_API_KEY`

2. The model must support temperature=0. memoir's extraction uses temperature=0 for determinism. Reasoning models that force temperature=1 (e.g. claude-opus-4-8) will fail capture with an UnsupportedParamsError. Use a standard model — anthropic/claude-haiku-4-5 is ideal for background extraction (fast and cheap), and decouples capture cost from whatever model your chats run on.

Recall is LLM-free, so it works with no key. Only capture and explicit memoir_remember need one.

Tool exposure

OpenClaw filters each agent's toolset by its tools profile (tools.profile). The coding profile is an allowlist that strips memory tools (it would strip memory-core's tools too) — so on a coding-configured gateway the memoir_* tools won't appear in the model's tool list, even though they registered fine. To expose them, use a profile that includes memory tools:

openclaw config set tools.profile full     # or any profile that includes memory tools
systemctl --user restart openclaw-gateway

Either way, auto-capture, passive recall injection, and the /memoir command don't depend on the tool profile — they keep working under coding. The tools only add on-demand recall/remember/forget for the model.

Storage model

OpenClaw maps onto memoir on two axes: an agent selects the store (a whole Prolly-tree), and the scope setting selects the namespace (a partition inside that store).

Store ← agent

<state-dir>/memoir/<agentId>

<state-dir> = OPENCLAW_STATE_DIR, else ~/.openclaw — so it follows --profile / --dev (e.g. ~/.openclaw-work/memoir/…). See Store location.
<agentId> = the conversation's agent (recovered from the agent:<id>:<session> session key), default main. Each agent gets a separate tree.
Override the whole path with the store config or MEMOIR_STORE.

Namespace ← scope (details in Scoped memory)

`scope`	Namespace	One namespace per…
`profile` (default)	`profile-<agentId>`	agent (all its sessions)
`chat`	`chat-<sessionKey>`	conversation / launch
`off`	`default`	the whole store

Two namespaces always exist alongside the scope one: default (shared facts — recall reads scope ⊕ default) and taxonomy (memoir's built-in path taxonomy, not user data — it's the "8 memories" you see on a fresh store).

The axes compose: agent → tree, scope → partition. Under the default scope=profile the store and namespace both key on the agent (1:1); the namespace layer only fans out under scope=chat.

~/.openclaw/memoir/main            # agent "main"        (store)
  ├── profile-main                 # scope=profile       (your facts)
  ├── default                      # shared across scopes
  └── taxonomy                     # built-in
~/.openclaw/memoir/research        # a second agent  →   separate store

Scoped memory

By default memory is shared across all of an agent's sessions, so the assistant remembers you across launches. OpenClaw mints a new session id per TUI launch, so chat scope would isolate every launch (no cross-session continuity) — opt into it only when you genuinely want per-conversation separation. Set scope to change the granularity:

`scope`	Each scope is…	Namespace
`profile` (default)	an agent (all its sessions)	`profile-<agentId>`
`chat`	a single conversation/launch	`chat-<sessionKey>`
`off`	one shared store	`default`

Captures and memoir_remember write to the scope's namespace; memoir_recall reads the scope namespace ⊕ default, so global facts are visible everywhere but a scoped fact never leaks into another scope (default-deny, not an injection-time filter). Scoping uses memoir namespaces (parallel partitions) — distinct from branches.

What lands in `default`?

Every write (auto-capture, memoir_remember, /memoir remember) targets the scope namespace, which is default only when scope=off:

`scope`	Writes land in	Does `default` fill up?
`off`	`default`	✅ everything
`profile` (default)	`profile-<agentId>`	❌ nothing automatic
`chat`	`chat-<sessionKey>`	❌ nothing automatic

So under the default profile scope, nothing the plugin writes goes to default — it stays empty. default is the cross-scope shared/read layer (recall always merges it in); it only fills when you run scope=off, or write to it deliberately:

memoir -s ~/.openclaw/memoir/<agent> remember "<fact>" -p <path> -n default

(So if you want a fact visible in every scope while running profile/chat, put it in default by hand.)

Store location

The store is anchored under OpenClaw's state dir, mirroring OpenClaw's own resolution: OPENCLAW_STATE_DIR if set, else <HOME>/.openclaw. So it follows --profile / --dev isolation — --profile work puts the store under ~/.openclaw-work/memoir/<agent>. Default:

~/.openclaw/memoir/<agent>          # e.g. ~/.openclaw/memoir/main

Override with the store config or MEMOIR_STORE.

Versioning

OpenClaw has no conversation-fork event, so (unlike Hermes) there's no automatic fork→branch mapping. Per-chat scoping covers the isolation case; for divergent, mergeable timelines use the manual branch commands:

/memoir branch <name>      # diverge off main
/memoir checkout <name>
/memoir sync               # additively merge the current branch back into main

Verify

openclaw memoir status                                   # branch / memory count / scope
memoir -s ~/.openclaw/memoir/main summarize --depth 3    # captured paths
memoir -s ~/.openclaw/memoir/main blame <path>           # provenance

End-to-end: in a chat, state a durable fact ("remember my daughter Mia has piano on Tuesdays"). Capture runs in the background (a few seconds); summarize then shows it under a sensible path. A debug trace of capture attempts is written to <store>/.git/memoir-openclaw-events.log.

Parity with the Hermes plugin

This plugin mirrors the Hermes provider: the same tools, capture/recall flow, secret guard, model routing, per-chat scoping, /memoir command, and CLI. The differences come from OpenClaw's API:

No session-fork event → manual /memoir branch | checkout | sync instead of automatic fork→branch.
Provider key in config (apiKey) → OpenClaw doesn't export keys to subprocesses, where Hermes inherits them from its process environment.
Tool-profile filtering can hide the tools (the coding profile); the passive path always works.

Limitations (v1)

Local store only. Multi-device sync (the merge-based wedge) is future work.
Capture needs a config key + a temperature=0-capable model (see Model & API key).
One memory provider at a time. Claiming the slot displaces memory-core.

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

OpenClaw Plugin

How it fits OpenClaw

Install

1. Install the memoir CLI

2. Install the plugin

3. Allow conversation access (for auto-capture)

4. Restart the gateway

What ships

Tools

Automatic behavior

The /memoir command

CLI

Configuration

Model & API key

Tool exposure

Storage model

Scoped memory

What lands in default?

Store location

Versioning

Verify

Parity with the Hermes plugin

Limitations (v1)

See also

Advantages

Limitations

Security

This brain runs

Attribution and licence

Install from source

The `/memoir` command

What lands in `default`?