\n\n# OwnMem — Git-Native Memory for AI Coding Agents\n\n**Open-source project memory for Claude Code, Codex, Cursor, Gemini CLI, and other AI coding agents — local, deterministic, reviewable, and safely self-improving.**\n\n`Git-native` · `AI agent memory` · `local recall` · `evidence-governed` · `Apache-2.0`\n\n[](https://www.npmjs.com/package/ownmem)\n[](https://www.npmjs.com/package/ownmem)\n[](https://github.com/grpcer/ownmem/actions/workflows/ci.yml)\n[](https://nodejs.org)\n[](./LICENSE)\n\n**English** · [简体中文](./docs/i18n/README.zh-CN.md) · [繁體中文](./docs/i18n/README.zh-TW.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Français](./docs/i18n/README.fr.md) · [Deutsch](./docs/i18n/README.de.md) · [Português (BR)](./docs/i18n/README.pt-BR.md)\n\n
\n\n## Why OwnMem\n\nMost 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?**\n\n| Advantage | What it means in practice |\n| --- | --- |\n| **The repository owns memory** | Readable Markdown in `.ownmem/` travels through clone, review, and rollback with the code. |\n| **One memory serves many agents** | Claude Code, Codex, Cursor, Gemini CLI, Grok CLI, and other hosts share one source of project truth. |\n| **Deterministic local recall** | Default recall makes no model or network call; the same query, config, and snapshot produce the same ranking. |\n| **Evidence before authority** | Content cannot declare itself trusted. Independent receipts and live evidence checks decide delivery. |\n| **Bounded growth** | Schemas, quotas, duplicate gates, lifecycle rules, and audits keep memory from becoming a second abandoned wiki. |\n| **Low-risk automation, review for impact** | Replay-proven R0 retrieval metadata can evolve unattended; prose, policy, and higher-risk changes cannot. |\n\n## Architecture\n\n\n \n \n\n\nOwnMem separates writing experience from delivering it to an agent:\n\n- **Repository source of truth.** L1 routing, L2 area indexes, and L3 topics remain reviewable Markdown; trust receipts live outside the text they authorize.\n- **Compile, then recall.** Schema, graph, lifecycle, and evidence gates produce a content-addressed immutable snapshot instead of rereading changing prose at query time.\n- **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.\n- **Four independent delivery gates.** relevance, epistemic validity, task applicability, and action risk lead to normal delivery, advisory, quarantine, or abstention under a context budget.\n- **Bounded unattended evolution.** The end-of-turn coordinator may promote only replay-proven, quota-bounded, precisely reversible R0 metadata; R1–R5 becomes review material.\n\n## How OwnMem governs AI agent memory\n\nThe differentiator is not one ranking formula. OwnMem turns coding-agent memory into a verifiable retrieval and evolution protocol:\n\n| Mechanism | How it is enforced |\n| --- | --- |\n| **Evidence-carrying memory** | Content hash, evidence root, lifecycle, applicability, risk, and predecessor receipts determine whether text may enter context. |\n| **Counterfactual promotion gate** | Automation must prove baseline miss, candidate-only recovery, and zero regression on the previously passing corpus. |\n| **Risk from change surface** | Risk is derived from what changed and what it can affect; an agent cannot downgrade its own proposal. |\n| **Content-addressed compensating rollback** | Automatic edits carry a verified inverse operation; failures or harmful outcomes restore the exact previous bytes without erasing history. |\n| **Memory-poisoning quarantine** | Candidates, content, authority, and evidence are separate trust domains; retrieval never grants permission to act. |\n| **Selective delivery** | Insufficient evidence produces advisory, quarantine, or abstention instead of invented confidence. |\n| **Immutable compiled snapshots** | Markdown, graph edges, ranking identity, and trust state become one reproducible runtime input. |\n| **Three anti-pollution ledgers** | Retrieval correctness, user/host-confirmed outcomes, and agent self-attribution never impersonate one another. |\n\nRead the detailed [technical design and research mapping](./docs/TECHNICAL.md).\n\n## Quick start\n\nRequires Node.js 20.6 or newer. Run this inside the repository that should own the memory:\n\n```bash\nnpm install --save-dev ownmem\nnpx ownmem init --locale auto --hosts claude,codex --layers dashboard --hook\n```\n\nReopen 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`.\n\n## Daily use\n\nAfter setup, keep working in plain language:\n\n> “Remember this: staging deployment timeouts come from the pool cap, not too few workers. Check both together next time.”\n\n> “Before changing this, check whether the project memory has seen the same failure.”\n\nThe 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:\n\n```bash\nnpx ownmem dashboard --open\nnpx ownmem evolve status\nnpx ownmem evolve run --force\n```\n\n## Trust and automation boundary\n\nOwnMem automates the part it can prove, not the part that merely sounds plausible.\n\n- **Automatic:** deterministic recall, candidate scanning, tripwire checks, counterfactual replay, R0 trigger backfill, machine trust receipt, audit, compile, observation, quarantine, and exact rollback.\n- **Escalated:** new prose knowledge, policy, active-set changes, conflicts, insufficient evidence, R1–R5 changes, and publishing.\n- **Hard boundary:** a candidate is not memory; self-attribution is not user confirmation; retrieved text cannot override host instructions or authorize tools.\n- **Failure behavior:** unsigned content or unverifiable evidence is quarantined; evidence drift becomes advisory; transaction failure restores the prior validated state.\n\n## Where it fits\n\n| Good fit | Choose another system when |\n| --- | --- |\n| A team wants project knowledge reviewed and migrated with code. | You need a cross-repository personal profile or global user memory. |\n| Several coding agents rotate through one repository. | You need to capture every conversation automatically with no evidence or risk boundary. |\n| Local, reproducible recall with no retrieval API bill matters. | You need large-scale cloud vector search or a real-time global knowledge graph. |\n| Bad memory must be attributable, rejectable, and reversible. | Maximum recall volume matters more than governance. |\n\n## Local-first by default\n\n- Default ranking reads repository files and local snapshots only: no LLM call, network request, or retrieval API bill. Delivered excerpts still use the host agent's context window and are capped by the configured context budget.\n- Runtime events stay in a Git-ignored local directory. Missing outcome samples are shown as unavailable, never fabricated as 0%.\n- Secrets and personal or production data that do not belong in Git do not belong in memory.\n- The embedding lane is optional and isolated. It joins weighted ranking only after repository-local A/B evidence passes the safety gate.\n\n## Research lineage\n\nOwnMem does not claim these foundations as inventions. Its contribution is their composition into an executable protocol for repository memory:\n\n- **Agent memory and reflection:** [Reflexion (NeurIPS 2023)](https://papers.neurips.cc/paper_files/paper/2023/hash/1b44b878bb782e6954cd888628510e90-Abstract-Conference.html), [MemGPT (2023)](https://arxiv.org/abs/2310.08560)\n- **Memory and knowledge-base poisoning:** [AgentPoison (NeurIPS 2024)](https://proceedings.neurips.cc/paper_files/paper/2024/hash/eb113910e9c3f6242541c1652e30dfd6-Abstract-Conference.html), [PoisonedRAG (USENIX Security 2025)](https://www.usenix.org/conference/usenixsecurity25/presentation/zou-poisonedrag)\n- **Untrusted data separated from authority:** [CaMeL: Defeating Prompt Injections by Design (2025)](https://arxiv.org/abs/2503.18813)\n- **Independent provenance:** [in-toto (USENIX Security 2019)](https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias)\n- **Selective prediction and abstention:** [Selective Classification (JMLR 2010)](https://jmlr.org/papers/v11/el-yaniv10a.html)\n- **Differential validation and compensation:** [Metamorphic Testing (1998)](https://www.cse.ust.hk/~scc/publ/CS98-01-metamorphictesting.pdf), [Sagas (SIGMOD 1987)](https://doi.org/10.1145/38713.38742)\n- **Decomposed retrieval evaluation:** [ARES (NAACL 2024)](https://aclanthology.org/2024.naacl-long.20/), [RAGChecker (2024)](https://arxiv.org/abs/2408.08067)\n\nThese citations describe the research lineage; they do not imply that the papers implement OwnMem or that OwnMem reproduces their experiments.\n\n## Documentation\n\n| Document | Purpose |\n| --- | --- |\n| [Architecture](./docs/ARCHITECTURE.md) | Package boundaries, snapshots, trust, and evolution |\n| [Technical design](./docs/TECHNICAL.md) | Mechanisms, threat model, and research mapping |\n| [Plugins](./docs/PLUGINS.md) | Optional host plugin installation |\n| [Updating](./docs/UPDATING.md) | Safe repository updates and version migrations |\n| [Privacy](./docs/PRIVACY.md) | Local data and optional channel boundaries |\n| [Changelog](./CHANGELOG.md) | Version history |\n| [License](./LICENSE) | Apache-2.0 |\n\nOwnMem is open source. Reproducible issues and pull requests are welcome.\n",
"bytes": 10917,
"sha": "dcaf2fb012eedba4d59fda83bad133dd3cdc72ba4779336cb8ac0c48a8b89c36",
"repo_slug": "grpcer/ownmem",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_grpcer_ownmem_b6330495/readme"
}
![\"OwnMem](\"./docs/assets/architecture-dark.svg\")
\n