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 safely self-improving.

Git-native · AI agent memory · local recall · evidence-governed · Apache-2.0

= 20.6">

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?

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:

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

• Automatic: deterministic recall, candidate scanning, tripwire checks, counterfactual replay, R0 trigger backfill, machine trust receipt, audit, compile, observation, quarantine, and ex