✨ Why OwnMem

Most AI agent memory systems optimize for remembering more. OwnMem starts with a different question: who owns project knowledge, who may change it, and how can a bad memory be stopped before it changes a coding agent's actions?

_{Measured on the locked CC0 corpus in this repository. Reproduce it in a clone with npm run benchmark.}

🆚 How it compares

OwnMem does not replace CLAUDE.md or AGENTS.md. Those files say how to work here, and they are read in full every turn. OwnMem answers a different question — which of the things this project learned the hard way are worth putting in front of the model for this task — and it is allowed to answer “none of them”.

🚀 Quick start

Requires Node.js 20.6 or newer. Run this inside the repository that should own the memory:

npm install --save-dev ownmem
npx ownmem init --hook --hosts claude,codex

Reopen the agent afterwards. Name the hosts you use in --hosts (claude, codex, cursor, gemini, grok); the list is recorded, and passing it again later is how a host is added or removed. init creates .ownmem/ and the host adapters, edits instruction files such as CLAUDE.md only inside managed blocks, and prints any one-time step a host still needs. Add --check to the same command to preview it, and --locale auto to write the generated instructions in your system language.

⚠️ Upgrading from 0.6.0? Update the package with npm install --save-dev ownmem@latest, then run npx ownmem init --update before anything else. 0.6.0 installed hooks whose subcommands no longer exist, so an installation that keeps them runs a failing command on every Bash call. The update removes them and never touches hooks you wrote yourself. Updating covers the rest, including the core.hooksPath cleanup.

💬 Daily use

Keep working in plain language. Your agent drafts a memory when you ask for one, and you review it like code:

“Remember this: staging deployment timeouts come from the pool cap, not too few workers. Check both together next time.”

“Before changing this, check whether the project memory has seen the same failure.”

Recall answers in one of three tiers: the memory quoted, up to three pointers to go and read, or an abstention. A real run:

$ npx ownmem recall -- "staging deploy timed out again, should I add more workers?"
== staging deploy timed out again, should I add more workers? ==
  staging_timeout_pool_cap  [score=0.875 lanes=exact,bm25f,ngram fields=body,codePath,description,hooks,name,triggers]
      matched deploy,more,out,staging,staging deploy timed out,timed
      trust advisory authority · lifecycle advisory (not fully verified)
        Treat it as a lead to re-check against the code, not as an established fact.
      excerpt(body) **Why**: `DB_POOL_MAX` is 10 on staging. Adding workers only queues more requests behind the same ten connections, so the deploy health check times out sooner, not later.
      file .ownmem/staging_timeout_pool_cap.md

Trust is stated, not implied. Nothing backs this entry yet — no review has confirmed it, and it cites no authority document or code anchor — so it arrives as a lead to re-check rather than as an established fact.

The commands you will reach for yourself:

npx ownmem new staging_timeout_pool_cap   # scaffold one memory that already passes every gate
npx ownmem report --since 7d              # used? fast enough? right? what to do next
npx ownmem dashboard --open               # open the local console
npx ownmem mcp                            # serve recall and read to any MCP host over stdio

ownmem mcp exists for hosts without hooks. It exposes exactly two tools, recall and read, and neither can change a memory; the gate commands (audit, trust, compile) and every memory write stay off that surface. Plugins shows how to register it so it runs the project's own copy.

🧩 How it works

• Repository source of truth. L1 routing, L2 area indexes, and L3 topics remain reviewable Markdown; trust receipts live outside the text they authorize.
• Compile, then recall. Schema, graph, lifecycle, and evidence gates produce a content-addressed immutable snapshot. Five deterministic lanes — exact, BM25F, n-gram, fuzzy, and graph — are fused locally; embeddings are an optional sixth lane at weight 0 until local A/B evidence passes.
• Four gates, three tiers. Relevance, epistemic validity, task applicability, and action risk each refuse on their own grounds. Above a threshold read off an ablation curve the memory is quoted; below it come up to three pointers that are explicitly not answers; with nothing qualified, an abstention that names the gate that refused.
• No unattended writes. There is no coordinator, no promotion, and no candidate queue. The package measures, proposes, and refuses; every change to memory is a commit somebody makes, and no ranking change lands without the evaluation harness.

Mechanisms, threat model, and research mapping: Technical design.

🔒 Privacy and boundaries

• Local by default. Ranking reads repository files and local snapshots only: no LLM call, no network request, no retrieval API bill. Delivered excerpts still use the agent's context window, capped by the configured budget.
• Telemetry stays on the machine. Runtime events live in a Git-ignored directory and expire after thirty days. The daily pass (ownmem daily) reduces each finished day to a counted package with no query text, topic bodies, or file paths. Missing samples show as unavailable, never as 0%.
• Retrieved text is data. It cannot override host instructions or authorize a tool, and an agent's self-attribution never counts as user confirmation.
• Failures are visible. An entry with unsigned content or an unverifiable evidence target is withheld; evidence drift downgrades it to advisory and names what moved.
• Keep secrets out. Secrets and personal or production data that do not belong in Git do not belong in memory.

🧭 When to use it

📚 Documentation

Research lineage

OwnMem does not claim these foundations as inventions. Its contribution is their composition into an executable protocol for repository memory:

• Agent memory and reflection: Reflexion (NeurIPS 2023), MemGPT (2023)
• Memory and knowledge-base poisoning: AgentPoison (NeurIPS 2024), PoisonedRAG (USENIX Security 2025)
• Untrusted data separated from authority: CaMeL: Defeating Prompt Injections by Design (2025)
• Independent provenance: in-toto (USENIX Security 2019)
• Selective prediction and abstention: Selective Classification (JMLR 2010)
• Ablation-based validation: Metamorphic Testing (1998)
• Decomposed retrieval evaluation: ARES (NAACL 2024), RAGChecker (2024)

These citations describe the research lineage; they do not imply that the papers implement OwnMem or that OwnMem reproduces their experiments.

OwnMem is open source. Reproducible issues and pull requests are welcome.