OwnMem — Git-Native Project Memory for AI Coding Agents

Repo-owned. Deterministic. Reviewable.

An open-source AI memory system for coding agents and software repositories. One persistent project memory serves Claude Code · Codex · Antigravity · Cursor · Gemini CLI · Grok CLI.

= 20">

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

What is OwnMem?

OwnMem is an open-source coding agent memory system that keeps curated project decisions, constraints, and debugging lessons as reviewable Markdown inside your repository. The same long-term project memory works across agents and sessions, travels with Git, and rolls back with the code it describes.

Its deterministic, Unicode-script-aware BM25F engine ranks memory in .ownmem/. For the same query, configuration, and compiled snapshot, default recall returns the same ranking without a model call, network request, or query-time token cost — in about two milliseconds on the public benchmark.

OwnMem has two pieces. The npm package is the engine: it lives in each repository as a reviewed devDependency and owns that repository's memory in .ownmem/. The agent plugin is an optional convenience layer installed once per machine: it teaches your agent to run the engine, including walking you through the per-repository setup.

Note: A repository is ready once it has the package and .ownmem/, however you got there. Start from either piece.

OwnMem at a glance

Implementation and release boundaries are documented in Repository architecture.

Quick start

OwnMem requires Node.js 20 or newer. Three steps, all inside the repository you want to give a memory.

Step 1 — install the engine. It becomes a normal devDependency, reviewed and pinned like any other:

npm install --save-dev ownmem

Step 2 — initialize this repository. This creates .ownmem/ and the per-agent adapter files:

npx ownmem init --locale auto --hosts claude,codex --layers dashboard --hook

Step 3 — reopen your agent. Agents discover commands at session start, so everything below appears in the next session, not the one that ran init.

This is the recommended setup — Claude Code and Codex work out of the box and the local console is included. What you have after reopening:

• Claude Code gains a project command: /ownmem <anything you want the memory to do>.
• Codex and Grok CLI automatically discover the repository's ownmem skill.
• Antigravity loads the same project instructions (AGENTS.md, GEMINI.md), so it follows the memory discipline too — as does every other agent that reads them.
• The console is a terminal command, not a slash command: npx ownmem dashboard --open. (The optional plugin below adds /ownmem:dashboard.)

There is no daily setup command — just work as usual. Repeat the three steps once for each repository that should have its own memory.

Only use one agent? Change --hosts claude,codex to --hosts claude or --hosts codex. Antigravity and Grok CLI read the same AGENTS.md (and, for Grok, .agents/skills/) files as Codex, so --hosts codex covers both. Cursor uses --hosts cursor, classic Gemini CLI setups use --hosts gemini, and --hosts generic works with other agents.

Initialization creates .ownmem/ and adds a small OwnMem section to the agent's project instructions. It never changes text outside its marked boundaries.

Daily use

After setup, there are only two things to remember.

1. Talk to your agent. When you learn something worth keeping, say it in plain language:

"Remember this — the timeout comes from the pool cap, not the worker count. Never raise workers without raising the pool."

Later, ask as naturally as you normally would:

"The staging deploy is hanging again. Check the project memory before you change anything."

The agent handles writing, validation, and recall. You do not need to open .ownmem/ or run audit and recall yourself. Prefer an explicit command? /ownmem <request> (Claude Code) and the ownmem skill (Codex) route the same request through the memory.

2. Open the console when you want an overview. It shows adoption, recall quality, latency, and memory health for this repository, and is available only on your computer at 127.0.0.1:

npx ownmem dashboard --open

That is the whole daily workflow. The audit, manual recall, and feedback commands are for CI and troubleshooting; normal users do not need to remember them.

Why this exists

I build Oriveo, a BYOK multi-model AI client shipping on iOS, Android, Web, and desktop — a large codebase I work on every day with coding agents, switching between Claude Code and Codex. Every repository kept accumulating hard-won lessons: debugging root causes, toolchain traps, timing races. And every time the agent, the machine, or a teammate changed, those lessons quietly disappeared, because they lived in one tool's memory on one machine.

Vector and cloud memory services never felt right for this: knowledge about a repository should not need an account, a server, or a per-query bill. So the memory moved into the repository itself. OwnMem is the system I run daily inside the Oriveo codebase — hundreds of curated memories, kept honest by quotas and audits — extracted and rebuilt as a clean public engine.

Why OwnMem

OwnMem makes four bets, and every design decision follows from them:

• Memory belongs in the repository. Reviewable Markdown that travels with git, shows up in pull requests, and rolls back like any other code. Clone the repo, get the memory — no account, no sync service, no export step.
• Recall must be free and deterministic. The same query returns the same ranking, with no model call, no latency tax, and no per-question bill: 100% Recall@1 at a 2.46 ms P95 on the locked public benchmark.
• Memory must outlive any single tool. The same files serve Claude Code, Codex, Antigravity, Cursor, Gemini CLI, and Grok CLI, so switching agents never means losing what the team learned.
• Memory must stay small to stay trusted. A zero-net-growth quota, a pure Node audit, near-duplicate and drift gates keep it lean and current instead of turning into a second wiki that nobody prunes.

What OwnMem is not

• Not a vector database. If you want fuzzy semantic search over large memory pools, a vector or knowledge-graph memory service fits better.
• Not automatic capture. Writes are deliberate and curated — review is the quality gate. Built-in agent memories are more convenient, at the cost of being tool-locked and unreviewable.
• Not cross-repository or cloud-synced. Memory travels with the repository's own git history — clone the repo and it is there. But it is never shared across repositories, and it never passes through a memory service, by design.

Inside .ownmem/: the three-tier memory

The always-loaded part stays tiny; everything else is read on demand:

A topic file is plain Markdown with a strict, schema-checked frontmatter — symptoms and phrasings in triggers, proof in evidence (abridged here; ownmem init scaffolds a complete example):

---
name: pool_cap_timeout
description: staging deploys time out when workers exceed the pool cap
metadata:
  type: l