Skip to content
Back to search

mnemon

LLM-supervised persistent memory for AI agents — graph-based recall, cross-session knowledge, single binary. Works with DeepSeek Harness, Claude Code, OpenClaw, and any agent runtime.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mnemon-dev/mnemon with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mnemon-dev/mnemon'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mnemon-dev--mnemon/badge.svg)](/listings/mnemon-dev--mnemon)

HTML

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

Install

i

Install instructions from the README

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

Install

**npm** (recommended; macOS / Linux / Windows, Node.js 22+):

npm install --global @mnemon-dev/mnemon

Upgrade the npm-managed CLI at any time:

mnemon update

The npm package installs the matching native Go executable for the host OS and CPU. Mnemon's engine remains a single native binary; Node.js is used only by the npm launcher and package manager.

**Alternative installers**:

brew install --cask mnemon-dev/tap/mnemon
go install github.com/mnemon-dev/mnemon@latest

Homebrew, `go install`, source builds, and other Node package managers must continue to use their original installation method. To migrate one of these installations, run the npm install command once and ensure the npm global bin directory precedes the old executable on `PATH`; subsequent `mnemon update` calls are npm-managed.

Windows supports the core Memory commands. Agency remains unavailable on Windows until its local authority boundary has native Windows security.

**From source** (macOS / Linux):

git clone https://github.com/mnemon-dev/mnemon.git && cd mnemon
make install

**Verify installation**:

mnemon --version
mnemon agency --version

Agency (Preview · Pi-first)

mnemon agency setup --runtime pi --project-root .

Set up each project once, then use Pi normally. Agency is available on macOS and Linux and remains independent from Memory: `mnemon setup --target pi --yes` enables Memory, while the command above enables Agency. See the [Agency guide](docs/AGENCY.md) for its operating model, Preview compatibility boundary, and optional peers.

