ownmem README

The project's README from github.com/grpcer/ownmem. As one markdown file: README.md.

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

npm version npm downloads release gates node >= 20.6 license Apache-2.0

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?

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 architecture: repository-owned Markdown and independent trust receipts compile into immutable snapshots; deterministic local recall passes four delivery gates, while a bounded evolution coordinator replays, promotes, observes, quarantines, and precisely rolls back low-risk changes.

OwnMem separates writing experience from delivering it to an agent:

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.

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.

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

Trust and automation boundary

OwnMem automates the part it can prove, not the part that merely sounds plausible.

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

Research lineage

OwnMem does not claim these foundations as inventions. Its contribution is their composition into an executable protocol for repository memory:

These citations describe the research lineage; they do not imply that the papers implement OwnMem or that OwnMem reproduces their experiments.

Documentation

Document Purpose
Architecture Package boundaries, snapshots, trust, and evolution
Technical design Mechanisms, threat model, and research mapping
Plugins Optional host plugin installation
Updating Safe repository updates and version migrations
Privacy Local data and optional channel boundaries
Changelog Version history
License Apache-2.0

OwnMem is open source. Reproducible issues and pull requests are welcome.

ownmem (grpcer/ownmem)

bm25
Searching Database…

429 ·GitHub
Ownmem
What is this?OwnMem is an open-source, Git-native memory system for AI coding agents like Claude Code, Codex, Cursor, and Gemini CLI. It stores project knowledge as reviewable Markdown inside your repo's .ownmem/ folder so multiple agents can share the same local, deterministic memory.
Is this a CLI tool or a library I import?It is a Node.js CLI installed with npx that wires itself into your coding agent via hook files (.claude/settings.json, /.codex/hooks.json) and adds a .ownmem/ folder to your repo; it is not something you import as a library.
How do I get it running?Run 'npx ownmem init' inside the repository you want OwnMem to manage, then reopen your coding agent so it picks up the new hooks. You can target one agent with '--hosts claude', '--hosts codex', '--hosts cursor', or '--hosts gemini', and preview changes first with 'npx ownmem init --check'.
Do I need anything besides Node.js?Just Node.js 20.6 or newer; OwnMem's own dependencies are only 'ajv' and 'yaml', with no API key or external service required by default.
Does every supported agent work the same way out of the box?No — Codex needs hooks enabled in config.toml plus the project explicitly trusted before it even sees the hook file, and Grok CLI needs its folder trusted once via '/hooks-trust' or it silently skips every hook. Cursor and Gemini CLI only get instruction adapters, so they can recall memory but never write to it.
Which coding agents does it actually support?Claude Code, Codex, Cursor, Gemini CLI, and Grok CLI are supported today, with Claude Code and Grok CLI getting full hook-based collection while Cursor and Gemini CLI only recall from memory.
Does recall need internet or an LLM call?No — the default ranking pipeline (exact, BM25F, n-gram, fuzzy, and graph matching) runs entirely on local repository files and snapshots; an optional embeddings lane only activates after local A/B evidence proves it helps.
Where does my project memory and usage data actually go?Runtime telemetry events are written to a Git-ignored local directory and expire after thirty days without ever leaving the machine; only an anonymized, day-level summary with no query text, file paths, or machine names is ever committed.
What happens if OwnMem isn't sure a memory entry is trustworthy?Instead of guessing, it delivers the entry as advisory, quarantines it, or abstains entirely under its evidence and action-risk gates, so unverified content never silently influences an agent's actions.
Can a bad automatic memory edit be undone?Yes — every automatic edit carries a verified inverse operation, so a failed or harmful change restores the exact previous bytes without erasing the edit history.
What's different about OwnMem compared to other agent memory tools?Most memory systems optimize for remembering more; OwnMem instead gates every entry through evidence, risk, and lifecycle checks so bad memory can be rejected, quarantined, or rolled back before it changes an agent's behavior.
Can OwnMem use embeddings or vector search?Embeddings are an optional sixth retrieval lane, but they stay at weight zero until a local A/B comparison proves they actually improve results on the repository's own data.
What are similar projects?okf-agent-memory, jevmem, casbin-gateway, agentmemory, EverOS, headroom, billion-context, copperhead
Which topics is it in?llm-memory, ai-memory, bm25, gemini-cli, coding-agents, search, agent-memory, memory, git, cursor, local-first, coding-agent
Creator
grpcer
Size
2.6 MB
Stars
429
Updated
CommitOct 14Releasev0.8.2Oct 11
Age
2mo
Commits · 90 Days