KMP

KMP — Agent memory that remembers why

[KMP]

Local first. Evidence attached. Time included.

[CI] [Release] [crates.io] [License]

KMP is local-first memory for coding agents. It runs beside Codex, Claude Code and Hermes Agent as one small binary with an embedded SQLite store, and it remembers what was decided, what the evidence was and when it happened. Never the transcript. No account, no service, no API key: memory stays on your machine.

Ask your agent "Why did we choose SQLite?" and it answers from stored evidence, or says UNKNOWN instead of guessing. Ask "Show me the memory behind this decision" and ChronoLoom, the viewer that ships inside the binary, opens on that decision and lights up its proof path, with time as a dimension you can move through and a view the agent and you steer together. Memory tools retrieve and audit the evidence, view tools steer that shared ChronoLoom view, and the running server's tools/list defines the current surface.

The problem

Your agent decides something today. Tomorrow a new session, or a different agent, rediscovers the same incident from scratch, or quietly contradicts the decision because the reason for it was in a context window that is gone. Summaries lose the reason; transcripts bury it.

KMP keeps the decision, the evidence it rested on and the moment it happened, as a typed, temporal memory the next session asks instead of re-deriving:

• evidence decides what can be claimed;
• relations carry the reason two memories belong together;
• time travel is explicit, cursor-based and auditable;
• old decisions are superseded, never quietly rewritten;
• UNKNOWN is an honest answer when the evidence is not there.

See it in two minutes

Install KMP in your host (below), then in any project:

kmp-mcp demo

It writes a worked example into that project's memory — a checkout service, an incident, the decision that replaced an earlier one and the measurement that verified it — opens ChronoLoom on it and prints the questions to ask:

Name KMP and the about example:kmp-demo in the request. The example never enters your project's committed bundle. More examples, including KMP's own memory.

Install

Install the plugin, run setup, restart the host once. The guides reach a fresh store on the first read; nothing else to run.

Claude Code

/plugin marketplace add underpass-ai/kmp@marketplace/plugin install kmp@underpass/kmp:setup

Codex CLI

codex plugin marketplace add underpass-ai/kmp --ref marketplacecodex plugin add kmp@underpass

Then ask Codex to run kmp-setup.

Hermes Agent

With kmp-mcp installed, register it and install the skills through the native lifecycle:

kmp-mcp setup --hermes

Verify

kmp-mcp doctor

or run /kmp:doctor. The plugin owns the MCP registration, so do not add a second KMP server by hand. cargo install kmp-mcp --locked is the fallback for a platform with no published engine; MCPB packages, release tarballs and the Pi coding agent are covered in the plugin installation guide. Store selection and repair live in Embedded KMP.

Talk to it like a human

You normally ask for the outcome. The KMP skill chooses the memory moves.

KMP is memory, not surveillance. Store durable decisions and evidence, not transcripts.

It also waits to be asked. A session that never mentions memory makes no KMP call at all. Naming KMP, running a /kmp:* command, or opting in from your project's CLAUDE.md or AGENTS.md is what opens a route. If you would rather it enter known work on its own:

kmp-mcp config memory-routing alwayskmp-mcp config memory-routing on-request   # the default

Ask in any language. The stored evidence is never translated; the answer comes back in yours. How that works.

How it works — the 10-second version

flowchart LR    U[You] --> H[Codex or Claude]    H --> S[KMP skill]    S -->|chooses a move| M[kmp-mcp]    M --> K[embedded kernel]    K --> D[(.kernel/\nSQLite)]    K --> V[local read-only viewer]

The plugin installs the skills and declares one local MCP process. The skill turns intent into one or more typed tools. kmp-mcp validates the request, and the kernel reads or writes the local graph-temporal store. The agent, not KMP, turns returned evidence into conversational prose.

Explore ChronoLoom · Technical architecture

Local means local

.kernel/ is machine state and is ignored by git. A project-scoped store also maintains .kmp/memory.jsonl. Export and Git commit are local operations; pushing, syncing or sharing the bundle makes its contents available elsewhere. Review its diff before sharing. Evidence read by the agent is also subject to the host's data policy, independently of whether you share the bundle.

KMP's own memory

This repository eats its own cooking. .kmp/memory.jsonl is the memory of why KMP is the way it is: the decisions behind it, each with the document that states it, and the ones that superseded older ones. Restore it with /kmp:restore and ask "why does a release advance the marketplace branch last?" How it is written.

Shared memory, when you actually need it

Several machines can share one live KMP service through the Kubernetes topology backed by Neo4j, Valkey and NATS JetStream. It is still free, open source and self-operated. "Enterprise" describes the operational shape, not a paid tier or an Underpass-hosted product. It also means owning infrastructure, TLS, identity, authorization and observability. Keep it local until those responsibilities buy you something. Then read Enterprise KMP.

Project status

KMP is pre-1.0: useful today, actively evolving, and explicit about sharp edges. Release automation builds kmp-mcp for Linux x86_64/arm64, macOS arm64/x86_64 and Windows x86_64. The embedded path is the default; the remote API is versioned v1beta1 and expects an operator.

We do not paste old benchmark numbers into the README. Reproducible, current evidence belongs in Research before it becomes a claim.

FAQ

Does KMP send my memory anywhere?

Not in the default embedded setup. The process, store and viewer are local. The agent host may be cloud-backed, so evidence sent to that agent follows the host's policy.

Do I need Docker, Kubernetes or a database server?

No. The shipped embedded binary uses SQLite. Kubernetes is only for a shared service.

Is there an LLM inside KMP?

No generative model is required for the default embedded path. KMP validates, stores and retrieves evidence; your agent writes the final answer and the English search summary. Optional TypeSafe Jev features send selected text to an external model for judgments, and optional semantic retrieval uses a local encoder. These integrations require explicit configuration. See retrieval defaults and opt-ins.

Can Codex and Claude share the same memory?

Yes: both speak the same MCP contract, and SQLite supports multiple local hosts. Use the maintained project bundle to move state between machines, or the enterprise topology for shared network access.

Is UNKNOWN an error?

No. It means the selected memory did not contain eligible evidence for the question. That is safer than a confident invention.

The tools disappeared. What now?

Run the host's kmp-doctor workflow and follow the missing-tools runbook. The usual suspects are a stale host session, duplicate MCP ownership, a missing binary or an unsupported store format.

Is enterprise KMP paid?

No. The code is Apache-2.0. You operate and pay for any infrastructure you choose to run.

Docs and project links

• Documentation home
• Embedded KMP
• Retrieval defaults and store configuration
• Languages
• Examples
• Enterprise KMP
• Technical architecture
• Runbooks
• Development
• Research
• Contributing
• Security policy
• Changelog
• Issues · Discussions

The implementation and executable checks win when prose disagrees: MCP schemas, plugin capabilities, CLI help, Helm values, API contracts and CI scripts are the source of truth.

License

Apache License 2.0. Free and open source.