Open-source project memory for Claude Code, Codex, Cursor, Gemini CLI, and other AI coding agents — local, deterministic, reviewable, and safely self-improving.
Git-native · AI agent memory · local recall · evidence-governed · Apache-2.0
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.
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 <project>/.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."<path>"] 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 <memory-dir>/config.json, or pass --no-commit, to archive without committing.
It points core.hooksPath at <memory-dir>/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.
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:
OwnMem 是一个开源、Git 原生的 AI 编程代理记忆系统,面向 Claude Code、Codex、Cursor 和 Gemini CLI 等。它把项目知识以可审查的 Markdown 存在你仓库的 .ownmem/ 文件夹里,让多个代理共享同一份本地、确定性的记忆。