ownmem

OwnMem

Git-native memory for AI coding agents

Open-source project memory for Claude Code, Codex, Cursor, Gemini CLI, and other AI coding agents — local, deterministic, reviewable, and never written behind your back.

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português (BR)

✨ 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?

Advantage	What it means in practice
The repository owns memory	Readable Markdown in .ownmem/ travels through clone, review, and rollback with the code, and every agent in the repository reads the same source.
Deterministic local recall	Default recall makes no model or network call; the same query, config, and snapshot produce the same ranking.
Evidence before authority	Content cannot declare itself trusted. Independent receipts and live evidence checks decide delivery.
It tells you when it does not know	Delivery is graded: the memory quoted, up to three pointers, or an abstention that names the gate that refused.
Net-zero growth	A hard entry count that only ratchets down, so adding to a full corpus means retiring something in the same change.

_{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”.

	Instruction files	Built-in agent memory	OwnMem
Who writes it	you, by hand	the agent, from your conversations	you, reviewed like code
Where it lives	one file in the repository	the vendor's account	Markdown in your repository
What reaches the model	all of it, every turn	whatever its own recall picked	one of three tiers, under a token budget
When an entry is wrong	you edit the file	you may never see the entry	evidence drift downgrades it and names what moved
Cost per turn	the whole file in tokens	a retrieval call	no model call, no network call

🚀 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.

Host	How recall happens	Setup
Claude Code	A hook before every Edit and Write, and on request	claude
Codex	A hook before every patch it applies, and on request	codex; the hooks need three one-time trust steps, which init prints
Grok CLI	Reads Claude Code's hook configuration through its compatibility layer	grok, alongside claude if you use both; trust the folder once with /hooks-trust
Cursor	An always-applied rule, or the MCP server	cursor; the MCP server takes one manual step, see Plugins
Gemini CLI	Instructions, or the MCP server	gemini; the MCP server takes one manual step, see Plugins

⚠️ 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

Good fit	Choose another system when
A team wants project knowledge reviewed and migrated with code.	You need a cross-repository personal profile or global user memory.
Several coding agents rotate through one repository.	You need to capture every conversation automatically with no evidence or risk boundary.
Local, reproducible recall with no retrieval API bill matters.	You need large-scale cloud vector search or a real-time global knowledge graph.
Bad memory must be attributable, rejectable, and reversible.	Maximum recall volume matters more than governance.

📚 Documentation

Document	Purpose
Architecture	Package boundaries, snapshots, trust, and delivery
Technical design	Mechanisms, threat model, and research mapping
Plugins	Per-host setup, plugins, and trust steps
Updating	Safe repository updates and version migrations
Privacy	Local data and optional channel boundaries
Changelog	Version history
Contributing	Reporting issues and sending changes
Security	Reporting a vulnerability
License	Apache-2.0

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.