{"id":45409107,"url":"https://github.com/mnemon-dev/mnemon","last_synced_at":"2026-05-31T12:00:40.536Z","repository":{"id":339820082,"uuid":"1162230313","full_name":"mnemon-dev/mnemon","owner":"mnemon-dev","description":"LLM-supervised persistent memory for AI agents — graph-based recall, cross-session knowledge, single binary. Works with Claude Code, OpenClaw, and any CLI agent.","archived":false,"fork":false,"pushed_at":"2026-05-24T00:25:13.000Z","size":6628,"stargazers_count":295,"open_issues_count":4,"forks_count":41,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-24T02:29:22.524Z","etag":null,"topics":["agent-framework","agent-memory","ai-agent","ai-tools","claude","claude-code","claude-memory","cli","context-window","golang","knowledge-graph","llm-agent","llm-memory","llm-supervised","mcp","memory","openclaw","persistent-memory","rag","sqlite"],"latest_commit_sha":null,"homepage":"https://github.com/mnemon-dev/mnemon#readme","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mnemon-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-20T02:26:17.000Z","updated_at":"2026-05-24T00:25:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mnemon-dev/mnemon","commit_stats":null,"previous_names":["mnemon-dev/mnemon"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mnemon-dev/mnemon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemon-dev%2Fmnemon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemon-dev%2Fmnemon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemon-dev%2Fmnemon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemon-dev%2Fmnemon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mnemon-dev","download_url":"https://codeload.github.com/mnemon-dev/mnemon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemon-dev%2Fmnemon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33730241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-memory","ai-agent","ai-tools","claude","claude-code","claude-memory","cli","context-window","golang","knowledge-graph","llm-agent","llm-memory","llm-supervised","mcp","memory","openclaw","persistent-memory","rag","sqlite"],"created_at":"2026-02-21T22:17:57.921Z","updated_at":"2026-05-31T12:00:40.523Z","avatar_url":"https://github.com/mnemon-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo/logo.svg\" width=\"160\" height=\"160\" alt=\"Mnemon Logo\" /\u003e\n\u003c/p\u003e\n\n# Mnemon\n\n**English** | [中文](docs/zh/README.md)\n\n**LLM-supervised persistent memory for AI agents.**\n\n[![Go 1.24+](https://img.shields.io/badge/Go-1.24%2B-00ADD8?logo=go\u0026logoColor=white)](https://go.dev/)\n[![CI](https://github.com/mnemon-dev/mnemon/actions/workflows/ci.yml/badge.svg)](https://github.com/mnemon-dev/mnemon/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mnemon-dev/mnemon)](https://goreportcard.com/report/github.com/mnemon-dev/mnemon)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)\n\n---\n\nLLM agents forget everything between sessions. Context compaction drops critical decisions, cross-session knowledge vanishes, and long conversations push early information out of the window.\n\nMnemon gives your agent persistent, cross-session memory — a four-graph knowledge store with intent-aware recall, importance decay, and automatic deduplication. Single binary, zero API keys, one setup command.\n\nFor the broader harness direction, Mnemon is an event-sourced lifecycle layer\nfor agents you already use. It does not replace Codex, Claude Code, OpenClaw,\nor future hosts; it adds governed memory, skill, eval, proposal, and audit\nlifecycles around them.\n\n\u003e **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.\n\n### Why Mnemon?\n\nMost 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.\n\n| Pattern | LLM Role | Representative |\n|---|---|---|\n| **LLM-Embedded** | Executor inside the pipeline | Mem0, Letta |\n| **File Injection** | None — reads file at session start | Claude Code Memory |\n| **MCP Server** | Tool provider via MCP protocol | claude-mem |\n| **LLM-Supervised** | External supervisor of a standalone binary | **Mnemon** |\n\nMnemon 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg 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\" /\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eThe LLM-Supervised pattern: hooks drive the lifecycle, the host LLM makes judgment calls, the binary handles deterministic computation.\u003c/sub\u003e\n\u003c/p\u003e\n\nMemory 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/10-knowledge-graph.jpg\" width=\"720\" alt=\"Knowledge Graph — 87 insights connected by temporal, entity, semantic, and causal edges\" /\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eA real knowledge graph built by Mnemon — 87 insights, 2150 edges across four graph types.\u003c/sub\u003e\n\u003c/p\u003e\n\nSee [Design \u0026 Architecture](docs/DESIGN.md) for details.\n\n## Quick Start\n\n### Install\n\n**Homebrew** (macOS / Linux):\n\n```bash\nbrew install mnemon-dev/tap/mnemon\n```\n\n**Go install**:\n\n```bash\ngo install github.com/mnemon-dev/mnemon@latest\n```\n\n**From source**:\n\n```bash\ngit clone https://github.com/mnemon-dev/mnemon.git \u0026\u0026 cd mnemon\nmake install\n```\n\n**Verify installation**:\n\n```bash\nmnemon --version\n```\n\n### Claude Code\n\n```bash\nmnemon setup\n```\n\n`mnemon setup` auto-detects Claude Code, then interactively deploys skill, hooks, and behavioral guide. Start a new session — memory just works.\n\n### [Codex](https://github.com/openai/codex)\n\n```bash\nmnemon setup --target codex --yes\n```\n\nOne command deploys the mnemon skill, prompt files, and Codex lifecycle hooks\n(`SessionStart`, `UserPromptSubmit`, `Stop`) in `.codex/hooks.json`.\n\n### [OpenClaw](https://github.com/openclaw/openclaw)\n\n```bash\nmnemon setup --target openclaw --yes\n```\n\nOne command deploys skill, hook, plugin, and behavioral guide to `~/.openclaw/`. Restart the OpenClaw gateway to activate.\n\n### [NanoClaw](https://github.com/qwibitai/nanoclaw)\n\nNanoClaw runs agents inside Linux containers. Use the `/add-mnemon` skill to integrate:\n\n1. Install mnemon on the host (see above)\n2. In your NanoClaw project, run `/add-mnemon` — Claude Code will modify the Dockerfile, add a container skill, and set up volume mounts\n3. Each WhatsApp group gets its own isolated memory store, with optional global shared memory (read-only)\n\nThe skill is available at `.claude/skills/add-mnemon/` in the NanoClaw repo.\n\n### [Nanobot](https://github.com/HKUDS/nanobot)\n\n```bash\nmnemon setup --target nanobot --global --yes\n```\n\nOne 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.\n\n### Uninstall\n\n```bash\nmnemon setup --eject\n```\n\n## How it works\n\nOnce set up, memory operates through a lightweight harness: `SKILL.md` teaches\ncommands, `GUIDELINE.md` teaches judgment, hooks remind the agent at lifecycle\nboundaries, and the `mnemon` binary executes deterministic memory operations.\nSupported setup commands automate this, but the harness is installable from\nmarkdown alone.\n\n```text\nSession starts\n    |\n    v\n  Prime   -\u003e make skill, guideline, and active store visible\n    |\n    v\nUser prompt arrives\n    |\n    v\n  Remind  -\u003e decide whether recall could change this task\n    |\n    v\nAgent works and calls Mnemon only when useful\n    |\n    v\n  Nudge   -\u003e decide whether durable writeback is justified\n    |\n    v\nBefore context compaction\n    |\n    v\n  Compact -\u003e preserve only critical continuity\n```\n\nThe four hook phases are reminders, not a hard workflow. **Prime** makes the\nskill, guideline, and active store visible. **Remind** prompts a recall\ndecision. **Nudge** prompts a writeback decision. **Compact** preserves only\ncritical continuity before context compression.\n\nYou don't run mnemon commands yourself. The agent does when the guideline says\nmemory is useful.\n\n## Features\n\n- **Zero user-side operation** — install once; supported runtimes can use hooks, minimal runtimes can use persistent rules\n- **LLM-supervised** — the host LLM decides what to remember, update, and forget; no embedded LLM, no API keys\n- **Multi-framework support** — Claude Code (hooks), OpenClaw (plugins), Nanobot (skills), and more\n- **Markdown-installable harness** — `SKILL.md`, `INSTALL.md`, `GUIDELINE.md`, and four lifecycle reminders\n- **Four-graph architecture** — temporal, entity, causal, and semantic edges, not just vector similarity\n- **Intent-native protocol** — three primitives (`remember`, `link`, `recall`) map to the LLM's cognitive vocabulary, not database syntax; structured JSON output with signal transparency\n- **Intent-aware recall** — graph traversal + optional vector search (RRF fusion), enabled by default for all queries\n- **Built-in deduplication** — `remember` auto-detects duplicates and conflicts; skips or auto-replaces\n- **Retention lifecycle** — importance decay, access-count boosting, and garbage collection\n- **Privacy-safe receipts** — export hashed operation receipts for memory-boundary audits without raw memory contents or queries\n- **Optional embeddings** — works fully without Ollama; add local [Ollama](https://ollama.ai) for enhanced vector+keyword hybrid search\n\n## Vision\n\nAll your local agentic AIs — across sessions and frameworks — sharing one pool of live memory.\n\n```\n  Claude Code ──┐\n                │\n  OpenClaw ─────┤\n                │\n  Nanobot ──────┤\n                │\n  NanoClaw ─────┤\n                ├──▶  ~/.mnemon  ◀── shared memory\n  OpenCode ─────┤\n                │\n  Gemini CLI ───┘\n```\n\nThe foundation is in place: a single `~/.mnemon` database that any agent can\nread and write. Claude Code setup automates hook installation; OpenClaw can use\nplugin hooks; Nanobot integrates via skill files; NanoClaw integrates via\ncontainer skills and volume mounts. The same harness can be installed in any\nLLM CLI that supports skills, rules, system prompts, or event hooks.\n\nThe 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.\n\n## FAQ\n\n**Do different sessions share memory?**\nYes. By default, all sessions use the same `default` store — a decision remembered in one session is available in every future session.\n\n**Can I isolate memory per project or agent?**\nYes. Use named stores to separate memory:\n\n```bash\nmnemon store create work        # create a new store\nmnemon store set work           # set as default\nMNEMON_STORE=work mnemon recall \"query\"  # or use env var per-process\n```\n\nDifferent agents/processes can use different stores via the `MNEMON_STORE` environment variable — no global state contention.\n\n**Local or global mode?**\n`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.\n\n**How do I customize the behavior?**\nEdit the generated guideline (`~/.mnemon/prompt/guide.md` in current setup\nflows) or use the installable [memory loop GUIDE](harness/loops/memory/GUIDE.md)\nas the source. The skill file should stay focused on command syntax.\n\n**What is sub-agent delegation?**\nSub-agent delegation is optional. When a runtime supports it, the main agent can\ndecide *what* to remember and ask a cheaper or isolated worker to execute\n`mnemon remember`. It is a useful execution strategy, not a required part of the\nMnemon architecture.\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---|---|---|\n| `MNEMON_DATA_DIR` | `~/.mnemon` | Base data directory |\n| `MNEMON_STORE` | *(active file or `default`)* | Named memory store for data isolation |\n\n**Ollama-specific** (only relevant if using embeddings):\n\n| Environment Variable | Default | Description |\n|---|---|---|\n| `MNEMON_EMBED_ENDPOINT` | `http://localhost:11434` | Ollama API endpoint |\n| `MNEMON_EMBED_MODEL` | `nomic-embed-text` | Embedding model name |\n\n## Development\n\n```bash\nmake build          # build binary\nmake install        # build + install to $GOBIN\nmake test           # run E2E test suite\nmnemon setup        # interactive setup\nmnemon setup --eject  # remove all integrations\nmake help           # show all targets\n```\n\n**Dependencies**: Go 1.24+, `modernc.org/sqlite`, `spf13/cobra`, `google/uuid`\n\nSee [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama embedding, and release setup.\n\n## Documentation\n\n- [Modular Self-Evolution Harness](docs/harness/README.md) — formal harness docs for modular agent, memory loop, and skill loop design\n- [Memory Loop Harness](harness/loops/memory/README.md) — installable memory loop assets\n- [Skill Loop Harness](harness/loops/skill/README.md) — installable skill loop assets\n- [Design \u0026 Architecture](docs/DESIGN.md) — current engine architecture, algorithms, integration design\n- [Usage \u0026 Reference](docs/USAGE.md) — CLI commands, embedding support, architecture overview\n- [Memory Import Guide](docs/IMPORT.md) — schema and LLM prompt for importing historical chats\n- [Architecture Diagrams](docs/diagrams/) — system architecture, pipelines, lifecycle management\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=mnemon-dev%2Fmnemon\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=mnemon-dev/mnemon\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=mnemon-dev/mnemon\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=mnemon-dev/mnemon\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## References\n\nMnemon 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.\n\n- **RLM** — Zhang, Kraska \u0026 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.\n- **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.\n- **Graph-LLM Structural Insight** — Joshi \u0026 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.\n\n## License\n\nCopyright 2026 Grivn and Mnemon contributors.\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnemon-dev%2Fmnemon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmnemon-dev%2Fmnemon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnemon-dev%2Fmnemon/lists"}