grpcer/ownmem: git-Native Project Memory for AI Coding Agents

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: lesson
  triggers: ["staging deploy timeout", "pool cap exceeded"]
  evidence: [deploy-2026-08-12.log]
---

Raising the worker count without raising the connection pool cap exhausts
the pool, and every deploy waits until it times out. Raise both together.

This structure is what makes recall free: the index is small enough to stay loaded, and BM25F only has to rank small, well-labeled topic files.

How OwnMem compares

Every column below solves a real problem — the table shows which trade-offs each one makes, including ours.

¹ Claude Code auto memory and Codex Memories: files under your home directory — machine-local, tool-locked, outside the repository. Cursor retired Memories in 2.1 in favor of Rules; Windsurf memories stay local to one machine and are never committed. ² Editable Markdown, but it lives outside the repo, so it never appears in a pull request. ³ Mem0's Apache-2.0 library runs locally, yet still requires an LLM and an embedding model (an OpenAI key by default, or local models via Ollama) to write and query memory. ⁴ Through an MCP server or its own API — memory is user- or app-scoped, not a set of files your repository owns. ⁵ Claude Code caps its always-loaded index (200 lines / 25 KB); there is no quota, audit, or duplicate gate behind it. ⁶ Optional embedding lane, off by default; it joins ranking only after your local A/B evidence passes the safety gate. ⁷ By design. OwnMem bets on curated, reviewed writes and one-repository scope; if you want automatic capture or user-level memory across apps, those tools genuinely fit better.

Facts checked August 2026 against each project's public documentation — Mem0, Zep / Graphiti, claude-mem, Claude Code auto memory, Codex memories, Cursor rules, Windsurf memories — corrections welcome.

Benchmarks

Every release must pass a locked public benchmark: a 40-topic CC0 corpus spanning 40 BCP 47 language tags and 25 script groups, with 128 positive queries and 40 unrelated negatives. Numbers below are from a release-grade run (25 timed iterations per query):

On the same corpus, a case-insensitive fixed-string grep scores 3.1% Recall@1. Staying lexical and deterministic is not the trick by itself — the Unicode-script-aware BM25F ranking is.

Reproduce it yourself:

git clone https://github.com/grpcer/ownmem
cd ownmem && npm ci && npm run benchmark

Note: Measured on an Apple M5 Pro with Node 25. The corpus hash, rankings, and thresholds are locked, and the run repeats with a reversed topic order to prove determinism. These synthetic metrics are regression evidence, not a claim of real-user accuracy.

References

None of the ranking math is homemade — every technique in the engine is a published, battle-tested method. OwnMem's contribution is composing them into a deterministic engine with two small pure-JavaScript runtime dependencies:

Install the agent plugin (optional, once per machine)

Do you have to install it? No — skip it and everything still works. ownmem init already wrote the discipline into the repository's agent instructions, so any agent that opens the repository follows it. The plugin is machine-wide convenience: it adds the same three skills to every repository on the machine — including ones with no .ownmem/ yet, where the init skill walks the agent through the engine setup. This repository doubles as the plugin marketplace, and the plugin's commands just route to npx ownmem, so a plugin update never rewrites your memory.

One plugin, three skills, one set of names:

Claude Code — run both commands, in order: the first registers this repository as a plugin marketplace (needed once), the second installs the plugin from it:

/plugin marketplace add grpcer/ownmem
/plugin install ownmem@ownmem

Then restart Claude Code: plugin commands load at session start, so they appear in the next session, not the one that installed them. Enable auto-update for the marketplace under /plugin → Marketplaces to receive new versions automatically.

Codex CLI — the same two steps in order: register the marketplace, then add the plugin:

codex plugin marketplace add grpcer/ownmem
codex plugin add ownmem@ownmem

Skills load at session start here too; find them in the $ skill picker. Refresh later with codex plugin marketplace upgrade ownmem followed by codex plugin add ownmem@ownmem.

Grok CLI — again both commands in order: register the marketplace, then install (Grok requires the explicit --trust). Skip the first command if Grok already imported your Claude Code marketplaces:

grok plugin marketplace add grpcer/ownmem
grok plugin install ownmem@ownmem --trust

This installs the same three skills. When a bare skill name is already taken, Grok namespaces it — its built-in dashboard makes ours /ownmem:dashboard. Update with grok plugin update ownmem.

Antigravity — a single command, no marketplace step:

agy plugin install https://github.com/grpcer/ownmem

This imports the ownmem, ownmem-init, and ownmem-dashboard skills; update by re-running the same command. (Classic Gemini CLI setups — API key, Vertex AI, or an enterprise license — can still install the same repository with gemini extensions install https://github.com/grpcer/ownmem.)

Safe automatic updates

OwnMem is designed for reviewable dependency updates, not silent background rewrites. Enable Dependabot or Renovate for npm dependencies. When it opens an OwnMem upgrade pull request, CI should run these three commands in order:

npx ownmem init --update
npx ownmem init --check
npx ownmem audit

init --update refreshes only OwnMem-managed boundaries and preserves project memory. init --check fails when generated adapters drift. Committing package-lock.json keeps every agent and CI job on the reviewed version.

For a manual update, run all four in order:

npm install --save-dev ownmem@latest
npx ownmem init --update
npx ownmem init --check
npx ownmem audit

Avoid floating npx ownmem@latest in production repositories: it is convenient for a first look, but it makes executions non-reproducible.

Layers

Pick how much machinery you want — each layer contains the previous one:

All layers use only the pure-JavaScript ajv and yaml runtime dependencies. OwnMem Console ships complete catalogs for English, Simplified and Traditional Chinese, Japanese, Korean, Spanish, French, German, Brazilian Portuguese, Arabic, Hindi, Indonesian, Russian, Thai, Turkish, and Vietnamese.

AI agent memory FAQ

What is an AI agent memory system?

An AI agent memory system stores knowledge that an agent can reuse across tasks or sessions. OwnMem specializes that idea for software repositories: it keeps reviewed engineering lessons rather than chat history or user profiles.

How do I give Claude Code or Codex persistent project memory?

Follow the quick start once in each repository, then reopen the agent. Claude Code, Codex, Antigravity, Cursor, Gemini CLI, and Grok CLI can read the same .ownmem/ files instead of maintaining separate memory silos.

Where is the memory stored, and how do teammates share it?

Memory is plain Markdown under .ownmem/. Commit appropriate memories to Git and they travel through the repository's normal clone, pull request, access control, and rollback workflow; do not record secrets that do not belong in the repository.

Does OwnMem require an LLM, embedding API, vector database, or network?

Default recall requires none of them: it is local lexical retrieval with two small pure-JavaScript runtime dependencies. Installing packages can require network access, and the optional embedding lane stays disabled until local A/B evidence passes its safety gate.

How is OwnMem different from Mem0, Graphiti, claude-mem, or built-in memory?

OwnMem is repository-scoped, curated, deterministic, and reviewable in Git. Those alternatives are a better fit when you need automatic capture, semantic search over large stores, user-level memory, knowledge graphs, or cloud sync; see the comparison and its sourced limitations.

Safety and evidence

• Memory files remain inspectable Markdown inside the repository.
• Schema, quota, generated-boundary, and near-duplicate checks run locally.
• recall.consumed is the adoption north star; Recall@K is a process metric.
• The default installation never downloads or invokes a model.
• The optional embedding lane stays out of ranking until local A/B evidence passes its safety gate.

OwnMem is licensed under Apache-2.0. See docs/PRIVACY.md, .github/SECURITY.md, and docs/RELEASE.md before sharing artifacts or publishing a release.