{"_id":"@agent-connect/memory","_rev":"4-f63c7a6c2232d0e93927a5da286f1004","name":"@agent-connect/memory","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@agent-connect/memory","version":"0.1.0","keywords":["agent","developer-tools","documentation","knowledge-base","project-memory","scaffolding"],"license":"MIT","_id":"@agent-connect/memory@0.1.0","maintainers":[{"name":"xiasenhai","email":"xiasenhai@outlook.com"}],"bin":{"agent-memory":"dist/cli.js"},"dist":{"shasum":"c4c5cea55c5f59a7c0b53bb12c89a5ac724cc43a","tarball":"https://registry.npmjs.org/@agent-connect/memory/-/memory-0.1.0.tgz","fileCount":20,"integrity":"sha512-fBaZelymUDmROLNd1fFPNDtsx0KUm/HKHyKaUUGIbeQNIclNSxbhU/16Y9RIQvaDje2bzIowsukMUmKYTZooDg==","signatures":[{"sig":"MEYCIQDdFkcwEI3nrzkmn8RhP1E5FTPUK4+aT9tzmBSYiYy4IgIhANeWq6av/zeEHB98VcTQXcRcK3LNkwTBFtclpicmFwgz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78077},"engines":{"node":">=18"},"gitHead":"5aa2c4e6a206b55745a7b9a35af9040a9ebcab2b","scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepack":"npm run build"},"_npmUser":{"name":"xiasenhai","email":"xiasenhai@outlook.com"},"_npmVersion":"11.9.0","description":"Bootstrap durable project memory for developers and coding agents.","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^24.7.2"},"_npmOperationalInternal":{"tmp":"tmp/memory_0.1.0_1774515327177_0.4673715441545896","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-connect/memory","version":"0.1.1","keywords":["agent","developer-tools","documentation","knowledge-base","project-memory","scaffolding"],"license":"MIT","_id":"@agent-connect/memory@0.1.1","maintainers":[{"name":"xiasenhai","email":"xiasenhai@outlook.com"}],"bin":{"agent-memory":"dist/cli.js"},"dist":{"shasum":"3f5f08eb435b98ee9e77862acc778a8acc8ffd35","tarball":"https://registry.npmjs.org/@agent-connect/memory/-/memory-0.1.1.tgz","fileCount":20,"integrity":"sha512-uStPjjx8eNR0FkZ5RpMTYqXngObwYUVKEoMG8NXpN4fPT/Wa1SrKzqu05qsP6vv6kKPQuP9Oh/6x1BPDckSsnA==","signatures":[{"sig":"MEUCIEaX6elIziEzGnzsWyQZ4BIN6GAet0/FX0WvbeGbSOFoAiEAi3bOfCaLxiY4Jy/z8deVqwksDITKCZfU2zZ5ERlmgco=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78099},"engines":{"node":">=18"},"gitHead":"5aa2c4e6a206b55745a7b9a35af9040a9ebcab2b","scripts":{"build":"tsc -p tsconfig.json && chmod +x dist/cli.js","clean":"rm -rf dist","prepack":"npm run build"},"_npmUser":{"name":"xiasenhai","email":"xiasenhai@outlook.com"},"_npmVersion":"11.9.0","description":"Bootstrap durable project memory for developers and coding agents.","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^24.7.2"},"_npmOperationalInternal":{"tmp":"tmp/memory_0.1.1_1774515666667_0.7503196295213825","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@agent-connect/memory","version":"0.2.1","keywords":["agent","developer-tools","documentation","knowledge-base","project-memory","scaffolding"],"license":"MIT","_id":"@agent-connect/memory@0.2.1","maintainers":[{"name":"xiasenhai","email":"xiasenhai@outlook.com"}],"bin":{"agent-memory":"dist/cli.js"},"dist":{"shasum":"8e248693378e4eeb0a3da4fdd445b6af45e82f06","tarball":"https://registry.npmjs.org/@agent-connect/memory/-/memory-0.2.1.tgz","fileCount":22,"integrity":"sha512-cIF+C/FTw/pqH87nB+uNdb17V4BpmbyOubryKwuYih/EJN6FwPRDrrzxG8qFWezgn7uWDV/h+VhyBOtt9lQwxg==","signatures":[{"sig":"MEYCIQDpPzkcQ0m5n/fdh+xPVWn9oqLWttZ274bgDdQ9dOv6RQIhAOqmFBkxmYy8QyV6WOsgPis+qAhe8tE8NKHXkyHDktGS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96090},"engines":{"node":">=18"},"gitHead":"3fea583d3e87c95fb79e9be8d14babbd25c4a55c","scripts":{"test":"npm run build && node --test test/*.test.js","build":"npm run clean && tsc -p tsconfig.json && chmod +x dist/cli.js","clean":"rm -rf dist","prepack":"npm run build"},"_npmUser":{"name":"xiasenhai","email":"xiasenhai@outlook.com"},"_npmVersion":"11.9.0","description":"Bootstrap durable project memory for developers and coding agents.","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^24.7.2"},"_npmOperationalInternal":{"tmp":"tmp/memory_0.2.1_1774574515284_0.5191606281855428","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@agent-connect/memory","version":"0.3.0","description":"Bootstrap durable project memory for developers and coding agents.","license":"MIT","publishConfig":{"access":"public"},"bin":{"agent-memory":"dist/cli.js"},"scripts":{"build":"npm run clean && tsc -p tsconfig.json && chmod +x dist/cli.js","clean":"rm -rf dist","dogfood:init":"node scripts/dogfood/init.mjs","dogfood:exercise":"node scripts/dogfood/exercise.mjs","dogfood:repair":"node scripts/dogfood/repair.mjs","dogfood:status":"node scripts/dogfood/status.mjs","prepack":"npm run build","test":"npm run build && node --test test/*.test.js"},"engines":{"node":">=18"},"keywords":["agent","developer-tools","documentation","knowledge-base","project-memory","scaffolding"],"devDependencies":{"@types/node":"^24.7.2","typescript":"^5.9.3"},"gitHead":"b2a554ff78d920c76be2d5850558dd55a611a6e4","_id":"@agent-connect/memory@0.3.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-NmBm6+4mURkszX3OKnG+DHRKW6h2+outYf3Z1zqHAo+9qHGYgSxeP5EUfDCrB+A3Ey5VfquEn5B5P8+JsQ32kg==","shasum":"345ac505faa347039224a793ca5521d9486eefee","tarball":"https://registry.npmjs.org/@agent-connect/memory/-/memory-0.3.0.tgz","fileCount":48,"unpackedSize":378517,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH3CxtPAqEWEZkDZ63JLA/bFyFicEY9xxWCcDr01DYFxAiArrsIhcQyV80x4SwvT0j0eUTK0YrVJUCMwkUc6CtYcbA=="}]},"_npmUser":{"name":"xiasenhai","email":"xiasenhai@outlook.com"},"directories":{},"maintainers":[{"name":"xiasenhai","email":"xiasenhai@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory_0.3.0_1774860433561_0.6827423757795039"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-26T08:55:27.068Z","modified":"2026-03-30T08:47:14.160Z","0.1.0":"2026-03-26T08:55:27.317Z","0.1.1":"2026-03-26T09:01:06.816Z","0.2.1":"2026-03-27T01:21:55.437Z","0.3.0":"2026-03-30T08:47:13.712Z"},"license":"MIT","keywords":["agent","developer-tools","documentation","knowledge-base","project-memory","scaffolding"],"description":"Bootstrap durable project memory for developers and coding agents.","maintainers":[{"name":"xiasenhai","email":"xiasenhai@outlook.com"}],"readme":"# agent-memory\n\n<!-- agent-memory:entry version=3 bundleHash=064a82ecbc8b63ca97d01824fdb45f860aa0481cd2ebf8e1bdd8e392cd4c29d8 start -->\n## Project Memory\n\nThis repository keeps canonical project memory in `.agent-memory/state.json`.\n\nHistory and checkpoints live in `.agent-memory/history/`.\n\nReadable projections live in `docs/agent-memory/`.\n\nRecommended reading order:\n1. `docs/agent-memory/README.md`\n2. `docs/agent-memory/project-map.md`\n3. `docs/agent-memory/current-focus.md`\n4. `docs/agent-memory/gotchas.md` when debugging gets noisy or surprising\n5. `docs/agent-memory/next-steps.md` when you need a clean starting point\n\nUse `npx agent-memory sync`, `npx agent-memory recall`, and `npx agent-memory query` to maintain and retrieve project memory.\n<!-- agent-memory:entry end -->\n\n[![npm version](https://img.shields.io/npm/v/%40agent-connect%2Fmemory)](https://www.npmjs.com/package/@agent-connect/memory)\n[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n[![node >=18](https://img.shields.io/badge/node-%3E%3D18-417e38)](./package.json)\n\nDurable project memory with history, recall, and query.\n\n`agent-memory` is now a full memory system for repositories:\n\n- it stores the current canonical memory in `/.agent-memory/state.json`\n- it records durable history in `/.agent-memory/history/`\n- it supports configurable recall policies in `/.agent-memory/config.json`\n- it projects the current memory into `docs/agent-memory/`\n- it lets you consolidate memory with `recall`\n- it lets you retrieve memory with `query`\n- it lets you inspect backlog and checkpoint drift with `status`\n- it can automate import-sync and recall with `automate`\n- it can integrate Claude Code and Codex with `integrate`\n\n## Why This Exists\n\nRepositories keep losing the same expensive context:\n\n- architectural boundaries live across code, manifests, and half-finished docs\n- current state gets trapped in chats and PR threads\n- repeated gotchas are rediscovered instead of remembered\n- long-lived projects need both memory maintenance and memory retrieval\n\n`agent-memory` turns that into a structured repository memory system instead of a pile of static notes.\n\n## Core Model\n\nThe system now has four persistent layers:\n\n- `/.agent-memory/state.json`\n  Current canonical memory bundle\n- `/.agent-memory/history/events.jsonl`\n  Append-only history of tool runs and imported sessions\n- `/.agent-memory/history/checkpoints/`\n  Bundle checkpoints written after `init`, `update`, and `recall`\n- `/.agent-memory/sources.json`\n  Registered external history sources\n- `/.agent-memory/config.json`\n  Recall defaults, policy, and backlog thresholds\n\nReadable projections still live in:\n\n- `docs/agent-memory/README.md`\n- `docs/agent-memory/project-map.md`\n- `docs/agent-memory/current-focus.md`\n- `docs/agent-memory/gotchas.md`\n- `docs/agent-memory/next-steps.md`\n\nAn entry block is also written into the preferred top-level entry file.\n\n## How It Works\n\n`agent-memory` no longer treats markdown files as the source of truth.\n\nInstead, it:\n\n1. collects repository context\n2. builds or refreshes a canonical bundle\n3. appends durable history events and checkpoints\n4. projects the active bundle into repository docs\n5. lets you consolidate history back into memory with `recall`\n6. lets you ask memory questions with `query`\n7. lets you inspect backlog and checkpoint drift with `status`\n8. can run local automation for import-sync and recall with `automate`\n9. can integrate chat clients and MCP tooling with `integrate`\n\nIf you need to control the runtime used for synthesis, use `--provider=auto|codex|claude`.\n\n## Commands\n\n### Bootstrap memory\n\n```bash\nnpx agent-memory init\n```\n\nCreates a fresh canonical state, resets the history scaffold, writes the first checkpoint, and projects the bundle into docs.\n\n### Refresh current memory\n\n```bash\nnpx agent-memory update\n```\n\nRefreshes the active canonical bundle from current repository evidence and writes a new checkpoint plus tool-run event.\n\n### Consolidate memory\n\n```bash\nnpx agent-memory recall\n```\n\nReads unrecalled history, proposes a consolidated bundle, shows summary changes and file diffs, and applies only after confirmation.\nThe preview also includes a grouped unrecalled history summary before apply.\n\nIf no unrecalled events produced durable changes, `recall` exits with a clear no-op message and does not write a checkpoint or tool-run event.\n\n- `--section=...` to limit consolidation to part of the bundle\n- `--policy=...` to apply policy presets such as imports-only or project-map protection\n- `--show-diff` to expand from summary-first preview into file-level diffs\n\n### Query memory\n\n```bash\nnpx agent-memory query \"how does caching work?\"\n```\n\nReturns a short answer plus citations from bundle sections, history events, and checkpoints. Natural-language structured questions such as `what changed recently?`, `what should I do next?`, and `what are the known traps?` are supported through the same command.\n\nIf current memory cannot support a confident answer, `query` now returns an explicit evidence-insufficient response instead of bluffing.\n\nFor agent-facing automation you can request JSON output:\n\n```bash\nnpx agent-memory query \"what changed recently?\" --output=json\n```\n\nBundle citations can also be cross-linked to the generated projection docs under `docs/agent-memory/`.\nProjects can override retrieval instructions per query mode through `.agent-memory/config.json`.\n\n### Add external session sources\n\n```bash\nnpx agent-memory add claude-local ~/.claude --name claude\n```\n\nRegisters an external session source.\n\n### Sync external session sources\n\n```bash\nnpx agent-memory sync --all\n```\n\nNormalizes external sessions into durable history events.\n\n`sync` may partially succeed:\n\n- imported sessions become history events\n- duplicate sessions are skipped\n- broken session files are reported as failures without aborting the whole source\n\nEach source also records sync status, last imported count, and the last sync error when applicable.\n\n### Inspect memory status\n\n```bash\nnpx agent-memory status\n```\n\nShows:\n\n- state and latest checkpoint id\n- unrecalled backlog counts plus a grouped summary of unrecalled history\n- source sync health\n- checkpoint drift summary\n- retention and archive summary\n- the next suggested action\n\n### Local automation daemon\n\n```bash\nnpx agent-memory automate start\nnpx agent-memory automate status\nnpx agent-memory automate run-once\nnpx agent-memory automate stop\n```\n\nThe first Phase 4 milestone is a local built-in automation daemon.\n\n- it runs as a repo-local background process\n- it can run `sync --all` and `recall --yes` on a schedule\n- it writes runtime state under `.agent-memory/automation/`\n- it records the latest machine-readable run result in `.agent-memory/automation/latest-run.json`\n- it applies retention pruning by default and archives aged history/checkpoints under `.agent-memory/archive/`\n- it uses aggressive auto-apply recall by default\n- dirty worktrees do not block automation cycles in this first version\n\nRetention behavior in this first policy-controls milestone:\n\n- retention is enabled by default\n- pruning only happens inside automation cycles\n- pruning is archive-first, not direct hard delete\n- archived batches later expire automatically from `.agent-memory/archive/`\n- archived data does not participate in active `query`, `recall`, or `status` baselines\n\n### Integrate Claude Code + Codex\n\n```bash\nnpx agent-memory integrate\nnpx agent-memory integrate --dry-run\nnpx agent-memory integrate --status\nnpx agent-memory integrate --status --output=json\nnpx agent-memory integrate --repair\n```\n\nThis command is separate from `init`.\n\n- `init` stays repo-local and never edits global chat tooling config\n- `integrate` writes Claude Code project files\n- `integrate` also registers Codex MCP globally with a safe merge\n\nInstall UX notes:\n\n- `--dry-run` previews project/user changes without writing files\n- `--status` is read-only and summarizes Claude/Codex integration health\n- `--status --output=json` returns machine-readable integration status\n- `--repair` only repairs managed mismatches; it does not create missing components\n- `--dry-run` and `--status` never write project files or global Codex config\n- normal `integrate` may write user-scope Codex config when Codex integration is selected\n\nGenerated/updated files include:\n\n- `.mcp.json`\n- `.claude/settings.json`\n- `.claude/skills/agent-memory/SKILL.md`\n- `AGENTS.md`\n- `~/.codex/config.toml`\n\nClaude Code integration uses project MCP + project skills + SessionStart and Stop hooks.\nCodex integration uses MCP + `AGENTS.md` + the local daemon.\n\nThe generated Claude skill and Codex guidance now prefer the higher-level MCP workflow tools:\n\n- `memory_assess` for a quick health and readiness check\n- `memory_compact_handoff` before compact or session handoff\n- `memory_maintain` for a one-shot maintenance pass\n- lower-level tools such as `memory_query`, `memory_status`, `memory_validate`, and `automation_*` only when finer control is needed\n\n### MCP server\n\n```bash\nnpx agent-memory mcp\n```\n\nThis starts the local stdio MCP server used by Claude Code and Codex integrations.\n\nThe MCP server exposes:\n\n- high-level workflow tools: `memory_assess`, `memory_compact_handoff`, `memory_maintain`\n- lower-level retrieval and health tools: `memory_query`, `memory_status`, `memory_validate`\n- automation controls: `automation_status`, `automation_ensure_running`, `automation_run_once`\n\n### Ensure automation is running\n\n```bash\nnpx agent-memory automate ensure-running\n```\n\nThis is the lightweight startup command used by Claude Code `SessionStart` hooks and can also be called directly.\n\n### Self-host dogfood\n\nThis repository can also exercise itself as a long-lived dogfood arena.\n\n```bash\nnpm run dogfood:init\nnpm run dogfood:exercise\nnpm run dogfood:repair\nnpm run dogfood:status\n```\n\nOptional provider override:\n\n```bash\nAGENT_MEMORY_DOGFOOD_PROVIDER=claude npm run dogfood:init\n```\n\nCurrent dogfood behavior:\n\n- repo-root `.agent-memory/`, `docs/agent-memory/`, `.mcp.json`, `.claude/`, and `AGENTS.md` form the stable self-host baseline\n- `exercise` runs in an isolated git worktree under `temp/dogfood/worktree`\n- dogfood now inherits your real `HOME` by default, so Codex and Claude use the same user-level auth/config they would during normal local work\n- tests and other isolated runs can still override `HOME` explicitly when they need a sandbox\n- dogfood structured runs now do a real provider preflight instead of trusting `--version` alone, so `auto` can fall back when one backend is installed but not authenticated\n- reports are written under `temp/dogfood/reports/`\n- `repair` first does deterministic maintenance/integration repair, then can escalate to whole-repo provider-driven repair if source-level breakage remains\n- successful repair only applies a patch back to the root worktree; it does not auto-commit or auto-push\n\n### Audit health\n\n```bash\nnpx agent-memory validate\n```\n\nAudits state integrity, history continuity, checkpoint presence, projection alignment, entry wiring, and recall backlog health.\nIt also inspects retention config plus archive batch health under `.agent-memory/archive/`.\n\n## Troubleshooting\n\nCommon cases:\n\n- `sync` reports `failed=...`\n  The source is still registered, but one or more session files could not be parsed or normalized. Run `agent-memory validate` to see whether this is now a warning condition.\n- `recall` says `Nothing to recall`\n  Either there are no unrecalled events for the selected scope, or consolidation produced no durable bundle changes.\n- `status` suggests `recall`\n  The backlog is above the configured threshold or the checkpoint drift summary suggests stale active memory.\n- `query` says there is not enough evidence\n  The current bundle, history, and checkpoints do not support a confident answer yet. Import more history or run `recall` before asking again.\n- `validate` warns about recall backlog\n  New history has accumulated and should be consolidated with `agent-memory recall`.\n\n## Breaking Change\n\nThis is a destructive model change.\n\n- old `state.json` formats are not supported\n- old projection markers are not supported\n- there is no migration path\n- old repositories must rerun `npx agent-memory init`\n\n## Learn More\n\n- [Overview](./docs/overview.md)\n- [Commands](./docs/commands.md)\n- [File Model](./docs/file-model.md)\n- [V1 Boundary And Roadmap](./docs/roadmap.md)\n- [Adoption Guide](./docs/adoption.md)\n- [Contributing](./CONTRIBUTING.md)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}