{"id":"a8debe06-18e5-4235-a35c-6f0ab407db83","slug":"long-mem","kind":"mcp","name":"long-mem","summary":"Keeps decisions alive across context compaction for Codex, Claude Code, Kimi Code and ZCode. Built on engram.","owner":"HOSRookie","repoUrl":"https://github.com/HOSRookie/long-mem","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-01T13:55:12.000Z","addedAt":"2026-10-22T03:44:06.920Z","logoUrl":"https://avatars.githubusercontent.com/u/235878021?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","developer-tools"],"tags":["agent-memory","ai-agents","claude-code","codex","context-management","long-term-memory"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T10:36:36.296Z","sample":false,"url":"https://conduits.dev/tools/long-mem","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# long_mem\n\n**Compaction-proof memory for AI coding agents.**\n\nEnglish | [简体中文](README.zh-CN.md)\n\n> The conversation is not a storage medium.\n> Anything that lives in the context window can be lost — so nothing lives there.\n> Memory lives outside. The window only holds pointers.\n\n![License](https://img.shields.io/badge/license-MIT-blue)\n![Agents](https://img.shields.io/badge/agents-Codex·ClaudeCode·ZCode·KimiCode-8A2BE2)\n![Field-tested](https://img.shields.io/badge/field--tested-504_compactions-green)\n![X](https://img.shields.io/badge/X-%40Rylie1933-black?logo=x)\n\n**long_mem** keeps AI coding agents continuous across context compaction, session restarts, and multi-day runs — without you repeating yourself.\n\n**Field-tested on one machine.** A Codex session ran **5 days 21 hours** through **40+ compactions** without losing context. That run predates long_mem as a plugin — it used the same mechanism by hand: an external memory store plus a custom compaction prompt.\n\nSince then, across the 22 sessions that actually used the memory tools, 504 compactions have been logged. In the one I examined most closely — 49 compactions over 60 hours — 46 were followed by an automatic `mem_context` pull from engram within minutes, before I typed anything.\n\n![49 compactions in 60 hours](docs/images/compaction-run.svg)\n\nThe numbers come from Codex's own session database, which records every `contextCompaction` event. Method, query and limits: [docs/DEMO.md](docs/DEMO.md).\n\nBuild logs and ongoing updates on X: **[@Rylie1933](https://x.com/Rylie1933)**.\n\n## Why\n\nEvery AI coding agent — Claude Code, Codex, ZCode, Kimi Code — shares the same flaw: **the conversation is its entire memory.** So:\n\n- The window fills up, the agent compacts, and everything you told it — constraints, decisions, reasons — is gone. It re-does work you already approved.\n- Next-day sessions start from zero. You re-brief the agent on what it did yesterday.\n- Some context plugins make it worse: they harvest your prompts, passively capture subagent output, and force-summarize your sessions into their store.\n\nThe usual fix is better summarization — which is just **a better lossy compression**.\n\nlong_mem is an inversion: **the conversation is not a storage medium.** Long-term memory lives outside — a governed [engram](https://github.com/Gentleman-Programming/engram) store plus the agent's own history. The window only holds pointers. Compaction destroys the conversation, and the conversation holds nothing of value — so compaction becomes a non-event.\n\n## How it works\n\n```text\n┌─ session start ───────▶ inject governance policy + pinned memory index\n│\n├─ during the session …  the agent writes durable judgments to engram\n│                         (through the governed gateway). The window\n│                         only holds pointers; bodies are read by ID.\n│\n├─ compaction ──────────▶ inject the \"continue directly\" rule; recover by\n│                         pointer. Never re-summarize.\n│\n└─ session end / next day rebuild from engram + history as needed —\n                          never from the conversation.\n```\n\n**Two storage layers:**\n\n| Layer | What it holds | Backed by |\n|---|---|---|\n| History recall | What happened | The agent's own history (e.g. Codex's SQLite history) |\n| Judgment distillation | Why it was decided | [engram](https://github.com/Gentleman-Programming/engram) |\n\n**The governance layer is the point.** Upstream memory plugins ship three automatic intake ports — prompt harvesting, passive subagent capture, forced session summaries. long_mem welds them shut and keeps exactly two: startup injection and post-compaction recovery. The thing being prevented is the agent polluting its own memory store.\n\n| Upstream hook | What it does | long_mem |\n|---|---|---|\n| UserPromptSubmit | Harvests every prompt | ❌ welded shut (may contain credentials) |\n| SubagentStop | Passively captures subagent output | ❌ welded shut |\n| SessionEnd | Force-generates a summary | ❌ welded shut |\n| SessionStart | Injects memory | ✅ kept |\n| Post-compaction | Recovers context | ✅ kept |\n\n## Quick start\n\nPrerequisite — install [engram](https://github.com/Gentleman-Programming/engram):\n\n```sh\nbrew install engram\n```\n\nThen pick your agent:\n\n| Agent | Install |\n|---|---|\n| **Codex** | See [PLUGIN.md](PLUGIN.md) (add the marketplace to config.toml) |\n| **Claude Code** | `claude plugin marketplace add HOSRookie/long-mem` → install long-mem |\n| **ZCode** | Plugin Marketplace → Add → paste this repo's URL |\n| **Kimi Code** | `/plugins install <repo>/adapters/kimi-code` — see the [adapter guide](adapters/kimi-code/README.md) |\n| **Gemini / Qwen / MiniMax / anything else** | Clone this repo → `scripts/inject-rules.sh` + wire up MCP per the [compatibility matrix](#compatibility) |\n\nAfter installing: open a new session. The agent sees the governance policy and your project's pinned memory index automatically. When the window compacts, it continues directly — you'll see what that means the first time it happens.\n\n## Compatibility\n\n| Agent | MCP | Resident rules | Lifecycle hooks | Manual recovery |\n|---|---|---|---|---|\n| Codex | ✓ | AGENTS.md | ✓ plugin hooks | compact-prompt |\n| Claude Code | ✓ | CLAUDE.md injection | ✓ SessionStart (incl. compact) | skill long-mem-recover |\n| ZCode | ✓ | rules template | ✓ SessionStart (compact matcher untested) | skill long-mem-recover |\n| Kimi Code | ✓ bundled | systemPrompt injection | sessionStart.skill (hooks upstream WIP) | skill |\n| Gemini / Qwen / others | ✓ | inject-rules.sh | — (rules + manual recovery) | skill |\n\nThe principle: **MCP is the greatest common denominator; hooks are a bonus.** Hookless agents still get ~90% of the value from resident rules + a manual recovery skill; hooked agents additionally get zero-touch injection.\n\n## Trust model\n\nMemory access is fail-closed:\n\n- The write path goes through a single governed gateway. Blocked tools: `mem_delete`, `mem_capture_passive`, `mem_save_prompt`, `mem_merge_projects`.\n- Upstream binary identity gate: sha256 drift is refused.\n- Session ↔ project double binding: DB owner check + independent local probe verification.\n- 16 KB cap on memory content — bodies live outside; memory stores evidence references.\n- The database is opened read-only; cloud sync defaults to off; credentials never enter memory.\n\nFull policy: [governance/POLICY.md](governance/POLICY.md).\n\n## Known limitations\n\n- engram's full-text search is weak on Chinese: recall works via the index + by-ID reads, not search.\n- Single trust domain: when multiple agents share one store, access control is by convention, not enforcement.\n- What's worth saving is judged by the agent: the mechanism guarantees saved memories aren't lost — it can't guarantee the judgment itself was right.\n\n## Feedback & contributing\n\n- Suggestions and feedback: open an [Issue](https://github.com/HOSRookie/long-mem/issues). Everything gets read.\n- Code contributions: open an Issue first to align direction. main is a protected branch; PRs are reviewed and merged by the maintainer — **keeping the memory store clean comes first**.\n\n## Docs\n\n[PLUGIN.md](PLUGIN.md) · [docs/USAGE.md](docs/USAGE.md) · [docs/DEMO.md](docs/DEMO.md) · [adapters/](adapters/) · [templates/](templates/) · [governance/POLICY.md](governance/POLICY.md)\n\n## Ecosystem\n\nlong_mem is the tip of a larger system:\n\n- **Polaris** (in progress) — a task-governance system for serious development work. long_mem is a minor component extracted from it. One thing I can share: I'm using a structured governance layer to contain LLM hallucinations — **not by eliminating them, but by leaving them nowhere to take effect**. The run log is public: [polars-log](https://github.com/nextAgentPolars/polars-log).\n- **Blue Space** (under wraps) — the name is romantic; the thing is still being validated. When it's ready to talk about, there'll be a link here.\n\nIf that direction interests you, a Star helps — for a long-cycle project, stars are one of the few fuels it runs on.\n\n## Support\n\nThis project burns real money in tokens. If long_mem genuinely helped you, a donation is appreciated — every one of them becomes the context window for the next experiment.\n\nInternational: [GitHub Sponsors](https://github.com/sponsors/HOSRookie)\n\nOtherwise:\n\n| Alipay | WeChat |\n|---|---|\n| <img src=\"docs/images/donate-alipay.jpg\" width=\"240\"/> | <img src=\"docs/images/donate-wechat.jpg\" width=\"240\"/> |\n\n## License\n\n[MIT](LICENSE)\n"}