Skip to content
Back to search

memoir

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhangfengcdt--memoir/badge.svg)](/listings/zhangfengcdt--memoir)

HTML

<a href="/listings/zhangfengcdt--memoir"><img src="/api/listings/zhangfengcdt--memoir/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install memoir-ai

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 37 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "memoir",
  3. "owner": {
  4. "name": "NextMind",
  5. "email": "f.feng.zhang@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "Git-versioned, taxonomy-structured memory plugins for Claude Code — branch, merge, time-travel your AI's memory.",
  9. "version": "0.6.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "memoir",
  14. "description": "Git-versioned, taxonomy-structured memory for Claude Code — recall by path, branch to isolate, time-travel to audit.",
  15. "version": "0.6.0",
  16. "source": "./plugins/claude-code",
  17. "category": "productivity",
  18. "author": {
  19. "name": "NextMind",
  20. "email": "f.feng.zhang@gmail.com"
  21. },
  22. "homepage": "https://github.com/zhangfengcdt/memoir",
  23. "repository": "https://github.com/zhangfengcdt/memoir",
  24. "license": "Apache-2.0",
  25. "keywords": [
  26. "memory",
  27. "git",
  28. "versioning",
  29. "taxonomy",
  30. "branching",
  31. "time-travel",
  32. "provenance",
  33. "prollytree"
  34. ]
  35. }
  36. ]
  37. }
