{"_id":"@agent-stack2/memory","_rev":"2-071667eb752d7c484e7ab05c11c51d16","name":"@agent-stack2/memory","dist-tags":{"latest":"0.6.0"},"versions":{"0.5.0":{"name":"@agent-stack2/memory","version":"0.5.0","keywords":["agent-stack","agent-memory","mcp","coding-agents"],"author":{"name":"jsalvadorlpz"},"license":"MIT","_id":"@agent-stack2/memory@0.5.0","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"dist":{"shasum":"ac8f1c8be2f96f4f046be53b2f1b9092e33d92af","tarball":"https://registry.npmjs.org/@agent-stack2/memory/-/memory-0.5.0.tgz","fileCount":155,"integrity":"sha512-AdXhLUoloO/6sCzBTU01XKQSAsshGfLw3HFDV7RN0OOlu04/M4oak9paGwrUNLEirgnvoWt9ONWF29Kw+is/4g==","signatures":[{"sig":"MEYCIQCgX9l0a4krNlqCGKQS/i527+1Bc124ruR8ZtbYum0h1AIhAIirxv7REbj5MPr2RWWMgukHYfglv5uoxiiD23wialFj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":669400},"main":"./dist/index.js","_from":"file:agent-stack2-memory-0.5.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"_resolved":"/tmp/1230ba9ee25d3793a46202aa15e248de/agent-stack2-memory-0.5.0.tgz","_integrity":"sha512-AdXhLUoloO/6sCzBTU01XKQSAsshGfLw3HFDV7RN0OOlu04/M4oak9paGwrUNLEirgnvoWt9ONWF29Kw+is/4g==","repository":{"url":"git+https://github.com/jsalvadorlpz/agent-stack.git","type":"git","directory":"packages/memory"},"_npmVersion":"10.8.2","description":"Core schemas, storage, hierarchy, summarization, and context resolution","directories":{},"_nodeVersion":"20.20.1","dependencies":{"zod":"^3.22.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.4.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/memory_0.5.0_1774196690990_0.22054164750212135","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@agent-stack2/memory","version":"0.6.0","description":"Core schemas, storage, hierarchy, summarization, and context resolution","license":"MIT","author":{"name":"jsalvadorlpz"},"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/memory"},"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"keywords":["agent-stack","agent-memory","mcp","coding-agents"],"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"publishConfig":{"access":"public"},"dependencies":{"zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0","vitest":"^1.4.0"},"scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_id":"@agent-stack2/memory@0.6.0","_integrity":"sha512-m7dKlutSGD1Z4rNGLedHDKIMWHpJOHKy+zdu3sIOwvEguciSDVJpQw2oyHp85UCpRrhBcuUMOve2w8oVtwRiRA==","_resolved":"/tmp/053ade45f31bc1be77a7cdf675c94c11/agent-stack2-memory-0.6.0.tgz","_from":"file:agent-stack2-memory-0.6.0.tgz","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-m7dKlutSGD1Z4rNGLedHDKIMWHpJOHKy+zdu3sIOwvEguciSDVJpQw2oyHp85UCpRrhBcuUMOve2w8oVtwRiRA==","shasum":"9ab76ac69b89eb75af817897675591265b180c0c","tarball":"https://registry.npmjs.org/@agent-stack2/memory/-/memory-0.6.0.tgz","fileCount":167,"unpackedSize":752895,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGn/DMpOL8Fw86Rju4oPwgYelFZpuyX0MSzMA2P6RYOuAiEAr1ms4eWmQ8fJNe1t8w0Z5Ni17HWEUJNOL+rnREOi2pE="}]},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"directories":{},"maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory_0.6.0_1774460963018_0.6711459317794817"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T16:24:50.895Z","modified":"2026-03-25T17:49:23.423Z","0.5.0":"2026-03-22T16:24:51.194Z","0.6.0":"2026-03-25T17:49:23.236Z"},"bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"author":{"name":"jsalvadorlpz"},"license":"MIT","homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","keywords":["agent-stack","agent-memory","mcp","coding-agents"],"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/memory"},"description":"Core schemas, storage, hierarchy, summarization, and context resolution","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"readme":"# Agent Memory Kit\n\n[![CI](https://github.com/jsalvadorlpz/agent-memory-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/jsalvadorlpz/agent-memory-kit/actions/workflows/ci.yml)\n[![Python SDK CI](https://github.com/jsalvadorlpz/agent-memory-kit/actions/workflows/python-sdk-ci.yml/badge.svg)](https://github.com/jsalvadorlpz/agent-memory-kit/actions/workflows/python-sdk-ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Execution memory for coding agents — structured context that survives between sessions.**\n\nNo database. No embeddings. No cloud services.\nJust flat files, deterministic retrieval, and a session lifecycle that makes agents smarter over time.\n\n---\n\n## The 3-call session lifecycle\n\nEvery agent session is boot, work, finalize. Two memory calls total:\n\n```\nboot_context()                                         # auto-detect branch, recover everything\n  ... meaningful work ...\n  record_event(kind=\"decision\", message=\"Use RS256\")   # auto-resolve node from branch\nfinalize_node(summary=\"Auth done. Next: rate limiting.\")  # quality-checked, handoff generated\n```\n\nThe next session calls `boot_context()` and immediately knows what was done, decided, failed, and what should happen next. Memory compounds — each session makes the next one better.\n\n---\n\n## What it gives you\n\n| For agents | For developers | For teams |\n|---|---|---|\n| Instant context recovery on boot | See what agents did and decided | Quality scores on every close |\n| Zero-ID workflow via branch auto-detection | Handoff packs for seamless resumption | Stale/blocked item tracking |\n| Quality gates catch low-effort memory | TypeScript + Python SDKs | Multi-workspace isolation |\n| Continuity snapshots verify memory state | Visual workbench UI | Actor/audit trail |\n\n---\n\n## Quick start\n\n### From source\n\n```bash\ngit clone https://github.com/jsalvadorlpz/agent-memory-kit.git\ncd agent-memory-kit\npnpm install && pnpm build\npnpm eval\n# http://localhost:3457  (workbench + API)\n```\n\n### npm\n\n```bash\nnpm install -g @agent-memory/cli\nagent-memory serve\n```\n\n### Docker\n\n```bash\ndocker compose up -d\n```\n\n### Verify\n\n```bash\ncurl http://localhost:3457/health\n# {\"ok\":true,\"service\":\"agent-memory-api\",\"version\":\"0.5.0\"}\n```\n\n---\n\n## Claude Code / MCP setup\n\nAdd to `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agent-memory/mcp\"],\n      \"env\": { \"MEMORY_DIR\": \"/path/to/project/.agent-memory\" }\n    }\n  }\n}\n```\n\nFor shared backends, set `AGENT_MEMORY_URL`, `AGENT_MEMORY_TOKEN`, and `AGENT_MEMORY_WORKSPACE` instead. See **[Claude Code Integration Guide](docs/claude-code-integration.md)**.\n\n### MCP tools\n\n**Session lifecycle (primary workflow)**\n\n| Tool | Description |\n|------|-------------|\n| `boot_context` | **Session start.** Auto-detects git branch, resolves context, includes handoff. Returns `activeNodeId`, `memoryQuality`, `confidence`, `suggestedTask`, `validation`. |\n| `finalize_node` | **Session end.** Records summary, sets status, returns handoff + `continuity` + `qualityScore` + optional `validation` state. Validation persists across calls: omitting it preserves prior state; passing `validationStatus: 'unknown'` clears it. ID optional — auto-resolves from branch. |\n| `record_event` | Record a decision, test, failure. ID optional — auto-resolves from branch. Returns `_feedback` with event counts. |\n| `check_quality` | Memory quality check: score (0-100), level, actionable warnings. |\n\n**Node management:** `create_node`, `close_node`, `get_node`, `get_children`, `get_hierarchy`, `get_dashboard`, `search_related`, `resolve_context`, `get_handoff`\n\n**Aliases:** `create_feature`, `create_story`, `create_task`, `close_task`, `close_story`\n\n---\n\n## Example: 3-session lifecycle\n\n```\nSession 1: Fresh start\n  boot_context() -> no match -> suggestedTask with title/sourceRefs from branch\n  create_task(from suggestion)\n  record_event(kind=\"decision\", message=\"Use RS256 JWT\")\n  finalize_node(summary=\"JWT auth implemented. Next: rate limiting.\")\n  -> qualityScore: 85\n\nSession 2: Resume\n  boot_context() -> recovers task + handoff, memoryQuality: good\n  record_event(kind=\"failure\", message=\"Redis connection issue\")\n  finalize_node(summary=\"Rate limiting blocked by Redis.\", status=\"interrupted\")\n  -> continuity.blockerCount: 1\n\nSession 3: Finish\n  boot_context() -> recovers interrupted state + blockers\n  record_event(kind=\"test\", message=\"All 15 tests pass\")\n  finalize_node(summary=\"Auth complete. Ready for review.\")\n  -> qualityScore: 90\n```\n\n---\n\n## Quality gates\n\nEvery `finalize_node` and `close_node` returns a quality assessment:\n\n| Score | Level | What it means |\n|-------|-------|---------------|\n| 75-100 | `good` | Summary + decisions + events + sourceRefs |\n| 45-74 | `acceptable` | Some context but gaps |\n| 1-44 | `poor` | Very little for the next session |\n| 0 | `empty` | Nothing recorded |\n\nScoring factors: summary (25), summary depth (10), events (15), event depth (10), decisions (20), source refs (10), tags (5), parent link (5).\n\nSummary validation catches low-effort patterns (`\"done\"`, `\"fixed\"`) with actionable warnings. Never blocks, always warns.\n\n---\n\n## HTTP API\n\nBase URL: `http://localhost:3457`\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/boot` | Boot context (`?branch=`, `?nodeId=`, `?format=markdown`) |\n| POST | `/nodes/:id/finalize` | Finalize with summary |\n| POST | `/finalize` | Finalize by branch (`branchName` in body) |\n| GET | `/nodes/:id/quality` | Quality check |\n| POST | `/events` | Record event (returns `_feedback`) |\n| GET/POST | `/nodes` | List/create nodes |\n| POST | `/nodes/:id/close` | Close (returns `_quality`) |\n| GET | `/handoff/:id` | Handoff pack |\n| GET | `/dashboard` | Dashboard overview |\n| GET | `/context/resolve` | Context resolution |\n| GET | `/search?q=` | Search |\n\n```bash\n# Boot\ncurl \"http://localhost:3457/boot?branch=feature/AUTH-42\"\n\n# Record event\ncurl -X POST http://localhost:3457/events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"nodeId\":\"TASK-xxx\",\"kind\":\"decision\",\"message\":\"Use RS256\"}'\n\n# Finalize\ncurl -X POST http://localhost:3457/nodes/TASK-xxx/finalize \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"summary\":\"JWT auth done. Tests pass. Next: refresh tokens.\"}'\n\n# Quality check\ncurl http://localhost:3457/nodes/TASK-xxx/quality\n```\n\nAuth: set `API_TOKEN` env var. Add `API_AUTH_ALL=true` for read auth too.\n\n---\n\n## SDKs\n\n### TypeScript\n\n```bash\nnpm install @agent-memory/sdk\n```\n\n```typescript\nimport { AgentMemoryClient } from '@agent-memory/sdk';\nconst client = new AgentMemoryClient();\n\nconst boot = await client.bootContext({ branchName: 'feature/AUTH-42' });\nawait client.recordEvent({ nodeId: boot.activeNodeId!, kind: 'decision', message: 'Use RS256' });\nconst result = await client.finalizeNode(boot.activeNodeId, {\n  summary: 'JWT auth done. Tests pass.',\n});\nconsole.log(result.continuity.nextSessionCanRecover);\n```\n\n### Python\n\n```bash\npip install agent-memory-sdk\n```\n\n```python\nfrom agent_memory import AgentMemoryClient\n\nclient = AgentMemoryClient.from_env()\nboot = client.boot_context(branch_name=\"feature/AUTH-42\")\nclient.record_event(node_id=boot[\"activeNodeId\"], message=\"Use RS256\", kind=\"decision\")\nresult = client.finalize_node(\"JWT auth done.\", node_id=boot[\"activeNodeId\"])\n```\n\n---\n\n## Architecture\n\n```\npackages/\n  core/       Domain: schemas, storage, hierarchy, boot, finalize, quality\n  api/        HTTP API (Hono, port 3457)\n  mcp/        MCP server (stdio, local + HTTP proxy)\n  cli/        agent-memory CLI\n  sdk/        TypeScript SDK (zero deps)\n  adapters/   GitAdapter\n  workbench/  React workbench\npython/       Python SDK (zero deps)\n```\n\n**Storage:** flat files in `.agent-memory/` — JSON nodes, JSONL events, Markdown summaries.\n\n---\n\n## Tests\n\n```bash\npnpm test   # 511 tests, 27 suites\n```\n\n---\n\n## Evaluating for your team?\n\n- **[Overview](docs/design-partner/overview.md)** — what's real today\n- **[Pilot guide](docs/design-partner/pilot-guide.md)** — setup and trial scenarios\n- **[Demo script](docs/design-partner/demo-script.md)** — 5-10 minute walkthrough\n- **[FAQ](docs/design-partner/faq.md)** — honest answers\n\n---\n\n## Safety\n\nStores structured execution metadata only. **Do not store** credentials, PII, or secrets.\nAll data is local. See [`SECURITY.md`](SECURITY.md).\n\n---\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}