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)

Searching Database…

430 ·GitHub
Ownmem
Что это?OwnMem — это система памяти с открытым кодом, нативная для Git, для ИИ-агентов кодинга вроде Claude Code, Codex, Cursor и Gemini CLI. Она хранит знания проекта в виде просматриваемого Markdown внутри папки .ownmem/ вашего репозитория, чтобы несколько агентов могли пользоваться одной локальной детерминированной памятью.
Это CLI-инструмент или библиотека для импорта?Это CLI на Node.js, устанавливаемый через npx, который встраивается в вашего кодинг-агента через файлы хуков (.claude/settings.json, /.codex/hooks.json) и добавляет папку .ownmem/ в репозиторий; это не то, что вы импортируете как библиотеку.
Как его запустить?Выполните 'npx ownmem init' внутри репозитория, которым должен управлять OwnMem, затем заново откройте своего кодинг-агента, чтобы он подхватил новые хуки. Можно нацелиться на одного агента с '--hosts claude', '--hosts codex', '--hosts cursor' или '--hosts gemini', а изменения предварительно посмотреть с 'npx ownmem init --check'.
Нужно ли что-то ещё, кроме Node.js?Только Node.js 20.6 или новее; собственные зависимости OwnMem — это лишь 'ajv' и 'yaml', без API-ключей или внешних сервисов по умолчанию.
Все ли поддерживаемые агенты работают одинаково сразу?Нет — Codex требует включения хуков в config.toml плюс явного доверия проекту, прежде чем он вообще увидит файл хука, а Grok CLI требует однократного доверия папке через '/hooks-trust', иначе он молча пропускает каждый хук. Cursor и Gemini CLI получают только адаптеры инструкций, поэтому могут извлекать память, но никогда не записывать её.
Каких кодинг-агентов он реально поддерживает?Сегодня поддерживаются Claude Code, Codex, Cursor, Gemini CLI и Grok CLI, причём Claude Code и Grok CLI получают полный сбор на основе хуков, а Cursor и Gemini CLI только извлекают из памяти.
Нужен ли для извлечения памяти интернет или вызов LLM?Нет — дефолтный конвейер ранжирования (точное совпадение, BM25F, n-граммы, нечёткое и графовое сопоставление) работает полностью на локальных файлах и снимках репозитория; опциональная ветка эмбеддингов активируется только после того, как локальные A/B-данные докажут её пользу.
Куда на самом деле уходят память моего проекта и данные об использовании?События runtime-телеметрии записываются в игнорируемый Git локальный каталог и устаревают через тридцать дней, никогда не покидая машину; коммитится лишь анонимизированная сводка по дням без текстов запросов, путей к файлам или имён машин.
Что происходит, если OwnMem не уверен в достоверности записи памяти?Вместо того чтобы гадать, он передаёт запись как рекомендательную, помещает её в карантин или полностью воздерживается, действуя по своим фильтрам доказательности и риска действий, поэтому непроверенный контент никогда не влияет незаметно на действия агента.
Можно ли отменить неудачное автоматическое изменение памяти?Да — каждое автоматическое изменение снабжено проверенной обратной операцией, поэтому неудачное или вредное изменение восстанавливает точные предыдущие байты, не стирая историю правок.
Чем OwnMem отличается от других инструментов памяти агентов?Большинство систем памяти оптимизируют запоминание большего; OwnMem вместо этого пропускает каждую запись через проверки доказательности, риска и жизненного цикла, чтобы плохая память могла быть отклонена, отправлена в карантин или откачена, прежде чем она изменит поведение агента.
Может ли OwnMem использовать эмбеддинги или векторный поиск?Эмбеддинги — опциональная шестая ветка поиска, но они остаются с нулевым весом, пока локальное сравнение A/B не докажет, что они реально улучшают результаты на собственных данных репозитория.
What are similar projects?okf-agent-memory, jevmem, casbin-gateway, EverOS, agentmemory, headroom, billion-context, copperhead
Which topics is it in?llm-memory, ai-memory, bm25, gemini-cli, search, coding-agents, agent-memory, memory, git, cursor, local-first, coding-agent
Creator
grpcer
Size
2.6 MB
Stars
430
Updated
CommitOct 14Releasev0.8.2Oct 11
Age
2mo
Commits · 90 Days