{ "markdown": "

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 gives Codex and Claude Code local-first memory that preserves what\nhappened, when and why. It stores decisions and evidence, not transcripts,\non embedded SQLite, and exposes them through eleven memory tools plus three\nsemantic view tools over a shared ChronoLoom view.\n\nAsk **“Show me the memory behind this decision.”** The agent retrieves the\nevidence, opens ChronoLoom at the relevant moment and lights up the proof path.\nYou can click, filter, pan, undo or take control of the same view at any time.\n\n\n## Why KMP?\n\nAgents are good at doing the work in front of them. Tomorrow is harder. A\ndecision survives, its rationale disappears, and somebody gets to rediscover\nthe same incident from scratch.\n\nKMP gives the agent a typed, temporal memory instead of a bag of text:\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\nThe normal path runs entirely on your machine. No KMP account. No hosted\nmemory server. No Underpass cloud.\n\n## Install. Run setup. Done.\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` and restart Codex once.\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\nRestart Claude Code once. Verify either host with its `kmp-doctor` workflow,\nor from a terminal:\n\n```bash\nkmp-mcp info\nkmp-mcp doctor\n```\n\nThat is the happy path. The plugin owns the MCP registration, so do not add a\nsecond KMP server by hand. Store selection and repair live in\n[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 happened 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.” | Publishes 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 — the agent works from what is in front of it. Naming KMP, running\na `/kmp:*` command, or opting in from your project's `CLAUDE.md` or `AGENTS.md`\nis what opens a route. If you would rather 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\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 of fourteen typed tools. `kmp-mcp` validates the\nrequest, and the kernel reads or writes the local graph-temporal store. The\nagent—not KMP—turns returned evidence into conversational prose.\n\n## ChronoLoom — memory you can see\n\nAsk your agent: **“Show me the memory behind this decision.”** ChronoLoom\nopens on the evidence and lights up its proof path.\n\n**You control the same view:** your agent can steer it; you can click, filter,\npan or undo at any time.\n\n[Explore ChronoLoom](crates/kmp-viewer/README.md) ·\n[Technical architecture](docs/architecture/README.md)\n\n### Who owns what?\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 fourteen-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\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
\nThe fourteen MCP moves\n\nEleven over memory, three over the view a person is looking at.\n\n| Tool | Purpose |\n|:--|:--|\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_goto` | Jump to memory at a time, sequence or ref. |\n| `kmp_near` | Inspect the temporal neighborhood around a cursor. |\n| `kmp_rewind` | Move backward through memory. |\n| `kmp_forward` | Move forward through memory. |\n| `kmp_trace` | Prove the path between two refs owned by an explicit `about`. |\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_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\n`tools/list` from the running server is authoritative for schemas, outputs and\nthe relation vocabulary.\n\n
\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. |\n| Underpass | Receives no memory and operates no service in this path. |\n| Updates | Setup may contact GitHub Releases for checksummed packages. |\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`; it leaves your machine only if you deliberately\ncommit or copy it.\n\n## Language without flattening the evidence\n\nKMP never translates or rewrites stored evidence. A semantic question is\nasked in the kernel's search language: the agent renders it in plain English,\nkeeps every number, identifier and acronym the user wrote, and passes the\nuser's own words as `asked_as`. The kernel searches the rendering as given,\nechoes `asked_as` on the answer, and warns when the rendering dropped an\nidentifier or leans to another language. It accepts a question in any\nlanguage, so if the English one returns `UNKNOWN` the agent re-asks once in\nthe user's own words and stops. With a lexical-bridge table beside the store\n(`/lexical-bridge.kmpb`, built by `scripts/lexical-bridge/`),\n`kmp_ask` also reaches memory written in another language on its own: a\ncitation that crossed a language names the word pairs that carried it\n(`valvula≈valve 0.51`) and answers at medium confidence at most. Either way,\nevidence, refs, relation `why` and source metadata stay exactly as stored,\nand the agent answers in the user's language.\n\nA writer can also attach an English rendering of a memory as the reserved\nentry metadata key `summary_en`. `kmp_ask` searches it and never cites it: a\nquestion in English reaches a memory written in Spanish through the summary,\nand what is cited is the Spanish text byte for byte. The kernel lints the\nsummary rather than trusting it — `kmp_ingest` warns about one that leans to\nanother language, is too thin, repeats the text, or drops an identifier the\ntext carries, and ranking makes the same reading, so such a summary carries\nnothing. A citation the summary carried says so: `matched_via: summary`, with\nthe question's words the rendering supplied in `summary_terms`.\n`kmp_write_memory` takes it as `current.summary_en`, and a strict write\nrequires it when the memory is not written in English. A memory written\nbefore summaries existed still owes one: `kmp-mcp summaries pending` lists\nthem, the doctor counts them, and the agent attaches each with\n`kmp_write_memory` and the intent `record_summary`, the stored text untouched.\n\nQuestions in Chinese, Japanese or Thai are not segmented by word yet. Their\nstored memory remains byte-exact and inspectable; word-based semantic\nretrieval in those scripts is not supported.\n\nTemporal requests such as “yesterday” use temporal navigation, not semantic\nAsk. A semantic question that carries a date or a range is one Ask that\nstands where it was asked: `as_of` for an instant, `interval` for a half-open\nspan, `axis` for the clock, and the proof declares where it stood.\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.\n\nIt also means owning infrastructure, TLS, identity, authorization and\nobservability. Keep it local until those responsibilities buy you something.\nThen read [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. KMP validates, stores, retrieves and proves. Your agent writes the final\nanswer from the returned evidence, and writes the English search summary when\nit stores a memory; KMP lints that summary and never produces one.\n\n### What if my question is Spanish but the evidence is English?\n\nThe agent asks in English and passes your Spanish as `asked_as`, so the\nEnglish evidence is reached directly; a Spanish memory is reached through the\nEnglish `summary_en` its writer attached, and with a lexical-bridge table\nbeside the store Ask crosses the two languages on its own and says which word\npairs it used. The stored material is never translated, and the answer comes\nback in Spanish.\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 another\nprocess holding the embedded store.\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## Docs and project links\n\n- [Documentation home](docs/index.md)\n- [Embedded KMP](docs/embedded/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\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", "bytes": 14945, "sha": "1fa71c37abac9ed94667ddc94dee2076b6fe119d06585c47dc575d5a1302a4d4", "repo_slug": "underpass-ai/kmp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_underpass_ai_kmp_b1ae6069/readme" }