\n\n**Your agent knows your code. It doesn't know your product.**\n\nMemory keeps the product graph of a codebase: features with their lifecycle\nstage, decisions with their reasons, gotchas, and open questions — anchored to\nthe code paths they describe. Agents query it on demand and keep it current as\nthe product changes.\n\nIf you run several projects with AI coding agents, you know the failure mode.\nYou come back to a repo after three weeks. Neither you nor the agent remembers\nwhat is shipped, what is half-done, why the queue lives in the worker, or what\nwas decided about storage. The agent can re-derive code structure cheaply; it\ncannot re-derive intent, stage, or rationale, because that knowledge is not in\nthe repo. So you re-explain, or the agent guesses.\n\nMemory stores that product layer as plain local files in `.memory/`: JSON\nsidecars with Markdown bodies, indexed with SQLite full-text search. No\nembeddings, no cloud account, no model API. Saved memory is reviewable in Git\nlike any other change. Code-graph tools map what is in the repo; Memory\ncaptures what isn't.\n\nThis repository publishes the npm package `@aictx/memory` and the Homebrew\nformula `aictx/tap/memory`. It ships the `memory` CLI and the optional\n`memory-mcp` server.\n\n## How It Works\n\n\n\n```text\ninit once -> query on demand -> save product changes -> sync at session end\n```\n\n1. **`memory init`** — once per repo. Creates `.memory/` storage, installs a\n short guidance block plus an auto-generated **product map** into `AGENTS.md`\n and `CLAUDE.md` (marker sections), starts the local viewer, and prints an\n **indexing brief**. Your coding agent follows the brief to build the initial\n graph: explore the repo, interview you for intent, stage, and decisions,\n then save everything in one call.\n2. **`memory query \"\"`** — on demand, mid-task. Returns a\n token-budgeted Markdown subgraph: full-text matches, their one-hop\n relations, and connected open questions. There is no per-task context\n loading; the only always-on context is the roughly one-screen product map.\n3. **`memory save --stdin`** — after product-meaningful changes. The input is\n intent JSON: `{task, nodes, stale, supersede, delete}`. The product map in\n `AGENTS.md`/`CLAUDE.md` refreshes automatically on every save.\n4. **`memory sync`** — at session end or after merging. Diff-driven: verifies\n anchors against the actual tree, reports nodes whose anchored code changed,\n orphaned anchors, and coverage gaps, then prints an agent prompt with a\n pre-filled save skeleton. Sync is mechanical — it never writes graph nodes\n itself.\n5. **`memory status`** — features by stage, open questions, stale anchors,\n last activity and sync. **`memory status --all`** is the cross-project\n dashboard: one row per registered project, for people running many repos\n with agents.\n\n### The product map\n\nThe map is the only thing agents carry into every session. It is generated,\ncapped at roughly one screen, and refreshed by `save` and `sync`:\n\n```markdown\n## Product map (generated — do not edit; refresh with memory save or memory sync)\nAcme Render — Self-hosted PDF render service for invoice pipelines.\n\n**Building:** webhook-retry-queue — Failed Stripe webhooks re-enter a worker-owned retry queue. — services/billing/src/webhooks/\n**Shipped:** pdf-render-api — Renders invoice templates to PDF over HTTP. — services/render/ · template-editor — In-browser template editing with live preview. — apps/editor/\n**Paused:** batch-exports — Nightly bulk export of rendered documents. — services/exports/\n\n**Recent decisions:** retries-run-in-worker — Webhook retries run in the queue worker · sqlite-over-postgres — SQLite for single-node deployments\n\n**Open questions:** pdf-storage-location — Where do rendered PDFs live long-term?\n```\n\nEverything deeper is pull, not push: `memory query` when the agent needs it.\n\n## Get Started Quickly\n\nMemory requires Node.js `>=22`. The Homebrew formula installs Node through\nHomebrew; npm installs require a compatible Node already on `PATH`. Core\ncommands run locally; no cloud account, model API, embeddings, or hosted sync\nare required.\n\n```bash\n# macOS/Linux with Homebrew\nbrew install aictx/tap/memory\n\n# or npm\nnpm install -g @aictx/memory\n\ncd path/to/your/repo\nmemory init\n```\n\n`memory init` creates local storage, installs the guidance block and product\nmap sections, starts the viewer, and prints the indexing brief for your agent.\nUse `memory init --no-view` to skip the viewer, `memory init --dry-run` to\npreview, or `memory init --brief` to reprint the brief later.\n\nMemory writes local files and never commits automatically.\n\n## Ask an Agent to Activate It\n\nPaste this into Claude Code, Codex, OpenCode, Cursor, Cline, or another\nCLI-capable coding agent from the project root:\n\n```text\nSet up Memory for this repository.\n\nInstall Memory with one of:\nbrew install aictx/tap/memory\nnpm install -g @aictx/memory\n\nThen run from the project root:\nmemory init\n\nFollow the printed indexing brief: explore the repo, draft the product graph\n(features with stage and anchors, decisions with their reasons, gotchas, open\nquestions), interview me for what the repo cannot tell you, and save it all in\none `memory save --stdin` call.\n\nWhen this is done, report:\n- what the product map in AGENTS.md/CLAUDE.md now shows\n- what `memory status` reports\n- how I can inspect the graph with `memory view`\n```\n\nAfter the initial graph exists, the ongoing loop is small:\n\n```bash\nmemory query \"why do webhook retries run in the worker?\"\n# do the work\nmemory save --stdin\nmemory sync # at session end\n```\n\n## What Gets Stored\n\nFive kinds of node, four relation predicates.\n\n| Kind | What it holds |\n| --- | --- |\n| `project` | One per repo: what this product is. Created by `init`, described with `save` (`kind: \"project\"`), feeds the map header. |\n| `feature` | What the product does for users. Carries a `stage` (`idea`, `building`, `shipped`, `paused`, `dead`) and `anchors` — repo-relative path globs linking it to code. |\n| `decision` | A choice and the reason it was made. |\n| `gotcha` | A known trap or failure mode. |\n| `question` | An open product or technical question that affects future work. |\n\nNodes connect through `affects`, `depends_on`, `supersedes`, and `related_to`\nrelations. Anchors are what make staleness mechanical: when anchored files\nchange or disappear, `sync` and `status` report exactly which nodes need\nre-verification.\n\nWhat this buys you, concretely:\n\n- Pick any project back up cold — the map and graph carry what is shipped,\n half-done, and why.\n- Agent answers grounded in product reality instead of guesses from code.\n- Decisions that survive sessions, branches, and agent switches.\n- Mechanical staleness detection through anchors, not vibes.\n- Memory you can review, diff, and fix in Git.\n\n## The Sync Ritual\n\n`memory sync` is how the graph stays honest without re-reading the repo:\n\n```bash\nmemory sync\n```\n\nIt diffs the tree since the last sync marker (`.memory/sync-state.json`),\nchecks every anchor against the current files, and reports four things: nodes\nwhose anchored code changed, nodes whose anchors match nothing anymore, nodes\nwith no anchors, and directories with real code but no feature coverage. When\nsomething needs attention it prints an agent prompt with a pre-filled\n`memory save --stdin` skeleton, so reconciliation is one save call. Run it at\nsession end or after merging others' work. `--dry-run` reports without\nadvancing the marker.\n\n## Inspect the Graph\n\n
\n \n \n \n \n The local viewer: projects dashboard, memory list, node detail, and the relation graph.\n
\n\n`memory view` starts a local browser viewer bound to `127.0.0.1`: a projects\ndashboard, the memory list, node detail, and an interactive relation graph.\n`memory inspect ` does the same for one node in the terminal, and\n`memory diff` shows tracked and untracked `.memory/` changes.\n\n## Works With Your Agent\n\n| Agent or client | Fastest path |\n| --- | --- |\n| Claude Code | `memory init` writes the guidance block and product map into `CLAUDE.md`. |\n| Codex | `memory init` writes `AGENTS.md`; use the CLI loop by default. |\n| OpenCode | Uses the root `AGENTS.md` guidance created by init. |\n| Cursor | Copy `integrations/cursor/memory.mdc` into `.cursor/rules/memory.mdc`, then run init. |\n| Cline | Copy `integrations/cline/memory.md` into `.clinerules/memory.md`, then run init. |\n| MCP-capable clients | Start with the CLI; configure `memory-mcp` for `query_memory`, `save_memory`, `status_memory`, and `inspect_memory` tools. |\n\nCodex users can add this repo's plugin marketplace with one command:\n\n```bash\ncodex plugin marketplace add aictx/memory\n```\n\nClaude Code users can add the marketplace and install the plugin from inside\nClaude Code:\n\n```text\n/plugin marketplace add aictx/memory\n/plugin install memory@aictx\n```\n\nFor official listing paths and release prep, see\n[Publishing agent plugins](https://docs.aictx.dev/plugin-publishing/).\n\n## Project Status and Upgrade Recovery\n\nMemory is pre-1.0. Breaking changes should be expected across package versions\nwhile the schema and local storage format are still evolving. There is no\nstorage migration: when a new version rejects existing `.memory/` storage,\nreset and re-index from the project root:\n\n```bash\nmemory reset\nmemory init\n```\n\n`memory reset` creates a backup archive under `.memory/.backup/` before\nclearing local storage. To rebuild the graph afterwards, ask your coding agent:\n\n```text\nMemory was reset after a package upgrade. Run `memory init` and follow the\nindexing brief to rebuild the product graph. Inspect the newest archive in\n.memory/.backup/ for prior features, decisions, gotchas, and open questions,\nand re-save only what is still true in one `memory save --stdin` call. Do not\ncopy old storage files back; validate the result with `memory check`.\n```\n\n## Documentation\n\n- [Getting started](https://docs.aictx.dev/getting-started/)\n- [Mental model](https://docs.aictx.dev/mental-model/)\n- [Capabilities](https://docs.aictx.dev/capabilities/)\n- [CLI reference](https://docs.aictx.dev/cli/)\n- [MCP](https://docs.aictx.dev/mcp/)\n- [Agent integration](https://docs.aictx.dev/agent-integration/)\n- [Reference](https://docs.aictx.dev/reference/)\n\n## Contribute\n\nMemory is MIT-licensed and built in the open. Issues, docs fixes, examples,\nand pull requests are welcome.\n\n[Contribute on GitHub](https://github.com/aictx/memory/blob/main/CONTRIBUTING.md)\n\n## Project identity\n\nMemory by Aictx keeps the product graph of a codebase for AI coding agents:\nfeatures with stage and code anchors, decisions with their reasons, gotchas,\nand open questions, stored as reviewable local files. It is distributed\nthrough the open source npm package `@aictx/memory` and the Homebrew formula\n`aictx/tap/memory`, then runs through the `memory` CLI and optional\n`memory-mcp` server.\n","readmeFilename":"README.md"}
![\"Website\"](\"https://img.shields.io/badge/website-memory.aictx.dev-111214?style=for-the-badge\"){kind=icon}
\n ![\"Docs\"](\"https://img.shields.io/badge/docs-read-111214?style=for-the-badge\"){kind=icon}
\n ![\"Live](\"https://img.shields.io/badge/demo-viewer-111214?style=for-the-badge\"){kind=icon}
\n![\"CI\"](\"https://github.com/aictx/memory/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"CodeQL\"](\"https://github.com/aictx/memory/actions/workflows/codeql.yml/badge.svg\"){kind=icon}
\n ![\"npm\"](\"https://img.shields.io/npm/v/@aictx/memory\")
![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n