[Claude Code](https://github.com/anthropics/claude-code)

mnemon setup

`mnemon setup` auto-detects Claude Code, then interactively deploys skill, hooks, and behavioral guide. Start a new session — memory just works.

[Codex](https://github.com/openai/codex)

mnemon setup --target codex --yes

One command deploys the mnemon skill, prompt files, and Codex lifecycle hooks (`SessionStart`, `UserPromptSubmit`, `Stop`) in `.codex/hooks.json`.

[Cursor](https://cursor.com/)

mnemon setup --target cursor --yes

One command deploys the mnemon skill, prompt files, and Cursor lifecycle hooks to `.cursor/`. The integration primes new agent sessions with Mnemon guidance and memory status, then nudges for durable-memory writeback after responses.

[ZCode](https://zcode.z.ai/)

mnemon setup --target zcode --global --yes

ZCode installs the Mnemon skill under `~/.zcode/skills/` and registers user-level lifecycle hooks in `~/.zcode/cli/config.json`. The hooks prime new sessions, add recall guidance before model calls, and prompt for durable-memory writeback at stop. Without `--global`, setup installs only the project skill; ZCode currently ignores project-level hook configuration.

The Stop hook honors `stop_hook_active` to avoid repeated reminders. Its completion fallback recognizes `mnemon`, `durable memory`, `持久记忆`, and `写入记忆`; the reminder asks for a `[mnemon]` marker so evaluations in any language can finish without another reminder. Windows hooks decode stdin as UTF-8, and the PowerShell script containing Chinese tokens includes a UTF-8 BOM for Windows PowerShell 5.1. Re-run setup and start a new ZCode session to update previously installed hooks.

[MiniMax Code](https://github.com/MiniMax-AI/minimax-code)

mnemon setup --target minimax-code --yes

One command deploys the Mnemon skill to `.minimax/skills/mnemon/SKILL.md`. Add `--global` to use `~/.minimax/skills/mnemon/SKILL.md` across projects. Current MiniMax Code releases discover both roots natively. The integration is intentionally skill-only: in MiniMax Code 3.0.65, the local Agent V2 path does not dispatch the user-prompt lifecycle hook required for dependable automatic recall.

[TRAE](https://www.trae.ai/) (TRAE Work)

mnemon setup --target trae --yes

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.

README.md · README · 646 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/logo/logo.svg" width="160" height="160" alt="Mnemon Logo" />
  3. </p>
  4. <h1 align="center">Mnemon</h1>
  5. <p align="center"><strong>English</strong> · <a href="docs/zh/README.md">中文</a></p>
  6. <p align="center">
  7. <a href="https://www.npmjs.com/package/@mnemon-dev/mnemon"><img alt="npm version" src="https://img.shields.io/npm/v/@mnemon-dev/mnemon?label=npm" /></a>
  8. <a href="https://www.npmjs.com/package/@mnemon-dev/mnemon"><img alt="npm downloads" src="https://img.shields.io/npm/dt/@mnemon-dev/mnemon?label=npm%20downloads" /></a>
  9. <a href="https://github.com/mnemon-dev/mnemon/releases/latest"><img alt="GitHub release" src="https://img.shields.io/github/v/release/mnemon-dev/mnemon" /></a>
  10. <a href="https://github.com/mnemon-dev/mnemon/releases"><img alt="GitHub release downloads" src="https://img.shields.io/github/downloads/mnemon-dev/mnemon/total?label=GitHub%20downloads" /></a>
  11. <a href="https://github.com/mnemon-dev/mnemon/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/mnemon-dev/mnemon?label=stars" /></a>
  12. <a href="https://go.dev/"><img alt="Go 1.24+" src="https://img.shields.io/badge/Go-1.24%2B-00ADD8?logo=go&amp;logoColor=white" /></a>
  13. <a href="https://github.com/mnemon-dev/mnemon/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mnemon-dev/mnemon/actions/workflows/ci.yml/badge.svg" /></a>
  14. <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg" /></a>
  15. </p>
  16. <p align="center"><strong>LLM-supervised persistent memory for AI agents.</strong></p>
  17. ---
  18. LLM agents forget everything between sessions. Context compaction drops critical decisions, cross-session knowledge vanishes, and long conversations push early information out of the window.
  19. Mnemon gives your agent persistent, cross-session memory — a four-graph knowledge store with intent-aware recall, importance decay, and automatic deduplication. The `mnemon` memory path remains one local binary with zero API keys and one setup command.
  20. Mnemon ships one executable with two separate surfaces. Memory stays at the
  21. `mnemon` root; [Agency Preview](docs/AGENCY.md) lives at `mnemon agency ...` and adds
  22. durable, project-local responsibility and effect admission to an existing Pi
  23. agent. Agency does not replace Memory or the Agent Runtime.
  24. > **Claude Max / Pro subscriber?** Mnemon works entirely through your existing subscription — no separate API key required. Your LLM subscription *is* the intelligence layer. Two commands and you're done.
  25. ### Why Mnemon?
  26. Most memory tools embed their own LLM inside the pipeline. Mnemon takes a different approach: **your host LLM is the supervisor.** The binary handles deterministic computation (storage, graph indexing, search, decay); the LLM makes judgment calls (what to remember, how to link, when to forget). No middleman, no extra inference cost.
  27. | Pattern | LLM Role | Representative |
  28. |---|---|---|
  29. | **LLM-Embedded** | Executor inside the pipeline | Mem0, Letta |
  30. | **File Injection** | None — reads file at session start | Claude Code Memory |
  31. | **MCP Server** | Tool provider via MCP protocol | claude-mem |
  32. | **LLM-Supervised** | External supervisor of a standalone binary | **Mnemon** |
  33. Mnemon also addresses a gap in the protocol stack. MCP standardizes how LLMs discover and invoke tools. ODBC/JDBC standardizes how applications access databases. But how LLMs interact with databases using memory semantics — this layer has no protocol. Mnemon's three primitives — `remember`, `link`, `recall` — form an intent-native protocol: command names map to the LLM's cognitive vocabulary (`remember` not INSERT, `recall` not SELECT), and output is structured JSON with signal transparency rather than raw database rows.
  34. <p align="center">
  35. <img src="docs/diagrams/llm-supervised-concept.jpg" width="720" alt="LLM-Supervised Architecture — three patterns compared, with Mnemon hooks, protocol boundary, and deterministic memory engine" />
  36. <br />
  37. <sub>The LLM-Supervised pattern: hooks drive the lifecycle, the host LLM makes judgment calls, the binary handles deterministic computation.</sub>
  38. </p>
  39. Memory has a **compound interest effect** — the longer it accumulates, the greater its value. LLM engines iterate constantly, skill files cost nearly nothing to write, but memory is a private asset that grows with the user. It is the only component in the agent ecosystem worth deep investment.
  40. <p align="center">
  41. <img src="docs/diagrams/10-knowledge-graph.jpg" width="720" alt="Knowledge Graph — 87 insights connected by temporal, entity, semantic, and causal edges" />
  42. <br />
  43. <sub>A real knowledge graph built by Mnemon — 87 insights, 2150 edges across four graph types.</sub>
  44. </p>
  45. See [Design & Architecture](docs/DESIGN.md) for details.
  46. ## Web knowledge workspace
  47. Browse the knowledge accumulated by your agents in a standalone local website:
  48. ```sh
  49. mnemon web
  50. # Open http://127.0.0.1:8484
  51. Optional: [shared Memory service and paper strategy](docs/memory-service.md), with [composable records indexes](docs/records-indexes.md).
  52. ```
  53. Explore a searchable memory library, readable memory pages, a relationship graph,
  54. entities, and recorded activity. Select a memory store in the sidebar while agents
  55. continue writing through the existing CLI. Browsing preserves memory content,
  56. access counts, retention weights, and the CLI's active-store selection.
  57. Use `mnemon web --store <name> --port 8485` to choose the initial store and port.
  58. The interface ships inside the Mnemon executable and uses bundled local assets.
  59. See the [web workspace guide](docs/development/web-workspace.md) for usage,
  60. live-read behavior, and frontend development.
  61. ## Quick Start
  62. ### Install
  63. **npm** (recommended; macOS / Linux / Windows, Node.js 22+):
  64. ```bash
  65. npm install --global @mnemon-dev/mnemon
  66. ```
  67. Upgrade the npm-managed CLI at any time:
  68. ```bash
  69. mnemon update
  70. ```
  71. The npm package installs the matching native Go executable for the host OS and
  72. CPU. Mnemon's engine remains a single native binary; Node.js is used only by
  73. the npm launcher and package manager.
  74. **Alternative installers**:
  75. ```bash
  76. brew install --cask mnemon-dev/tap/mnemon
  77. go install github.com/mnemon-dev/mnemon@latest
  78. ```
  79. Homebrew, `go install`, source builds, and other Node package managers must
  80. continue to use their original installation method. To migrate one of these
  81. installations, run the npm install command once and ensure the npm global bin
  82. directory precedes the old executable on `PATH`; subsequent `mnemon update`
  83. calls are npm-managed.
  84. Windows supports the core Memory commands. Agency remains unavailable on
  85. Windows until its local authority boundary has native Windows security.
  86. **From source** (macOS / Linux):
  87. ```bash
  88. git clone https://github.com/mnemon-dev/mnemon.git && cd mnemon
  89. make install
  90. ```
  91. **Verify installation**:
  92. ```bash
  93. mnemon --version
  94. mnemon agency --version
  95. ```
  96. ### Agency (Preview · Pi-first)
  97. ```bash
  98. mnemon agency setup --runtime pi --project-root .
  99. ```
  100. Set up each project once, then use Pi normally. Agency is available on macOS
  101. and Linux and remains independent from Memory: `mnemon setup --target pi --yes`
  102. enables Memory, while the command above enables Agency. See the
  103. [Agency guide](docs/AGENCY.md) for its operating model, Preview compatibility
  104. boundary, and optional peers.
  105. ### [Claude Code](https://github.com/anthropics/claude-code)
  106. ```bash
  107. mnemon setup
  108. ```
  109. `mnemon setup` auto-detects Claude Code, then interactively deploys skill, hooks, and behavioral guide. Start a new session — memory just works.
  110. ### [Codex](https://github.com/openai/codex)
  111. ```bash
  112. mnemon setup --target codex --yes
  113. ```
  114. One command deploys the mnemon skill, prompt files, and Codex lifecycle hooks
  115. (`SessionStart`, `UserPromptSubmit`, `Stop`) in `.codex/hooks.json`.
  116. ### [Cursor](https://cursor.com/)
  117. ```bash
  118. mnemon setup --target cursor --yes
  119. ```
  120. One command deploys the mnemon skill, prompt files, and Cursor lifecycle hooks
  121. to `.cursor/`. The integration primes new agent sessions with Mnemon guidance
  122. and memory status, then nudges for durable-memory writeback after responses.
  123. ### [ZCode](https://zcode.z.ai/)
  124. ```bash
  125. mnemon setup --target zcode --global --yes
  126. ```
  127. ZCode installs the Mnemon skill under `~/.zcode/skills/` and registers
  128. user-level lifecycle hooks in `~/.zcode/cli/config.json`. The hooks prime new
  129. sessions, add recall guidance before model calls, and prompt for durable-memory
  130. writeback at stop. Without `--global`, setup installs only the project skill;
  131. ZCode currently ignores project-level hook configuration.
  132. The Stop hook honors `stop_hook_active` to avoid repeated reminders. Its
  133. completion fallback recognizes `mnemon`, `durable memory`, `持久记忆`, and
  134. `写入记忆`; the reminder asks for a `[mnemon]` marker so evaluations in any
  135. language can finish without another reminder. Windows hooks decode stdin as
  136. UTF-8, and the PowerShell script containing Chinese tokens includes a UTF-8 BOM
  137. for Windows PowerShell 5.1. Re-run setup and start a new ZCode session to update
  138. previously installed hooks.
  139. ### [MiniMax Code](https://github.com/MiniMax-AI/minimax-code)
  140. ```bash
  141. mnemon setup --target minimax-code --yes
  142. ```
  143. One command deploys the Mnemon skill to
  144. `.minimax/skills/mnemon/SKILL.md`. Add `--global` to use
  145. `~/.minimax/skills/mnemon/SKILL.md` across projects. Current MiniMax Code
  146. releases discover both roots natively. The integration is intentionally
  147. skill-only: in MiniMax Code 3.0.65, the local Agent V2 path does not dispatch
  148. the user-prompt lifecycle hook required for dependable automatic recall.
  149. ### [TRAE](https://www.trae.ai/) (TRAE Work)
  150. ```bash
  151. mnemon setup --target trae --yes
  152. ```
  153. One command deploys the mnemon skill, prompt files, and TRAE native hooks for
  154. both TRAE IDE and TRAE Work to `.trae/`. The integration uses `SessionStart`,
  155. `UserPromptSubmit`, and `Stop` hooks in `.trae/hooks.json`.
  156. ### [Qoder](https://qoder.com/) (QoderWork)
  157. ```bash
  158. mnemon setup --target qoder --yes
  159. mnemon setup --target qoderwork --yes
  160. ```
  161. Qoder deploys the mnemon skill, prompt files, and native hooks to `.qoder/`
  162. or `~/.qoder/`. QoderWork uses its native user config at `~/.qoderwork/`.
  163. Both integrations register `SessionStart`, `UserPromptSubmit`, and `Stop`
  164. hooks in `settings.json`.
  165. ### [CodeBuddy](https://www.codebuddy.cn/)
  166. ```bash
  167. mnemon setup --target codebuddy --yes
  168. ```
  169. CodeBuddy deploys the mnemon skill, prompt files, and native hooks to
  170. `.codebuddy/` or `~/.codebuddy/`. The integration registers `SessionStart`,
  171. `UserPromptSubmit`, and `Stop` hooks in `settings.json`.
  172. ### [WorkBuddy](https://www.codebuddy.cn/work/)
  173. ```bash
  174. mnemon setup --target workbuddy --yes
  175. ```
  176. WorkBuddy deploys the mnemon skill, prompt files, and native hooks to
  177. `.workbuddy/` or `~/.workbuddy/`. The integration registers `SessionStart`,
  178. `UserPromptSubmit`, and `Stop` hooks in `settings.json`.
  179. ### [Kimi Code](https://github.com/MoonshotAI/kimi-code)
  180. ```bash
  181. mnemon setup --target kimi --yes
  182. ```
  183. Kimi Code deploys the mnemon skill, prompt files, and native lifecycle hooks to
  184. `~/.kimi-code/` or `$KIMI_CODE_HOME/`. The integration registers
  185. `SessionStart`, `UserPromptSubmit`, and `Stop` hooks in `config.toml`.
  186. ### [OpenCode](https://opencode.ai/)
  187. ```bash
  188. mnemon setup --target opencode --yes
  189. ```
  190. OpenCode deploys the mnemon skill to `.opencode/skills/`, registers the
  191. generated guide through `opencode.json` instructions, and installs a native
  192. plugin in `.opencode/plugins/`. The plugin injects recall context before chat
  193. requests and adds Mnemon guidance to session compaction.
  194. The plugin supports OpenCode v2 and v1.18.29 or newer. After updating Mnemon,
  195. rerun setup with the same scope (add `--global` for a user-wide installation),
  196. then restart OpenCode to replace an older plugin. See the
  197. [OpenCode setup notes](docs/USAGE.md#opencode) for runtime requirements.
  198. ### [OpenClaw](https://github.com/openclaw/openclaw)
  199. ```bash
  200. mnemon setup --target openclaw --yes
  201. ```
  202. One command deploys skill, hook, plugin, and behavioral guide to `~/.openclaw/`. Restart the OpenClaw gateway to activate.
  203. ### [Pi](https://pi.dev)
  204. ```bash
  205. mnemon setup --target pi --yes
  206. ```
  207. One command deploys the mnemon skill, prompt files, and a Pi TypeScript extension
  208. to `.pi/`. The extension maps Mnemon's lifecycle reminders onto Pi events
  209. (`resources_discover`, `before_agent_start`,
  210. `session_before_compact`). Start a new Pi session or run `/reload` to activate.
  211. ### [Hermes Agent](https://github.com/NousResearch/hermes-agent)
  212. ```bash
  213. mnemon setup --target hermes --yes
  214. ```
  215. One command deploys the mnemon skill, prompt files, and Hermes shell hooks to
  216. `~/.hermes/`. The integration uses Hermes' native lifecycle hooks:
  217. `on_session_start`, `pre_llm_call`, `post_llm_call`, and optional
  218. `on_session_finalize`. Hermes may prompt once to approve the installed shell
  219. hooks.
  220. ### [Alma](https://alma.now)
  221. ```bash
  222. mnemon setup --target alma --yes
  223. ```
  224. One command deploys the mnemon skill, a `mem` shim, and a single `app.ready`
  225. hook to `~/.config/alma/`. Alma's hook stdout is not injected into the model
  226. context — only `decision`, `reason`, and `updatedInput` from the last JSON line
  227. are consumed — so the integration is deliberately shaped differently from the
  228. lifecycle-hook targets: the hook does one job (refresh a generated block inside
  229. `MEMORY.md`, which Alma already injects into its system prompt every request),
  230. and recall is left to the model through the skill. The block is delimited by
  231. `<!-- mnemon:begin -->` / `<!-- mnemon:end -->` and everything outside those
  232. markers is preserved byte for byte, because Alma's own prompt tells the model to
  233. write to the same file.
  234. Alma has no project-local hook configuration, so this target is user-global
  235. only.
  236. ### [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
  237. DeepSeek Harness (DSH) integrates through the [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) plugin, which layers DSH's runtime memory, managed project documents, and Mnemon's long-term memory spaces into one supervised three-tier memory system.
  238. With `mnemon` installed on the host (see [Install](#install)), add the plugin and restart your DSH Web profile:
  239. ```bash
  240. dsh plugin --profile web add dsh-mnemon
  241. dsh --profile web
  242. ```
  243. The Mnemon repository is also a direct GitHub installation source. Unreleased
  244. plugin builds can still be installed from the dedicated repository, and local
  245. development checkouts use an absolute path:
  246. ```bash
  247. dsh plugin --profile web add github:mnemon-dev/mnemon
  248. dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
  249. dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
  250. ```
  251. New installations from the Mnemon repository resolve the `latest` npm release
  252. of `dsh-mnemon`, so publishing a new plugin release does not require a matching
  253. change in this repository. Existing installations remain on their resolved
  254. version until the plugin is reinstalled or updated.
  255. Then open DSH's Settings → Plugin Config → Mnemon to pick a storage scope, and use the Memory System tab in a session to create or activate memory spaces. Recall reads only from active memory spaces; durable writes go through supervised sub-agents.
  256. ### [NanoClaw](https://github.com/qwibitai/nanoclaw)
  257. NanoClaw runs agents inside Linux containers. Use the `/add-mnemon` skill to integrate:
  258. 1. Install mnemon on the host (see above)
  259. 2. In your NanoClaw project, run `/add-mnemon` — Claude Code will modify the Dockerfile, add a container skill, and set up volume mounts
  260. 3. Each WhatsApp group gets its own isolated memory store, with optional global shared memory (read-only)
  261. The skill is available at `.claude/skills/add-mnemon/` in the NanoClaw repo.
  262. ### [Nanobot](https://github.com/HKUDS/nanobot)
  263. ```bash
  264. mnemon setup --target nanobot --global --yes
  265. ```
  266. One command writes a skill file to `~/.nanobot/workspace/skills/mnemon/SKILL.md`. Memory is shared across all Nanobot sessions and projects. Use `--global` (recommended) because Nanobot discovers skills from the global workspace directory.
  267. ### Uninstall
  268. ```bash
  269. mnemon setup --eject
  270. ```
  271. ## How it works
  272. Once set up, Memory operates through lightweight runtime projections: a
  273. runtime-specific `SKILL.md` teaches commands, a shared `guide.md` (by default
  274. `~/.mnemon/prompt/guide.md`) carries judgment guidance, and native hooks or
  275. extensions surface reminders at supported lifecycle boundaries. The `mnemon`
  276. binary executes deterministic memory operations, while `mnemon setup` installs
  277. the closest native mapping for each supported runtime.
  278. ```text
  279. Session starts
  280. |
  281. v
  282. Prime -> make skill, guide, and active store visible
  283. |
  284. v
  285. User prompt arrives
  286. |
  287. v
  288. Remind -> decide whether recall could change this task
  289. |
  290. v
  291. Agent works and calls Mnemon only when useful
  292. |
  293. v
  294. Nudge -> decide whether durable writeback is justified
  295. |
  296. v
  297. Before context compaction
  298. |
  299. v
  300. Compact -> preserve only critical continuity
  301. ```
  302. The four hook phases are reminders, not a hard workflow. **Prime** makes the
  303. skill, guide, and active store visible. **Remind** prompts a recall
  304. decision. **Nudge** prompts a writeback decision. **Compact** preserves only
  305. critical continuity before context compression.
  306. You don't run mnemon commands yourself. The agent does when the guide says
  307. memory is useful.
  308. ## Features
  309. - **Zero user-side operation** — install once; supported runtimes can use hooks, minimal runtimes can use persistent rules
  310. - **LLM-supervised** — the host LLM decides what to remember, update, and forget; no embedded LLM, no API keys
  311. - **Multi-framework support** — Claude Code, Codex, Cursor, ZCode, TRAE/TRAE Work, Qoder/QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent (hooks/plugins), OpenClaw (plugins), Pi (extensions), Alma (skill + `app.ready` hook), MiniMax Code and Nanobot (skills), DeepSeek Harness (via the dsh-mnemon plugin), and more
  312. - **Runtime-native integration** — runtime-specific `SKILL.md`, shared `guide.md`, and supported hooks or extensions
  313. - **Four-graph architecture** — temporal, entity, causal, and semantic edges, not just vector similarity
  314. - **Intent-native protocol** — three primitives (`remember`, `link`, `recall`) map to the LLM's cognitive vocabulary, not database syntax; structured JSON output with signal transparency
  315. - **Intent-aware recall** — graph traversal + optional vector search (RRF fusion), enabled by default for all queries
  316. - **Built-in deduplication** — `remember` and `import` skip exact content repeats and preserve distinct facts; similarity suggestions guide review
  317. - **Retention lifecycle** — importance decay, access-count boosting, and garbage collection
  318. - **Privacy-safe receipts** — export hashed operation receipts for memory-boundary audits without raw memory contents or queries
  319. - **Optional embeddings** — works fully without an embedding provider; add local [Ollama](https://ollama.ai) or an OpenAI-compatible server for enhanced vector+keyword hybrid search
  320. ## Vision
  321. All your local agentic AIs — across sessions and frameworks — sharing one pool of live memory.
  322. ```
  323. Claude Code ───────┐
  324. │
  325. Codex ─────────────┤
  326. │
  327. Cursor ────────────┤
  328. │
  329. ZCode ─────────────┤
  330. │
  331. MiniMax Code ──────┤
  332. │
  333. TRAE ──────────────┤
  334. │
  335. TRAE Work ─────────┤
  336. │
  337. Qoder ─────────────┤
  338. │
  339. QoderWork ─────────┤
  340. │
  341. CodeBuddy ─────────┤
  342. │
  343. WorkBuddy ─────────┤
  344. │
  345. Kimi Code ─────────┤
  346. │
  347. Hermes Agent ──────┤
  348. │
  349. DeepSeek Harness ──┤
  350. │
  351. OpenClaw ──────────┤
  352. │
  353. Pi ────────────────┤
  354. │
  355. Nanobot ───────────┤
  356. │
  357. NanoClaw ──────────┤
  358. ├──▶ ~/.mnemon ◀── shared memory
  359. OpenCode ──────────┤
  360. │
  361. Gemini CLI ────────┘
  362. ```
  363. The foundation is in place: a single `~/.mnemon` database that any agent can
  364. read and write. Claude Code, Codex, Cursor, ZCode, TRAE/TRAE Work, Qoder/QoderWork,
  365. CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent setup automate hook/plugin installation;
  366. OpenClaw can use plugin hooks; Pi integrates via native skills and TypeScript
  367. lifecycle extensions; MiniMax Code and Nanobot integrate via skill files; NanoClaw integrates
  368. via container skills and volume mounts. The same integration bundle can be installed in any
  369. LLM CLI that supports skills, rules, system prompts, or event hooks.
  370. The longer-term direction is a **memory gateway**: protocol decoupled from storage engine. The current SQLite backend is the first adapter; the protocol surface (`remember / link / recall`) can sit on top of PostgreSQL, Neo4j, or any graph database. Agent-side optimization (when to recall, what to remember) and storage-side optimization (indexing, graph algorithms) evolve independently. See [Future Direction](docs/design/08-decisions.md#82-future-direction) for details.
  371. ## FAQ
  372. **Do different sessions share memory?**
  373. Yes. By default, all sessions use the same `default` store — a decision remembered in one session is available in every future session.
  374. **Can I isolate memory per project or agent?**
  375. Yes. Use named stores to separate memory:
  376. ```bash
  377. mnemon store create work # create a new store
  378. mnemon store set work # set as default
  379. MNEMON_STORE=work mnemon recall "query" # or use env var per-process
  380. ```
  381. Different agents/processes can use different stores via the `MNEMON_STORE` environment variable — no global state contention.
  382. **Local or global mode?**
  383. `mnemon setup` defaults to **local** (project-scoped `.claude/`), recommended for most users. **Global** (`mnemon setup --global`, installed to `~/.claude/`) activates mnemon across all projects — convenient if you want other frameworks (e.g., OpenClaw) to share memory by forwarding requests through Claude Code CLI, but may add maintenance overhead.
  384. **How do I customize the behavior?**
  385. Edit the generated guideline (`~/.mnemon/prompt/guide.md` in current setup
  386. flows). Skill files should stay focused on command syntax.
  387. **What is sub-agent delegation?**
  388. Sub-agent delegation is optional. When a runtime supports it, the main agent can
  389. decide *what* to remember and ask a cheaper or isolated worker to execute
  390. `mnemon remember`. It is a useful execution strategy, not a required part of the
  391. Mnemon architecture.
  392. ## Configuration
  393. | Environment Variable | Default | Description |
  394. |---|---|---|
  395. | `MNEMON_DATA_DIR` | `~/.mnemon` | Base data directory |
  396. | `MNEMON_STORE` | *(active file or `default`)* | Named memory store for data isolation |
  397. **Retention**:
  398. | Environment Variable | Default | Description |
  399. |---|---|---|
  400. | `MNEMON_MAX_INSIGHTS` | `1000` | Active-insight ceiling; `0` disables automatic pruning |
  401. | `MNEMON_AUTO_PRUNE_MIN_AGE` | `24h` | Grace period before an insight can be auto-pruned; accepts `24h`, `7d`, or `0` |
  402. Each automatic deletion is soft, appears in the oplog as a `prune` operation, and is
  403. reported by ID in the triggering command's `auto_pruned_ids` field.
  404. **Embedding** (only relevant if using embeddings):
  405. | Environment Variable | Default | Description |
  406. |---|---|---|
  407. | `MNEMON_EMBED_ENDPOINT` | `http://localhost:11434` | Embedding API endpoint |
  408. | `MNEMON_EMBED_MODEL` | `nomic-embed-text` | Embedding model name |
  409. | `MNEMON_EMBED_PROTOCOL` | *(auto-detect)* | `ollama` or `openai`; auto-detected from an endpoint ending in `/v1` |
  410. | `MNEMON_EMBED_API_KEY` | *(none)* | Bearer token for OpenAI-compatible servers (oMLX, vLLM, etc.) |
  411. | `MNEMON_EMBED_KEEP_ALIVE` | `30m` | How long Ollama keeps the embedding model loaded after each request (ignored for OpenAI-compatible servers) |
  412. | `MNEMON_EMBED_DIMENSIONS` | *(native)* | Optional Matryoshka dimension truncation |
  413. The embedding client speaks the Ollama API by default and the
  414. OpenAI-compatible embeddings API when the endpoint ends in `/v1` (or when
  415. `MNEMON_EMBED_PROTOCOL=openai` is set). OpenAI-compatible servers are
  416. normally probed via their `models` route; servers that do not serve that
  417. route (e.g. [Voyage AI](https://docs.voyageai.com)) are detected via an
  418. embeddings round-trip instead. For example, a local server such as
  419. [oMLX](https://omlx.dev) can be configured with:
  420. ```bash
  421. export MNEMON_EMBED_ENDPOINT=http://127.0.0.1:18000/v1
  422. export MNEMON_EMBED_MODEL=bge-m3-mlx-8bit
  423. export MNEMON_EMBED_API_KEY=sk-... # omit for keyless local servers
  424. mnemon embed --status
  425. ```
  426. A hosted provider such as Voyage AI needs only the endpoint, model, and key:
  427. ```bash
  428. export MNEMON_EMBED_ENDPOINT=https://api.voyageai.com/v1
  429. export MNEMON_EMBED_MODEL=voyage-3.5
  430. export MNEMON_EMBED_API_KEY=pa-...
  431. mnemon embed --status
  432. ```
  433. ## Development
  434. ```bash
  435. make build # build the single mnemon executable
  436. make install # build + install to $GOBIN
  437. make test # run deterministic CI tests
  438. make test-integration # opt-in CLI E2E and Agency boundary tests
  439. mnemon setup # interactive setup
  440. mnemon setup --eject # remove all integrations
  441. make help # show all targets
  442. ```
  443. **Dependencies**: Go 1.24+, `modernc.org/sqlite`, `spf13/cobra`, `google/uuid`
  444. See [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama embedding, and release setup.
  445. ## Optional Memory Agent and AML backend
  446. The [Memory Agent](docs/memory-service.md) exposes the v0.3.4 AML evaluation
  447. engine through explicit `mnemon memory-agent ...` commands. It stores original
  448. records, builds a source-linked memory index, and returns evidence for an agent
  449. to answer from. Reads and consolidation require separately configured models.
  450. Existing `remember`, `recall`, `search`, `setup`, hooks, and the Web library keep
  451. using native Memory and `mnemon.db`. No automatic migration, model activation,
  452. or switch of the default engine is performed. Build this branch to use the new
  453. commands; opening a PR does not update the published CLI or npm release.
  454. `mnemon memory-agent aml-serve` adds the AML Add/Search API with per-user stores,
  455. bounded background consolidation, authentication and budgets. Its operational
  456. surface includes readiness, metrics, redacted logs, traces and read-only
  457. inspection. See the [AML adapter runbook](docs/aml-adapter.md),
  458. [Admin API](docs/admin-api.md), and [Inspect API](docs/inspect-api.md).
  459. The separate hosted console, frontend UI/UX, design prototypes and private
  460. evaluation data are outside this source snapshot.
  461. ## Documentation
  462. - [Agency Preview](docs/AGENCY.md) — maturity boundary, Pi setup, operating model, completion semantics, and optional peers
  463. - [Go Engineering Standard](docs/development/go-engineering-standard.md) — maintainability, concurrency, persistence, testing, and review thresholds
  464. - [Design & Architecture](docs/DESIGN.md) — current engine architecture, algorithms, integration design
  465. - [Memory Usage & Reference](docs/USAGE.md) — root Memory commands, import, receipts, and embedding support
  466. - [Optional Memory Agent](docs/memory-service.md) — v0.3.4 baseline, explicit configuration, records and evidence Views
  467. - [Memory Import Guide](docs/IMPORT.md) — schema and LLM prompt for importing historical chats
  468. - [Architecture Diagrams](docs/diagrams/) — system architecture, pipelines, lifecycle management
  469. - [Memory Agent (experimental)](experimental/memory-agent/) — research preview of Mnemon as a memory agent on DSH, with Jev as its System 1 decision model; paper, code and run records
  470. - [AML adapter runbook](docs/aml-adapter.md) — the Agent Memory Leaderboard service as memory cloud instances: install, open, operate, alerts, data deletion
  471. - [Admin API](docs/admin-api.md) — an instance's admin listener: token, private bind, metrics, readiness, status and store overview
  472. ## Star History
  473. <a href="https://www.star-history.com/?repos=mnemon-dev%2Fmnemon&type=timeline&legend=bottom-right">
  474. <picture>
  475. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=mnemon-dev/mnemon&type=timeline&theme=dark&legend=bottom-right" />
  476. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=mnemon-dev/mnemon&type=timeline&legend=bottom-right" />
  477. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=mnemon-dev/mnemon&type=timeline&legend=bottom-right" />
  478. </picture>
  479. </a>
  480. ## References
  481. Mnemon combines the paradigm of one paper with the methodology of another, grounded in the structural insight that graph memory is isomorphic to LLM attention. See [Theoretical Foundations](docs/DESIGN.md#25-theoretical-foundations) for details.
  482. - **RLM** — Zhang, Kraska & Khattab. [Recursive Language Models](https://arxiv.org/abs/2512.24601). 2025. Establishes the paradigm: LLMs are more effective as orchestrators of external environments than as direct data processors.
  483. - **MAGMA** — Zou et al. [A Multi-Graph based Agentic Memory Architecture](https://arxiv.org/abs/2601.03236). 2025. Provides the methodology: four-graph model (temporal, entity, causal, semantic) with intent-adaptive retrieval.
  484. - **Graph-LLM Structural Insight** — Joshi & Zhu. [Building Powerful GNNs from Transformers](https://arxiv.org/abs/2506.22084). 2025; and the Graph-based Agent Memory survey (Chang Yang et al., 2026). Confirms that LLM attention is computationally equivalent to GNN operations — graph memory is a structural match, not an engineering convenience.
  485. ## License
  486. Copyright 2026 Grivn and Mnemon contributors.
  487. [Apache-2.0](LICENSE)
  488. The bracketed copyright example near the end of `LICENSE` is part of Apache
  489. 2.0's standard application appendix; this section carries the project's actual
  490. copyright notice.

Ratings and comments

Sign in to rate this skill.

Sign in

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