README.md · README · 237 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Memoir
  2. <div align="center">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="https://www.memoir-ai.dev/images/memoir.png">
  5. <source media="(prefers-color-scheme: light)" srcset="https://www.memoir-ai.dev/images/memoir-light.png">
  6. <img src="https://www.memoir-ai.dev/images/memoir.png" alt="Memoir Logo" width="200" height="200">
  7. </picture>
  8. **Git for AI Memory**
  9. *Hierarchical Memory with Git-Like Version Control*
  10. </div>
  11. [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
  12. [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://github.com/zhangfengcdt/memoir/blob/main/LICENSE)
  13. [![Status](https://img.shields.io/badge/Status-Alpha-orange.svg)]()
  14. [![Website](https://img.shields.io/badge/Website-memoir--ai.dev-purple.svg)](https://www.memoir-ai.dev/)
  15. [![Docs](https://img.shields.io/badge/Docs-zhangfengcdt.github.io%2Fmemoir-blue.svg)](https://zhangfengcdt.github.io/memoir/)
  16. <p align="center">
  17. <img src="docs/_static/memoir-demo.gif" alt="Memoir demo" width="900">
  18. </p>
  19. 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.
  20. > **Project page:** **[memoir-ai.dev](https://www.memoir-ai.dev/)** — full overview, demos, and roadmap.
  21. ## Why agents need versioned memory
  22. > **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.
  23. **Your agent doesn't respect your git state.**
  24. Context contamination happens every time you `git checkout`. Without branch-aware memory, your agent tries to apply experimental refactor patterns to stable production hotfixes.
  25. **You're paying "token rent" on a flat file.**
  26. 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.
  27. **Your agent's memory is code without version control.**
  28. 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.
  29. ## Key Features
  30. - **Git-like Versioning** — Branch, commit, merge, and rollback memories with cryptographic integrity.
  31. - **Semantic Paths** — Replace UUID keys with meaningful paths like `profile.professional.skills.python`.
  32. - **O(log n) Lookups** — Fast hierarchical search instead of expensive vector operations.
  33. - **Memory Aggregation** — Automatic consolidation of related memories at semantic locations.
  34. - **Clean Architecture** — Proper separation of storage, classification, and search layers.
  35. - **Multiple Search Engines** — Choose between fast keyword-based or intelligent LLM-powered search.
  36. <!--
  37. ## Multi-agent sessions
  38. <p align="center">
  39. <img src="docs/_static/memoir-multi-agent.gif" alt="Multiple agent sessions working with Memoir" width="900">
  40. <br>
  41. <em>Multiple agent sessions working with Memoir.</em>
  42. </p>
  43. -->
  44. ## Install from PyPI
  45. ```bash
  46. pip install memoir-ai
  47. ```
  48. > The distribution name on PyPI is `memoir-ai`. The Python import is `import memoir` and the CLI is `memoir`.
  49. ## Install a plugin for your agent
  50. Memoir ships as a plugin for several coding and personal-assistant agents. Expand the one you use:
  51. <details>
  52. <summary><b>Claude Code</b></summary>
  53. Inside a Claude Code session, run:
  54. ```
  55. /plugin marketplace add zhangfengcdt/memoir
  56. /plugin install memoir@memoir
  57. ```
  58. **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:
  59. ```bash
  60. curl -LsSf https://astral.sh/uv/install.sh | sh
  61. ```
  62. 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](https://zhangfengcdt.github.io/memoir/claude_code/) for the full slash-command and hook reference.
  63. </details>
  64. <details>
  65. <summary><b>Codex</b></summary>
  66. 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`.
  67. You can also register the marketplace from the CLI:
  68. ```bash
  69. codex plugin marketplace add zhangfengcdt/memoir
  70. ```
  71. 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.
  72. **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`.
  73. 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](https://zhangfengcdt.github.io/memoir/codex/) for setup, limitations, and the real Codex smoke-test flow.
  74. </details>
  75. <details>
  76. <summary><b>Hermes</b></summary>
  77. Memoir is a memory provider for [Hermes](https://github.com/NousResearch/hermes-agent), the Nous Research personal-assistant agent. Install the plugin into your Hermes home and activate it:
  78. ```bash
  79. hermes plugins install zhangfengcdt/memoir/plugins/hermes # or: cp -r plugins/hermes ~/.hermes/plugins/memoir
  80. hermes memory setup # choose "memoir"
  81. ```
  82. 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](https://zhangfengcdt.github.io/memoir/hermes/) for install, configuration, model selection, and proxy routing.
  83. </details>
  84. <details>
  85. <summary><b>OpenClaw</b> (community)</summary>
  86. Memoir is a memory plugin for [OpenClaw](https://github.com/openclaw/openclaw), the personal-assistant gateway. It lives in its own repo, [`zhangfengcdt/openclaw-memoir`](https://github.com/zhangfengcdt/openclaw-memoir). Install it into the memory slot, allow conversation access, and restart the gateway:
  87. ```bash
  88. openclaw plugins install https://github.com/zhangfengcdt/openclaw-memoir # or: --link /path/to/openclaw-memoir
  89. openclaw config set plugins.entries.memory-memoir.hooks.allowConversationAccess true
  90. systemctl --user restart openclaw-gateway
  91. ```
  92. 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](https://zhangfengcdt.github.io/memoir/openclaw/) for configuration, scoping, model selection, and tool-profile notes.
  93. </details>
  94. <details>
  95. <summary><b>OpenCode</b> (community)</summary>
  96. **[opencode-memoir](https://github.com/disafronov/opencode-memoir)** is a community-maintained plugin that brings Memoir's long-term memory workflows to [OpenCode](https://github.com/sst/opencode) through its native plugin system. Follow the install instructions in that repository.
  97. </details>
  98. <details>
  99. <summary><b>Any MCP host</b> (Claude Desktop, Cursor, Cline, Windsurf, VS Code, Zed, …)</summary>
  100. 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:
  101. ```json
  102. {
  103. "mcpServers": {
  104. "memoir": {
  105. "command": "uvx",
  106. "args": ["--from", "memoir-ai[mcp]", "memoir-mcp"],
  107. "env": { "MEMOIR_STORE": "~/.memoir/mcp" }
  108. }
  109. }
  110. }
  111. ```
  112. 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](https://zhangfengcdt.github.io/memoir/mcp/) 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`.
  113. </details>
  114. ## Quick look
  115. Memoir's CLI defaults to Anthropic **`claude-haiku-4-5`** as of v0.1.6 — set your key first:
  116. ```bash
  117. export ANTHROPIC_API_KEY="sk-..."
  118. ```
  119. 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.
  120. Then create a store and round-trip a memory:
  121. ```bash
  122. # 1. Create a memoir store
  123. memoir new my-memoir-store
  124. cd my-memoir-store
  125. # 2. Store with an explicit path (offline, no LLM call)
  126. memoir remember "Sarah prefers tabs and 2-space indents" -p preferences.coding.style
  127. # 3. Store with auto-classification (LLM picks the path; needs API key)
  128. memoir remember "I work in Pacific time"
  129. # 4. Read back by path (offline)
  130. memoir get preferences.coding.style
  131. # 5. Semantic search (LLM-backed)
  132. memoir recall "what does Sarah prefer?"
  133. # 6. Watch a file by indexing it on the fly
  134. memoir watch add ~/papers/transformer.pdf -n research
  135. # 7. Search the indexed content
  136. memoir search "transformer attention mechanism"
  137. # 8. Open the visual explorer (auto-opens in your browser)
  138. memoir ui
  139. ```
  140. > Curious what the UI looks like before installing? Browse the [UI Gallery](https://www.memoir-ai.dev/demos/).
  141. 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`.
  142. See the full [Quickstart](https://zhangfengcdt.github.io/memoir/quickstart/) for the Python API and version-control workflow.
  143. ## Documentation
  144. Full docs live at **[zhangfengcdt.github.io/memoir](https://zhangfengcdt.github.io/memoir/)**:
  145. - [Quickstart](https://zhangfengcdt.github.io/memoir/quickstart/) — five-minute tour of the core loop.
  146. - [CLI Reference](https://zhangfengcdt.github.io/memoir/cli/) — every command, flag, and exit code.
  147. - [UI](https://zhangfengcdt.github.io/memoir/ui/) — the visual explorer (Tree / Graph / Timeline / Places + `/stats`).
  148. - [Claude Code](https://zhangfengcdt.github.io/memoir/claude_code/) — plugin install, slash commands, hooks, lifecycle.
  149. - [Codex](https://zhangfengcdt.github.io/memoir/codex/) — plugin install, hooks, skills, transcript parsing, smoke-test evidence.
  150. - [Architecture](https://zhangfengcdt.github.io/memoir/architecture/) — taxonomy, classifier, store, search.
  151. - [API Reference](https://zhangfengcdt.github.io/memoir/api/memoir/) — Python SDK.
  152. - [Examples](https://zhangfengcdt.github.io/memoir/examples/) — context branching, memory debugging, reproducible testing.
  153. ## Contributing
  154. 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:
  155. - Pick an issue from the [issue tracker](https://github.com/zhangfengcdt/memoir/issues) or open one describing a gap.
  156. - Fork the repo, branch off `main`, and run `make ci` before opening a PR (lint, tests, docs build must be green).
  157. - Bug reports with a minimal reproducer and benchmark / taxonomy proposals for coding-agent use cases are particularly appreciated.
  158. ## License
  159. Apache License 2.0 — see [LICENSE](https://github.com/zhangfengcdt/memoir/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.