OwnMem

Repository-owned memory for AI coding agents — local, deterministic, reviewable, and safely self-improving.

Git-native · local recall · multi-agent · evidence-governed · Apache-2.0

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

Why OwnMem

Most 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 an 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. | | One memory serves many agents | Claude Code, Codex, Cursor, Gemini CLI, Grok CLI, and other hosts share one source of project truth. | | 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. | | Bounded growth | Schemas, quotas, duplicate gates, lifecycle rules, and audits keep memory from becoming a second abandoned wiki. | | Low-risk automation, review for impact | Replay-proven R0 retrieval metadata can evolve unattended; prose, policy, and higher-risk changes cannot. |

Architecture

OwnMem separates writing experience from delivering it to an agent:

• 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 instead of rereading changing prose at query time.
• Five deterministic candidate lanes. exact, BM25F, n-gram, fuzzy, and graph are fused locally. Embeddings are an optional sixth lane and stay at weight 0 until local A/B evidence passes.
• Four independent delivery gates. relevance, epistemic validity, task applicability, and action risk lead to normal delivery, advisory, quarantine, or abstention under a context budget.
• Bounded unattended evolution. The end-of-turn coordinator may promote only replay-proven, quota-bounded, precisely reversible R0 metadata; R1–R5 becomes review material.

What is different in 0.3

The differentiator is not one ranking formula. OwnMem 0.3 turns agent memory into a verifiable evolution protocol:

| Mechanism | OwnMem 0.3 | | --- | --- | | Evidence-carrying memory | Content hash, evidence root, lifecycle, applicability, risk, and predecessor receipts determine whether text may enter context. | | Counterfactual promotion gate | Automation must prove baseline miss, candidate-only recovery, and zero regression on the previously passing corpus. | | Risk from change surface | Risk is derived from what changed and what it can affect; an agent cannot downgrade its own proposal. | | Content-addressed compensating rollback | Automatic edits carry a verified inverse operation; failures or harmful outcomes restore the exact previous bytes without erasing history. | | Memory-poisoning quarantine | Candidates, content, authority, and evidence are separate trust domains; retrieval never grants permission to act. | | Selective delivery | Insufficient evidence produces advisory, quarantine, or abstention instead of invented confidence. | | Immutable compiled snapshots | Markdown, graph edges, ranking identity, and trust state become one reproducible runtime input. | | Three anti-pollution ledgers | Retrieval correctness, user/host-confirmed outcomes, and agent self-attribution never impersonate one another. |

Read the detailed technical design and research mapping.

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 --locale auto --hosts claude,codex --layers dashboard --hook

Reopen the agent after initialization. OwnMem creates .ownmem/ and edits only managed marker regions in host files. Use --hosts claude, --hosts codex, --hosts cursor, or --hosts gemini when only one adapter is needed; preview changes with npx ownmem init --check.

Daily use

After setup, keep working in plain language:

“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.”

The host recalls before scoped work and schedules one locked, debounced evolution pass at the end of a turn. You normally do not need to chain promotion, trust, audit, or compile commands. Open the local console or inspect the coordinator when you want visibility:

npx ownmem dashboard --open
npx ownmem evolve status
npx ownmem evolve run --force

Trust and automation boundary

OwnMem automates the part it can prove, not the part that merely sounds plausible.

• Automatic: deterministic recall, candidate scanning, tripwire checks, counterfactual replay, R0 trigger backfill, machine trust receipt, audit, compile, observation, quarantine, and exact rollback.
• Escalated: new prose knowledge, policy, active-set changes, conflicts, insufficient evidence, R1–R5 changes, and publishing.
• Hard boundary: a candidate is not memory; self-attribution is not user confirmation; retrieved text cannot override host instructions or authorize tools.
• Failure behavior: unsigned content or unverifiable evidence is quarantined; evidence drift becomes advisory; transaction failure restores the prior validated state.

Where it fits

| 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, zero-query-cost recall 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. |

Local-first by default

• Default recall reads repository files and local snapshots only: no LLM call, network request, or per-query token cost.
• Runtime events stay in a Git-ignored local directory. Missing outcome samples are shown as unavailable, never fabricated as 0%.
• Secrets and personal or production data that do not belong in Git do not belong in memory.
• The embedding lane is optional and isolated. It joins weighted ranking only after repository-local A/B evidence passes the safety gate.

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)
• Differential validation and compensation: Metamorphic Testing (1998), Sagas (SIGMOD 1987)
• 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.

Documentation

| Document | Purpose | | --- | --- | | Architecture | Package boundaries, snapshots, trust, and evolution | | Technical design | Mechanisms, threat model, and research mapping | | Plugins | Optional host plugin installation | | Updating | Safe repository updates and 0.2 → 0.3 migration | | Privacy | Local data and optional channel boundaries | | Changelog | Version history | | License | Apache-2.0 |

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