{"id":"f731caea-e969-49f6-a217-bd523ca4a033","slug":"kmp","kind":"mcp","name":"kmp","summary":"Local-first agent memory that preserves what happened, when and why","owner":"underpass-ai","repoUrl":"https://github.com/underpass-ai/kmp","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-13T23:16:06.000Z","addedAt":"2026-10-14T06:08:08.521Z","logoUrl":"https://avatars.githubusercontent.com/u/225552176?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","developer-tools"],"tags":["claude-code","codex","context-engineering","llm","memory-system","agent-infrastructure","agent-memory","ai-agents"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T00:50:07.470Z","sample":false,"url":"https://conduits.dev/tools/kmp","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

KMP — Agent memory that remembers why

\n\n

\n \"KMP\"\n

\n\n

\n Local first. Evidence attached. Time included.\n

\n\n

\n \"CI\"\n \"Release\"\n \"crates.io\"\n \"License\"\n

\n\n\nKMP is local-first memory for coding agents. It runs beside Codex, Claude Code\nand Hermes Agent as one small binary with an embedded SQLite store, and it\nremembers what was decided, what the evidence was and when it happened. Never\nthe transcript. No account, no service, no API key: memory stays on your\nmachine.\n\nAsk your agent **\"Why did we choose SQLite?\"** and it answers from stored\nevidence, or says `UNKNOWN` instead of guessing. Ask **\"Show me the memory\nbehind this decision\"** and ChronoLoom, the viewer that ships inside the\nbinary, opens on that decision and lights up its proof path, with time as a\ndimension you can move through and a view the agent and you steer together.\nMemory tools retrieve and audit the evidence, view tools steer that shared\nChronoLoom view, and the running server's `tools/list` defines the current\nsurface.\n\n\n## The problem\n\nYour agent decides something today. Tomorrow a new session, or a different\nagent, rediscovers the same incident from scratch, or quietly contradicts the\ndecision because the reason for it was in a context window that is gone.\nSummaries lose the reason; transcripts bury it.\n\nKMP keeps the decision, the evidence it rested on and the moment it happened,\nas a typed, temporal memory the next session asks instead of re-deriving:\n\n- evidence decides what can be claimed;\n- relations carry the reason two memories belong together;\n- time travel is explicit, cursor-based and auditable;\n- old decisions are superseded, never quietly rewritten;\n- `UNKNOWN` is an honest answer when the evidence is not there.\n\n## See it in two minutes\n\nInstall KMP in your host (below), then in any project:\n\n```bash\nkmp-mcp demo\n```\n\nIt writes a worked example into that project's memory — a checkout service,\nan incident, the decision that replaced an earlier one and the measurement\nthat verified it — opens ChronoLoom on it and prints the questions to ask:\n\n| You say | You get |\n|:--|:--|\n| \"Why are retries to the payment provider capped at two?\" | The decision, with the incident and the ADR it cites. |\n| \"What did we believe about retries in August 2026?\" | The earlier decision, as it stood then, not the cap that replaced it. |\n| \"What changed about retries in September 2026?\" | The incident, the cap and the measurement, in order. |\n| \"Show me the memory behind the retry cap decision.\" | ChronoLoom opens on the decision and lights up its proof path. |\n\nName KMP and the about `example:kmp-demo` in the request. The example never\nenters your project's committed bundle. [More examples](examples/README.md),\nincluding [KMP's own memory](examples/kmp-project/README.md).\n\n## Install\n\nInstall the plugin, run setup, restart the host once. The guides reach a fresh\nstore on the first read; nothing else to run.\n\n### Claude Code\n\n```text\n/plugin marketplace add underpass-ai/kmp@marketplace\n/plugin install kmp@underpass\n/kmp:setup\n```\n\n### Codex CLI\n\n```bash\ncodex plugin marketplace add underpass-ai/kmp --ref marketplace\ncodex plugin add kmp@underpass\n```\n\nThen ask Codex to run `kmp-setup`.\n\n### Hermes Agent\n\nWith `kmp-mcp` installed, register it and install the skills through the\nnative lifecycle:\n\n```bash\nkmp-mcp setup --hermes\n```\n\n### Verify\n\n```bash\nkmp-mcp doctor\n```\n\nor run `/kmp:doctor`. The plugin owns the MCP registration, so do not add a\nsecond KMP server by hand. `cargo install kmp-mcp --locked` is the fallback\nfor a platform with no published engine; MCPB packages, release tarballs and\nthe Pi coding agent are covered in the\n[plugin installation guide](plugins/kmp/README.md). Store selection and\nrepair live in [Embedded KMP](docs/embedded/README.md).\n\n## Talk to it like a human\n\nYou normally ask for the outcome. The KMP skill chooses the memory moves.\n\n| You say | The agent does | You get |\n|:--|:--|:--|\n| \"Continue the KMP documentation work.\" | Wakes `project:kmp` before re-deriving it. | Current decisions, constraints and next actions. |\n| \"Why did we choose SQLite?\" | Asks memory and follows the stored evidence. | A grounded answer, or `UNKNOWN`. |\n| \"What does KMP remember from yesterday?\" | Resolves the interval and navigates every temporal page. | Ordered memory from that period. |\n| \"Why was the launch postponed in March?\" | Asks memory standing within March: only what fell inside competes, and the lifecycles are read as they stood then. | A grounded answer from that time, or `UNKNOWN` naming the nearest match outside the span. |\n| \"Remember that retries are capped at two because logs showed amplification.\" | Records the decision, its evidence and meaningful relations. | Durable state with an auditable why. |\n| \"Show the proof between this incident and that decision.\" | Traces the typed path and inspects its evidence. | The stored connection, rationale and sources. |\n| \"Undo that decision.\" | Writes a state that supersedes the old one. | Both decisions remain visible in time. |\n| \"Save the project memory.\" | Exports the maintained project bundle and shows its diff. | Reviewable `.kmp/memory.jsonl`. |\n\nKMP is memory, not surveillance. Store durable decisions and evidence, not\ntranscripts.\n\nIt also waits to be asked. A session that never mentions memory makes no KMP\ncall at all. Naming KMP, running a `/kmp:*` command, or opting in from your\nproject's `CLAUDE.md` or `AGENTS.md` is what opens a route. If you would\nrather it enter known work on its own:\n\n```bash\nkmp-mcp config memory-routing always\nkmp-mcp config memory-routing on-request # the default\n```\n\nAsk in any language. The stored evidence is never translated; the answer\ncomes back in yours. [How that works](docs/embedded/languages.md).\n\n## How it works — the 10-second version\n\n```mermaid\nflowchart LR\n U[You] --> H[Codex or Claude]\n H --> S[KMP skill]\n S -->|chooses a move| M[kmp-mcp]\n M --> K[embedded kernel]\n K --> D[(.kernel/\\nSQLite)]\n K --> V[local read-only viewer]\n```\n\nThe plugin installs the skills and declares one local MCP process. The skill\nturns intent into one or more typed tools. `kmp-mcp` validates the request,\nand the kernel reads or writes the local graph-temporal store. The agent, not\nKMP, turns returned evidence into conversational prose.\n\n| Layer | Owns | Does not own |\n|:--|:--|:--|\n| Plugin | Installation, host discovery, skills and the single MCP declaration. | Memory semantics or a second tool vocabulary. |\n| Skills | When to recover, ask, navigate, audit, write, diagnose, save or restore. | Persistence. |\n| kmp‑mcp | The schema-checked tool boundary over local stdio. | Choosing a workflow from user prose. |\n| Kernel | Validation, temporal storage, traversal, deterministic retrieval and proof. | Generating prose or inventing rationale. |\n\n[Explore ChronoLoom](crates/kmp-viewer/README.md) ·\n[Technical architecture](docs/architecture/README.md)\n\n## Local means local\n\n| Boundary | Default behavior |\n|:--|:--|\n| Memory | Stored on your machine, normally in the repository's `.kernel/`. |\n| MCP transport | Local stdio between the agent host and `kmp-mcp`. |\n| Viewer | Read-only loopback HTTP, normally rooted at `http://127.0.0.1:7317/`, behind a random per-session capability. |\n| External services | None required; optional TypeSafe Jev integrations send selected text to the configured service. |\n| Underpass | Receives no memory and operates no service in this path. |\n| Updates | Setup and updates contact GitHub Releases for checksummed packages; the Claude session hook can check releases daily. |\n| Local metadata | Agent identities and guide delivery records live outside memory retrieval; quality diagnostics use a separate local journal. |\n| Cloud agents | Evidence returned to a cloud agent follows that host's data policy. |\n\n`.kernel/` is machine state and is ignored by git. A project-scoped store also\nmaintains `.kmp/memory.jsonl`. Export and Git commit are local operations;\npushing, syncing or sharing the bundle makes its contents available elsewhere.\nReview its diff before sharing. Evidence read by the agent is also subject to\nthe host's data policy, independently of whether you share the bundle.\n\n## KMP's own memory\n\nThis repository eats its own cooking. [`.kmp/memory.jsonl`](.kmp/memory.jsonl)\nis the memory of why KMP is the way it is: the decisions behind it, each with\nthe document that states it, and the ones that superseded older ones. Restore\nit with `/kmp:restore` and ask \"why does a release advance the marketplace\nbranch last?\" [How it is written](examples/kmp-project/README.md).\n\n## Shared memory, when you actually need it\n\nSeveral machines can share one live KMP service through the Kubernetes\ntopology backed by Neo4j, Valkey and NATS JetStream. It is still free, open\nsource and self-operated. \"Enterprise\" describes the operational shape, not a\npaid tier or an Underpass-hosted product. It also means owning infrastructure,\nTLS, identity, authorization and observability. Keep it local until those\nresponsibilities buy you something. Then read\n[Enterprise KMP](docs/enterprise/README.md).\n\n## Project status\n\nKMP is pre-1.0: useful today, actively evolving, and explicit about sharp\nedges. Release automation builds `kmp-mcp` for Linux x86_64/arm64, macOS\narm64/x86_64 and Windows x86_64. The embedded path is the default; the remote\nAPI is versioned `v1beta1` and expects an operator.\n\nWe do not paste old benchmark numbers into the README. Reproducible, current\nevidence belongs in [Research](docs/research/README.md) before it becomes a\nclaim.\n\n## FAQ\n\n### Does KMP send my memory anywhere?\n\nNot in the default embedded setup. The process, store and viewer are local.\nThe agent host may be cloud-backed, so evidence sent to that agent follows the\nhost's policy.\n\n### Do I need Docker, Kubernetes or a database server?\n\nNo. The shipped embedded binary uses SQLite. Kubernetes is only for a shared\nservice.\n\n### Is there an LLM inside KMP?\n\nNo generative model is required for the default embedded path. KMP validates,\nstores and retrieves evidence; your agent writes the final answer and the\nEnglish search summary. Optional TypeSafe Jev features send selected text to\nan external model for judgments, and optional semantic retrieval uses a local\nencoder. These integrations require explicit configuration. See\n[retrieval defaults and opt-ins](docs/embedded/configuration.md).\n\n### Can Codex and Claude share the same memory?\n\nYes: both speak the same MCP contract, and SQLite supports multiple local\nhosts. Use the maintained project bundle to move state between machines, or\nthe enterprise topology for shared network access.\n\n### Is `UNKNOWN` an error?\n\nNo. It means the selected memory did not contain eligible evidence for the\nquestion. That is safer than a confident invention.\n\n### The tools disappeared. What now?\n\nRun the host's `kmp-doctor` workflow and follow the\n[missing-tools runbook](docs/runbooks/mcp-tools-missing.md). The usual suspects\nare a stale host session, duplicate MCP ownership, a missing binary or an\nunsupported store format.\n\n### Is enterprise KMP paid?\n\nNo. The code is Apache-2.0. You operate and pay for any infrastructure you\nchoose to run.\n\n
\nThe MCP moves\n\nOver memory, over the view a person is looking at, and one for persistent\nagent identity and progressive guidance. `tools/list` is the authority.\n\n| Tool | Purpose |\n|:--|:--|\n| `kmp_guide` | Open a capability map, preserve agent identity and expand one worked card. |\n| `kmp_wake` | Recover compact state before continuing work. |\n| `kmp_ask` | Retrieve evidence for a semantic question, or `UNKNOWN`. |\n| `kmp_relate` | Read what the memories of several abouts have to do with each other in a span, off the scopes and clocks they share. |\n| `kmp_time` | Move through memory on one clock: `rewind` and `forward` page backward and forward from a cursor or through an interval, `goto` jumps to a time, sequence or ref, `near` reads the neighbourhood around one. |\n| `kmp_trace` | Audit a path between two refs, or search for evidence from seed refs; inspect returned support and completeness. |\n| `kmp_inspect` | Inspect one object inside an explicit `about`, with its links and evidence. |\n| `kmp_write_memory` | Validate and record a decision, constraint or outcome. |\n| `kmp_ingest` | Ingest an exact canonical memory graph. |\n| `kmp_relabel` | Change the labels a memory stands in — add, take off, and why — without rewriting its text. |\n| `kmp_condense` | Write a compact reader card for one stored body, bound to the exact version it was read from. |\n| `kmp_summaries_audit` | Read where an about's memories stand with respect to their English search summaries: what is missing, what the lint refuses, and what stands and still retrieves little. |\n| `kmp_curate` | Review the relations of one or several abouts with TypeSafe Jev as an opt-in second reader: pairs nothing declares, with the type Jev would choose, and declared relations whose reason Jev doubts. The agent writes every relation. |\n| `kmp_view_open` | Open or rehydrate a ChronoLoom view over an about. |\n| `kmp_view_apply_intent` | Move that view by declaring meaning — focus, clock, zoom, filters, selection — under optimistic concurrency. |\n| `kmp_view_get_state` | Read the view's semantic state, never its pixels. |\n\nThe view tools never write memory: they carry a closed, semantic vocabulary\nwith no coordinates in it, and a person at the loom has right of way — an\nintent prepared against a stale revision conflicts rather than yanking the\nview away.\n\nHuman workflows such as `kmp-setup`, `kmp-doctor`, `kmp-info`, `kmp-catchup`,\n`kmp-save`, `kmp-restore` and `kmp-revert` compose the MCP surface. They are\nnot extra memory verbs. The machine-checked ownership map is\n[`plugins/kmp/capabilities.json`](plugins/kmp/capabilities.json).\n\n
\n\n## Docs and project links\n\n- [Documentation home](docs/index.md)\n- [Embedded KMP](docs/embedded/README.md)\n- [Retrieval defaults and store configuration](docs/embedded/configuration.md)\n- [Languages](docs/embedded/languages.md)\n- [Examples](examples/README.md)\n- [Enterprise KMP](docs/enterprise/README.md)\n- [Technical architecture](docs/architecture/README.md)\n- [Runbooks](docs/runbooks/README.md)\n- [Development](docs/development/README.md)\n- [Research](docs/research/README.md)\n- [Contributing](CONTRIBUTING.md)\n- [Security policy](SECURITY.md)\n- [Changelog](CHANGELOG.md)\n- [Issues](https://github.com/underpass-ai/kmp/issues) ·\n [Discussions](https://github.com/underpass-ai/kmp/discussions)\n\nThe implementation and executable checks win when prose disagrees: MCP\nschemas, plugin capabilities, CLI help, Helm values, API contracts and CI\nscripts are the source of truth.\n\n## License\n\n[Apache License 2.0](LICENSE). Free and open source.\n"}