OwnMem gives Claude Code, Codex, and other coding agents a memory that lives
inside the repository: plain Markdown in .ownmem/, ranked by a deterministic,
Unicode-script-aware BM25F engine. Recall never calls a model, never touches
the network, and never spends a query-time token — the same question returns
the same answer, in about two milliseconds.

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.

Quick start

OwnMem requires Node.js 20 or newer. In the repository you want to give a
memory, run:

npm install --save-dev ownmem
npx ownmem init --locale auto --hosts claude,codex --layers dashboard --hook

This is the recommended setup: Claude Code and Codex both work out of the box,
and the local console is included. Reopen your agent when initialization
finishes — agents discover commands at session start, so everything below
appears in the next session, not the one that ran init.

What you have after reopening:

• Claude Code gains a project command: /ownmem <anything you want the memory to do>.
• Codex automatically discovers the repository's ownmem skill.
• Every agent follows the memory discipline written into the project
  instructions (CLAUDE.md, AGENTS.md).
• 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.

Only use one agent? Change --hosts claude,codex to --hosts claude or
--hosts codex. Gemini CLI and Cursor are also supported with
--hosts gemini,cursor; --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, Gemini CLI, Cursor, 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, dependency-free engine:

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:

/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:

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.

Gemini CLI:

gemini extensions install https://github.com/grpcer/ownmem

This adds the /ownmem command and the ownmem, ownmem-init, and
ownmem-dashboard skills. Update with gemini extensions update 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:

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:

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.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md
for the ground rules: keep default recall deterministic, local, and model-free,
add a regression case for every retrieval change, and run npm test plus
npm run benchmark:release before requesting review. Security reports go
through SECURITY.md.

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 PRIVACY.md, SECURITY.md, and
RELEASE.md before sharing artifacts or publishing a release.