grpcer/ownmem

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

How OwnMem governs AI agent memory

The differentiator is not one ranking formula. OwnMem turns coding-agent memory into a verifiable retrieval and evolution protocol:

| Mechanism | How it is enforced | | --- | --- | | 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,grok --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.

• Claude Code and Grok CLI both read .claude/settings.json. Grok additionally needs this folder trusted once — run /hooks-trust inside grok, or start it with grok --trust — otherwise it silently runs none of these hooks.
• Codex reads /.codex/hooks.json behind three separate permissions: (1) hooks = true under [features] in ~/.codex/config.toml, (2) the project itself trusted — interactive Codex asks the first time it opens it, or add [projects.""] with trust_level = "trusted" — and (3) the hook trust prompt on first sight. An untrusted project is silent: it never discovers the file, and neither --dangerously-bypass-hook-trust nor a -c projects... override reaches that layer. The hook process runs at the project root with node_modules/.bin on PATH and the same JSON on stdin that Claude Code sends, but with no CODEX_* variable of any kind, so every command declares its host explicitly.
• Cursor and Gemini CLI receive instruction adapters only. Neither exposes a hook surface, so they recall from memory but contribute no collection.

Upgrading from 0.5.x: the hook configuration is now v2. Run npx ownmem init --update once. Commands that predate it are replaced where they stand, hooks you wrote yourself are never touched, and the session-start pass keeps saying the configuration is out of date until you do.

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

Telemetry and the daily pass

Runtime events expire after thirty days and never leave the machine that wrote them. The daily pass reduces each finished day to a counted package small enough to commit, so a second machine — and a report run months later — can still see it:

npx ownmem daily                       # archive yesterday, commit it, report only what is wrong
npx ownmem archive --backfill          # reduce every day still on disk to a counted package
npx ownmem report --since 7d --fleet   # merge every machine's packages, and name the missing days

• What a package holds: counts, buckets, latency percentiles, abstain reasons, the quota and golden-set hashes, and topic names that are already in the public index.
• What it never holds: query text or its digest, topic bodies, file paths, machine or account names, and no timestamp finer than the day.
• It commits itself. Packages are staged against a private index with explicit paths and a compare-and-swap on HEAD, so a pass can never carry away another session’s staged work. Set telemetry.auto_commit to false in /config.json, or pass --no-commit, to archive without committing.
• It points core.hooksPath at /git-hooks/, where ownmem init generates the post-commit fallback, and only while that setting is empty or points at an untouched default hook directory. Set telemetry.manage_hooks_path to false to leave it alone.
• Across machines, report --fleet merges every machine’s packages and names the days that have commits but no package, instead of quietly presenting one laptop’s week as the whole history.

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

Local-first by default

• 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.
• 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 version migrations | | 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.