{"_id":"@alphaone/ai-memory","_rev":"9-f379b0512ddccbdca5d6ef17a3182517","name":"@alphaone/ai-memory","dist-tags":{"latest":"0.10.0"},"versions":{"0.6.4":{"name":"@alphaone/ai-memory","version":"0.6.4","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.6.4","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaone/ai-memory","bugs":{"url":"https://github.com/alphaone/ai-memory/issues"},"dist":{"shasum":"a20fb4dcdfe6f80bfd8170038069b5eb9be74a92","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.6.4.tgz","fileCount":26,"integrity":"sha512-T2EzZYF6wz7ZHfFL2Nx5cAbeTaRMYhocUy5vm8UCd4LFZ4dF3mId9BD/do/9oKmCZj1qxXx4Cjjl1BgYC25Meg==","signatures":[{"sig":"MEUCIQCdP9bs5TRZVfwu+UszRs7kTSr5Sx9srzxPFWG3Z4SNDgIgHNXRW/WuDxp4LXrlKSgppkpCI0aaZ/YpoQxtXXwcItM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":92624},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"f78b306795031bac40023ec169a76ba3c255ba21","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaone/ai-memory.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.9.7","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.6.4_1777987762597_0.714755911204422","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@alphaone/ai-memory","version":"0.7.0","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.7.0","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"dist":{"shasum":"c9b84fd48cbb3c1c475eb12065f199dc8cc6ef9f","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.7.0.tgz","fileCount":26,"integrity":"sha512-xx8EDI1dOqCn/Ce5PAUGun4wVEQaCCqUijdO8UhkPOt4bWVDDXC8vxUurlPa5NmfF0+LAfXFSAF/cO8S1bX4og==","signatures":[{"sig":"MEUCIQC/WeISZmNXzGpJZu9xEZlXL128VXsShThUzCXcn86NrgIgMSQojdcC2pXDHcvyw9pVAfNqq1w0kXTCVQIbCX+YWIE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":92749},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"101df73d97e9c9cfcc51c633f95f578049365022","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.7.0_1781395160557_0.01772960568355586","host":"s3://npm-registry-packages-npm-production"}},"0.7.1":{"name":"@alphaone/ai-memory","version":"0.7.1","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.7.1","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"dist":{"shasum":"c4cc7ebe9d6ec84dc788f4d6938cc9c12d86bf62","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.7.1.tgz","fileCount":26,"integrity":"sha512-JoQOxkD4a1UJYMSFHY27lRVIrLSPOv+kxdoxyPDof8ApRpgOTqljvpDa1s3EKyYYaUJZJpakRAih3wKZeNaHCg==","signatures":[{"sig":"MEQCIFINxsDRLJYTHsnBClTU4YycP8Y2H1gfO7qrzBnvwUSvAiB9Afgf6rauyo9MPjqEhcpj4l6qAaehrkqCukj4dvU73w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.7.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":92749},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"d350e0bc0a8d54ef4cdd90db2327daa5624a4663","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.7.1_1781547409847_0.06731129839265271","host":"s3://npm-registry-packages-npm-production"}},"0.8.0":{"name":"@alphaone/ai-memory","version":"0.8.0","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.8.0","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"dist":{"shasum":"4ac8424ebf980adffbd48cd9b56c27c38eca0404","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.8.0.tgz","fileCount":26,"integrity":"sha512-PNgzHFn6rTVSCxk8jKimT6lbZs0rwBZqzxu1zfRQWJ0Hs8TCjKt2X+MmmsVUoA9+AjJlDmHs0/9dBPd7yla8/A==","signatures":[{"sig":"MEYCIQD1LhZgGrGM0tfEYbAunJh03LSIZwWVgXyIrgGFaNDSXAIhANYdw1QMTKGFiKZ4ofAy5ozeS/RdgturwYApQjPzXpmG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.8.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":92749},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"fd68550d1c98d15d747aa41efa2531f374da6aba","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.8.0_1782430566644_0.1816430708767045","host":"s3://npm-registry-packages-npm-production"}},"0.8.1":{"name":"@alphaone/ai-memory","version":"0.8.1","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.8.1","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"dist":{"shasum":"8d78c13b6ff880e5dd28886c43dc568c83d2d43d","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.8.1.tgz","fileCount":26,"integrity":"sha512-qYOlwrgiYKOqgEuNhz59N5EFLvikHrdFHMsfynEaOWdzbvpj0GwC/K5LnphGfw9PjpmSrFA9wng2djjsx3L8lg==","signatures":[{"sig":"MEQCIAveHBpPvpP2LKVvG9ozzJfs9fu/KTfnQ7/RgooOzECGAiAIBJ1y2VangjIML13s2jcc3FHJl/y8Z7sr8C5Xsl3q3w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.8.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":92749},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"08f4e2500eb1eb865c6c8960df9e57783b23c506","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.8.1_1782760548009_0.4496523168818185","host":"s3://npm-registry-packages-npm-production"}},"0.9.1":{"name":"@alphaone/ai-memory","version":"0.9.1","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","_id":"@alphaone/ai-memory@0.9.1","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"dist":{"shasum":"47307384106971422203c8419d8021b9f0a3b859","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.9.1.tgz","fileCount":26,"integrity":"sha512-xhKRIbe6XImMaO5okpGYH06box/2gSX+a2d3tYoUbLTl3BnyeS4EUBRVyXPvCSW75+iiWQJB9qcuHQq/aA4IGA==","signatures":[{"sig":"MEQCIE14lEyHHuMqwx41EOxMuzz3kgxVX9OKuZv+NymU8TqVAiBIf2yk68AM8Av/Ww0lK6/utTV+SK4vPlizEPvdyVufXA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.9.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":92749},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"}},"gitHead":"987f24fb2e3a6fba5a86726bb8e88e176f57185c","scripts":{"test":"jest","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"repository":{"url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.9.1_1783512449007_0.34685313614063884","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@alphaone/ai-memory","version":"0.10.0","description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","license":"Apache-2.0","author":{"name":"AlphaOne LLC"},"homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","repository":{"type":"git","url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","directory":"sdk/typescript"},"bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./webhooks":{"types":"./dist/webhooks.d.ts","import":"./dist/webhooks.js"},"./errors":{"types":"./dist/errors.d.ts","import":"./dist/errors.js"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"jest","clean":"rm -rf dist"},"dependencies":{"undici":"^6.21.0"},"devDependencies":{"@types/jest":"^29.5.12","@types/node":"^20.14.0","jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.5.4"},"engines":{"node":">=20.0.0"},"keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"_id":"@alphaone/ai-memory@0.10.0","gitHead":"248d8c7007e0e3eac3db865500149cf6d550052a","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-VQu+SDkJLf60uuDpCJouCfST2xavap+6cfWxjv3mwB58FaTzuKrD0pOClqcft+k4l+FfYWrgP9xXKxDsnrF4bw==","shasum":"b7a3773aa20985188a2c5297244785bb5f8c5162","tarball":"https://registry.npmjs.org/@alphaone/ai-memory/-/ai-memory-0.10.0.tgz","fileCount":26,"unpackedSize":92750,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alphaone%2fai-memory@0.10.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD1gF7iZj1fv85RshtQIYhTw/rSbsqFdSdtOcxXe89T7QIgMs3HGYFOYy/p69KsREYWTk009aCUiR2hYtNcTsqhj20="}]},"_npmUser":{"name":"alphaonedev","email":"Justin@alpha-one.mobi"},"directories":{},"maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-memory_0.10.0_1783842031651_0.23989958369107067"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T13:29:22.508Z","modified":"2026-07-12T07:40:32.149Z","0.6.4":"2026-05-05T13:29:22.757Z","0.7.0":"2026-06-13T23:59:20.713Z","0.7.1":"2026-06-15T18:16:50.000Z","0.8.0":"2026-06-25T23:36:06.794Z","0.8.1":"2026-06-29T19:15:48.160Z","0.9.0":"2026-07-06T22:17:28.755Z","0.9.1":"2026-07-08T12:07:29.159Z","0.10.0":"2026-07-12T07:40:31.772Z"},"bugs":{"url":"https://github.com/alphaonedev/ai-memory-mcp/issues"},"author":{"name":"AlphaOne LLC"},"license":"Apache-2.0","homepage":"https://github.com/alphaonedev/ai-memory-mcp/tree/main/sdk/typescript","keywords":["ai-memory","mcp","memory","claude","alphaone","sdk"],"repository":{"type":"git","url":"git+https://github.com/alphaonedev/ai-memory-mcp.git","directory":"sdk/typescript"},"description":"TypeScript SDK for the ai-memory HTTP API — persistent, tier-aware memory for AI agents.","maintainers":[{"name":"alphaonedev","email":"Justin@alpha-one.mobi"}],"readme":"# @alphaone/ai-memory\n\nTypeScript SDK for the [ai-memory](../../) HTTP API — persistent, tier-aware\nmemory for AI agents, built on top of the same daemon that powers the MCP\nserver.\n\n> Status: `0.6.0-alpha.0`. Target server is ai-memory v0.6.0 HTTP API at\n> `/api/v1/`. Some endpoints (subscriptions, notify/inbox, cluster, metrics,\n> grant/revoke) target v0.6.0.0 shape and may not be merged server-side yet.\n\n- Runtime: Node 20+ (uses `undici.fetch` — Node 20 ships undici as its\n  platform `fetch`). Modern browsers work too; see [Browser usage](#browser-usage).\n- License: Apache-2.0\n- Repo: <https://github.com/alphaone/ai-memory>\n\n## Install\n\n```bash\nnpm install @alphaone/ai-memory\n# or\npnpm add @alphaone/ai-memory\n# or\nyarn add @alphaone/ai-memory\n```\n\n> This SDK is not yet published to npm. During the alpha, consume it via\n> the workspace directly or a tarball (`npm pack`). See the root ROADMAP.\n\n## Quickstart\n\n```ts\nimport { AiMemoryClient } from \"@alphaone/ai-memory\";\n\nconst memory = new AiMemoryClient({\n  baseUrl: \"http://localhost:9077\",\n  apiKey: process.env.AI_MEMORY_API_KEY,     // optional\n  agentId: \"ai:claude-opus-4.7@laptop:pid-1234\", // optional default header\n});\n\n// Store\nconst m = await memory.store({\n  title: \"DNS zone refresh procedure\",\n  content: \"Run `rndc reload` then check SERIAL bump in named.log …\",\n  tier: \"long\",\n  namespace: \"ops/dns\",\n  tags: [\"bind9\", \"runbook\"],\n  priority: 8,\n});\n\n// Recall — fuzzy, scored, mutates access_count + TTL\nconst hits = await memory.recall({\n  context: \"how do I refresh a dns zone\",\n  namespace: \"ops/dns\",\n  limit: 5,\n});\nfor (const hit of hits.memories) {\n  console.log(hit.score.toFixed(3), hit.title);\n}\n```\n\n## Methods\n\nAll methods return typed `Promise<T>` and throw typed errors (see\n[Error handling](#error-handling)). `RequestOptions` (last argument) lets\nyou override `agentId`, pass an `AbortSignal`, or add custom headers.\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `store(body, opts?)` | `POST /api/v1/memories` | Create a new memory. |\n| `storeBulk(memories, opts?)` | `POST /api/v1/memories/bulk` | Batch insert up to 1000. |\n| `get(id, opts?)` | `GET /api/v1/memories/:id` | Fetch by id. |\n| `update(id, body, opts?)` | `PUT /api/v1/memories/:id` | Patch fields. |\n| `delete(id, opts?)` | `DELETE /api/v1/memories/:id` | Delete by id. |\n| `promote(id, opts?)` | `POST /api/v1/memories/:id/promote` | Promote to long tier. |\n| `list(query?, opts?)` | `GET /api/v1/memories` | Paginated list with filters. |\n| `recall(body, opts?)` | `POST /api/v1/recall` | Fuzzy hybrid recall. |\n| `search(query, opts?)` | `GET /api/v1/search` | AND keyword search. |\n| `forget(body, opts?)` | `POST /api/v1/forget` | Bulk delete by pattern/ns/tier. |\n| `link(body, opts?)` | `POST /api/v1/links` | Link two memories. |\n| `getLinks(id, opts?)` | `GET /api/v1/links/:id` | Fetch all links for a memory. |\n| `stats(opts?)` | `GET /api/v1/stats` | Aggregate stats. |\n| `health(opts?)` | `GET /api/v1/health` | Liveness probe. |\n| `namespaces(opts?)` | `GET /api/v1/namespaces` | List namespaces w/ counts. |\n| `agents(opts?)` | `GET /api/v1/agents` | List registered agents. |\n| `registerAgent(body, opts?)` | `POST /api/v1/agents` | Register an NHI. |\n| `metrics(opts?)` | `GET /api/v1/metrics` | Prometheus text-format. |\n| `subscribe(body, opts?)` | `POST /api/v1/subscriptions` | Register a webhook. |\n| `unsubscribe(id, opts?)` | `DELETE /api/v1/subscriptions/:id` | Remove a webhook. |\n| `listSubscriptions(opts?)` | `GET /api/v1/subscriptions` | List current webhooks. |\n| `grant(memoryId, body, opts?)` | `POST /api/v1/memories/:id/grant` | Grant access. |\n| `revoke(memoryId, body, opts?)` | `POST /api/v1/memories/:id/revoke` | Revoke access. |\n| `notify(body, opts?)` | `POST /api/v1/notify` | Send inbox message. |\n| `inbox(query?, opts?)` | `GET /api/v1/inbox` | Read inbox. |\n| `cluster(body, opts?)` | `POST /api/v1/cluster` | Peer management. |\n\n### Examples\n\n#### `.store()`\n\n```ts\nawait memory.store({\n  title: \"Rust trait bounds refresher\",\n  content: \"Trait bounds `where T: Send + Sync` …\",\n  tier: \"mid\",\n  namespace: \"rust\",\n  tags: [\"rust\", \"traits\"],\n  priority: 6,\n  confidence: 0.9,\n  metadata: { source_commit: \"abc123\" },\n});\n```\n\n#### `.recall()`\n\n```ts\nconst { memories, tokens_used } = await memory.recall({\n  context: \"what's our nginx reload command?\",\n  namespace: \"ops\",\n  budget_tokens: 2000,\n});\n```\n\n#### `.search()`\n\n```ts\nconst { results } = await memory.search({\n  q: \"bind9 AND reload\",\n  namespace: \"ops/dns\",\n  limit: 20,\n});\n```\n\n#### `.list()`\n\n```ts\nconst { memories } = await memory.list({\n  namespace: \"rust\",\n  tier: \"long\",\n  limit: 50,\n  offset: 0,\n});\n```\n\n#### `.get()` / `.delete()`\n\n```ts\nconst m = await memory.get(\"b4e3…\");\nawait memory.delete(\"b4e3…\");\n```\n\n#### `.subscribe()` + webhook verification\n\n```ts\nimport express from \"express\";\nimport { verifyWebhookSignature } from \"@alphaone/ai-memory/webhooks\";\n\nconst sub = await memory.subscribe({\n  callback_url: \"https://myapp.example.com/webhooks/ai-memory\",\n  events: [\"memory.stored\", \"memory.updated\"],\n  secret: process.env.WEBHOOK_SECRET,\n});\n\nconst app = express();\napp.post(\n  \"/webhooks/ai-memory\",\n  express.raw({ type: \"application/json\" }),\n  (req, res) => {\n    const sig = String(req.header(\"X-AI-Memory-Signature\") ?? \"\");\n    if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET!)) {\n      return res.status(401).send(\"bad signature\");\n    }\n    const event = JSON.parse(req.body.toString(\"utf8\"));\n    console.log(\"event\", event);\n    res.status(204).end();\n  },\n);\n```\n\n#### `.unsubscribe()`\n\n```ts\nawait memory.unsubscribe(sub.id);\n```\n\n#### `.notify()` / `.inbox()`\n\n```ts\nawait memory.notify({\n  to: \"ai:codex-5.4@ci:pid-42\",\n  subject: \"review needed\",\n  body: \"please approve pending action pa_123\",\n  memory_id: \"b4e3…\",\n});\n\nconst { messages, unread } = await memory.inbox({ unread: true, limit: 20 });\n```\n\n#### `.grant()` / `.revoke()`\n\n```ts\nawait memory.grant(\"b4e3…\", { agent_id: \"alice\", permission: \"read\" });\nawait memory.revoke(\"b4e3…\", { agent_id: \"alice\" });\n```\n\n#### `.cluster()`\n\n```ts\nconst { peers } = await memory.cluster({ action: \"list\" });\n```\n\n#### `.agents()` / `.registerAgent()`\n\n```ts\nawait memory.registerAgent({\n  agent_id: \"ai:claude-opus-4.7@ci:pid-99\",\n  agent_type: \"ai:claude-opus-4.7\",\n  capabilities: [\"memory_write\", \"memory_recall\"],\n});\nconst { agents } = await memory.agents();\n```\n\n#### `.health()`\n\n```ts\nconst h = await memory.health();\nif (h.status !== \"ok\") throw new Error(\"memory daemon unhealthy\");\n```\n\n## Agent identity (NHI)\n\n`agent_id` precedence (from `docs/CLAUDE.md` §Agent Identity):\n\n1. Explicit body-level `agent_id` on `.store()` / `.registerAgent()` etc.\n2. `X-Agent-Id` HTTP header — set via `new AiMemoryClient({ agentId })` or\n   per-call `opts.agentId`.\n3. Server-side `anonymous:req-<uuid8>` fallback (logged at WARN).\n\nThe id must match the regex `^[A-Za-z0-9_\\-:@./]{1,128}$` — permits prefixed\nforms like `ai:claude-opus-4.7@host:pid-123` and future SPIFFE-style ids.\nRejects whitespace, null bytes, control chars, shell metacharacters.\n\n## Authentication\n\n### API key (`X-API-Key`)\n\nThe daemon's `api_key_auth` middleware checks `X-API-Key` (or `?api_key=` query\nparam) when an API key is configured. Pass it to the client once:\n\n```ts\nconst memory = new AiMemoryClient({\n  baseUrl: \"https://memory.internal\",\n  apiKey: process.env.AI_MEMORY_API_KEY,\n});\n```\n\n### mTLS\n\nai-memory itself is HTTP-only by design. Terminate TLS and client-certificate\nauth at a reverse proxy (nginx, Caddy, Envoy) in front of the daemon, then\nforward the verified identity via a header to the backend.\n\nExample nginx snippet:\n\n```nginx\nserver {\n  listen 443 ssl;\n  ssl_certificate     /etc/ssl/memory.crt;\n  ssl_certificate_key /etc/ssl/memory.key;\n  ssl_client_certificate /etc/ssl/ca.crt;\n  ssl_verify_client on;\n\n  location / {\n    proxy_set_header X-Agent-Id $ssl_client_s_dn_cn;\n    proxy_pass http://127.0.0.1:9077;\n  }\n}\n```\n\n## Error handling\n\nAll methods reject with a typed error:\n\n```ts\nimport {\n  ApiError,\n  ValidationError,\n  UnauthorizedError,\n  NotFoundError,\n  ConflictError,\n  ServerError,\n  NetworkError,\n} from \"@alphaone/ai-memory\";\n\ntry {\n  await memory.get(\"bogus\");\n} catch (err) {\n  if (err instanceof NotFoundError) {\n    // 404\n  } else if (err instanceof ValidationError) {\n    // 400 — err.message carries the server's reason\n  } else if (err instanceof UnauthorizedError) {\n    // 401/403 — missing or bad API key\n  } else if (err instanceof ApiError) {\n    console.error(err.status, err.code, err.message);\n  } else if (err instanceof NetworkError) {\n    // connection refused, DNS, TLS, timeout, etc.\n  } else {\n    throw err;\n  }\n}\n```\n\n## Claude Code / Cursor integration\n\n### Claude Code (MCP server already includes memory tools)\n\nRun ai-memory as the MCP server and this SDK in your own tooling scripts:\n\n```json\n// ~/.config/claude-code/settings.json\n{\n  \"mcpServers\": {\n    \"memory\": { \"command\": \"ai-memory\", \"args\": [\"serve\"] }\n  }\n}\n```\n\nInside a Claude Code slash command script (or hook) you can call the HTTP\nSDK against the same daemon, e.g. to fan-out a memory bulk-create from a\nCI hook:\n\n```ts\nimport { AiMemoryClient } from \"@alphaone/ai-memory\";\nconst mem = new AiMemoryClient({ baseUrl: \"http://localhost:9077\" });\nawait mem.storeBulk(newFacts.map(f => ({ title: f.title, content: f.body, tier: \"long\" })));\n```\n\n### Cursor\n\nIn Cursor's `.cursorrules` or a project-level script, use the same client.\nCursor's agent surface will find stored memories via the MCP server; the SDK\nis for bespoke tool integrations (post-commit hooks, review automation).\n\n### Claude desktop extensions\n\nRegister the SDK-driven tool under `.claude/commands/*.ts` and import the\nclient as shown in Quickstart.\n\n## Browser usage\n\n`undici.fetch` is a Node module. For browsers, pass the native `fetch`:\n\n```ts\nimport { AiMemoryClient } from \"@alphaone/ai-memory\";\n// @ts-ignore - browser globalThis.fetch\nconst memory = new AiMemoryClient({ baseUrl: \"/api\" }, globalThis.fetch);\n```\n\nWebhook verification (`verifyWebhookSignature`) uses `node:crypto`; for the\nbrowser use the Web Crypto API (`crypto.subtle.importKey` + `sign(\"HMAC\")`) —\nnot yet shipped in this package.\n\n## Development\n\n```bash\nnpm install        # (not run by the scaffold generator — review first)\nnpm run typecheck  # tsc --noEmit\nnpm run build      # emit ./dist\nAI_MEMORY_TEST_DAEMON=1 npm test   # integration tests against a live daemon\n```\n\n## Links\n\n- Main repo: <https://github.com/alphaone/ai-memory>\n- Architecture notes: [`docs/CLAUDE.md`](../../CLAUDE.md)\n- HTTP API handlers: [`src/handlers.rs`](../../src/handlers.rs)\n- Validation rules: [`src/validate.rs`](../../src/validate.rs)\n","readmeFilename":"README.md"}