# OwnMem: memory that answers none, and says which gate refused > A git-native memory layer for coding agents where recall is a local function with no model call, delivery comes in three tiers including abstention, and the corpus is only allowed to shrink. **grpcer/ownmem** — Open-source, Git-native memory for AI coding agents — deterministic local recall for Claude Code, Codex, Cursor, Gemini CLI, and compatible tools. - Repository: https://github.com/grpcer/ownmem - Website: https://www.npmjs.com/package/ownmem - Stars: 422 · Forks: 7 - Language: JavaScript - License: Apache-2.0 - Published: 2026-09-17 · Updated: 2026-09-17 · Language: en - Canonical page: https://hysenlabs.com/projects/grpcer-ownmem ## Recall is a function, not a guess Default recall makes no model call and no network call, and the same query, config and snapshot produce the same ranking. That is the design decision everything else follows from, and it is why the npm package carries exactly two runtime dependencies, ajv for schema validation and yaml for parsing. A real run looks like a scored lookup rather than a generated paragraph: ```console $ npx ownmem recall -- "staging deploy timed out again, should I add more workers?" == staging deploy timed out again, should I add more workers? == staging_timeout_pool_cap [score=0.875 lanes=exact,bm25f,ngram fields=body,codePath,description,hooks,name,triggers] matched deploy,more,out,staging,staging deploy timed out,timed ``` Three retrieval lanes run and report, exact, bm25f and ngram, across the fields body, codePath, description, hooks, name and triggers. The score is a number you can reason about, not a similarity vibe. ## Three tiers, and the third one is a refusal Recall answers in one of three tiers: the memory quoted, up to three pointers to go and read, or an abstention that names the gate that refused. Trust is stated on the entry, not implied by it. In the run above the entry arrives as trust advisory authority and lifecycle advisory (not fully verified), with the instruction to treat it as a lead to re-check against the code, not as an established fact, because no review has confirmed it and it cites no authority document or code anchor. Content cannot declare itself trusted: independent receipts and live evidence checks decide delivery, and when evidence drifts the entry is downgraded and the change is named rather than quietly dropped. A memory system that is allowed to say none of them is the difference between this and a recall step that always produces something. ## A hard entry count that only ratchets down Net-zero growth is enforced rather than encouraged. The corpus has a hard entry count that only ratchets down, so adding to a full corpus means retiring something in the same change. That is a different relationship with a knowledge base than the usual append-only log, and it is the reason recall stays a local function: the index stays small enough that ranking it costs no model call. Scaffolding respects the same rule, since npx ownmem new staging_timeout_pool_cap creates one memory that already passes every gate. Memory lives as readable Markdown in .ownmem/, which is the property that makes it travel through clone, review and rollback with the code, and every agent in the repository reads the same source. ## Instruction files and built-in memory answer different questions OwnMem does not replace CLAUDE.md or AGENTS.md. Those files say how to work here and are read in full every turn; OwnMem answers a narrower question, which of the things this project learned the hard way are worth putting in front of the model for this task, and it is allowed to answer none of them. The three columns differ in every row. Who writes it: you by hand, the agent from your conversations, or you reviewed like code. Where it lives: one file in the repository, the vendor's account, or Markdown in your repository. What reaches the model: all of it every turn, whatever the vendor's own recall picked, or one of three tiers under a token budget. When an entry is wrong: you edit the file, you may never see the entry, or evidence drift downgrades it and names what moved. ## Hooks for two hosts, instructions or MCP for the rest Setup starts inside the repository that should own the memory and needs Node.js 20.6 or newer: ```bash npm install --save-dev ownmem npx ownmem init --hook --hosts claude,codex ``` The host list is recorded, so passing --hosts again is how a host is added or removed, and init creates .ownmem/ plus the host adapters, edits instruction files only inside managed blocks, and prints any one-time step a host still needs. --check previews the same command and --locale auto writes generated instructions in your system language. Recall then arrives differently per host: Claude Code gets a hook before every Edit and Write, Codex a hook before every patch it applies and needs three one-time trust steps, Grok CLI reads Claude Code's hook configuration through its compatibility layer and needs /hooks-trust once, and Cursor and Gemini CLI get an always-applied rule or the MCP server, which takes one manual step each. ## 0.6.0 hooks fire a failing command on every Bash call One upgrade warning is specific enough to be worth reading twice. Version 0.6.0 installed hooks whose subcommands no longer exist, so an installation that keeps them runs a failing command on every Bash call. The fix is ordered: npm install --save-dev ownmem@latest, then npx ownmem init --update before anything else. The update removes those hooks and never touches hooks you wrote yourself, and docs/UPDATING.md covers the rest, including the core.hooksPath cleanup that goes with them. Three releases landed inside September, v0.6.0 on 9 September, v0.7.0 on 22 September and v0.8.0 on 30 September 2026, and package.json carries 0.8.0 with the last push to main dated 1 October 2026. ## The MCP server exposes two tools and cannot write For hosts without hooks, ownmem mcp serves recall and read over stdio to any MCP host, and it exposes exactly two tools: recall and read. Neither can change a memory. The gate commands, audit, trust and compile, and every memory write stay outside that surface, which is why the MCP route is safe for Cursor and Gemini CLI while the hook route adds the per-edit trigger. The rest of the surface you drive yourself: ```bash npx ownmem new staging_timeout_pool_cap # scaffold one memory that already passes every gate npx ownmem report --since 7d # used? fast enough? right? what to do next npx ownmem dashboard --open # open the local console npx ownmem mcp # serve recall and read to any MCP host over stdio ``` The benchmark behind the claims is public too: npm run benchmark runs the locked CC0 corpus in the repository with 20 iterations, and npm run verify:release chains the two self-tests, a 100-iteration benchmark and a dry-run pack. The repository dogfoods itself, since .ownmem/ and .claude-plugin/ sit at the root next to bin/, commands/, schemas/, skills/ and docs/i18n/, which carries eight translated READMEs. ## Conclusion OwnMem fits a team that reviews its own repository and wants memory to travel through pull requests and rollbacks instead of living in a vendor account, since the entry cap only ratchets down and a full corpus forces a retirement in the same change. It does not fit someone who wants the agent to write memory unattended, or who needs a hosted answer: default recall makes no model call and no network call, so anything requiring interpretation has to happen elsewhere. Before you upgrade from 0.6.0, run npx ownmem init --update before anything else, because the hooks that version installed reference subcommands that no longer exist and otherwise fire a failing command on every Bash call. On a fresh setup, read the host table first, since Codex needs three one-time trust steps and Cursor and Gemini CLI each need a manual step for the MCP route. ## FAQ ### Does OwnMem call a model when it recalls a memory? No. Default recall makes no model call and no network call, so the same query, config and snapshot produce the same ranking. The package depends only on ajv and yaml at runtime. ### Can OwnMem say it does not know? Yes, and that is one of three delivery tiers. Recall returns the memory quoted, up to three pointers to go and read, or an abstention that names the gate which refused. ### What happens to my OwnMem installation when I upgrade from 0.6.0? Run npm install --save-dev ownmem@latest and then npx ownmem init --update before anything else. Version 0.6.0 installed hooks whose subcommands no longer exist, so without the update every Bash call runs a failing command; the update removes them and leaves hooks you wrote yourself alone. ### Which coding agents does OwnMem support? Claude Code, Codex, Grok CLI, Cursor and Gemini CLI. Claude Code and Codex get hooks, Grok CLI reads Claude Code's hook configuration through its compatibility layer, and Cursor and Gemini CLI use an always-applied rule or the MCP server, which takes one manual step. ### Can the MCP server change an OwnMem memory? No. The MCP server exposes exactly two tools, recall and read, and neither can change a memory. The gate commands audit, trust and compile, along with every memory write, stay outside the MCP surface. ## Sources - [grpcer/ownmem on GitHub](https://github.com/grpcer/ownmem) - [License: Apache-2.0](https://github.com/grpcer/ownmem/blob/main/LICENSE) - [Project website](https://www.npmjs.com/package/ownmem) - [README](https://github.com/grpcer/ownmem/blob/main/README.md) - [Releases](https://github.com/grpcer/ownmem/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grpcer-ownmem