{"_id":"@ahmedshaikh/agent-memory-mcp","name":"@ahmedshaikh/agent-memory-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ahmedshaikh/agent-memory-mcp","version":"0.1.0","type":"module","description":"Persistent, semantic long-term memory for AI agents — an MCP server + hook integration so agents remember decisions, gotchas, and conventions across sessions and recall them automatically.","bin":{"agent-memory":"dist/cli.js"},"engines":{"node":">=22"},"scripts":{"serve":"tsx src/server.ts","mem":"tsx src/cli.ts","build":"tsc","test":"node --import tsx --test --test-force-exit test/*.test.ts","eval":"tsx eval/run-eval.ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@xenova/transformers":"^2.17.2","sqlite-vec":"^0.1.9","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.7.0","typescript":"^5.4.0"},"license":"MIT","author":{"name":"ahmedshaikh"},"keywords":["mcp","model-context-protocol","claude","agent","ai","memory","embeddings","recall","long-term-memory"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/agent-memory-mcp.git"},"homepage":"https://github.com/RaziStuff/agent-memory-mcp#readme","bugs":{"url":"https://github.com/RaziStuff/agent-memory-mcp/issues"},"publishConfig":{"access":"public"},"gitHead":"128eccdcd3a5cb29ae2ae9c545b3d53f32dfe09e","_id":"@ahmedshaikh/agent-memory-mcp@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-t/tn+GEuzbiGOTh/x7f3sGNRLhM95tAXwbk/CIRZo0HJI7+allZTNqnvDB9gXwn9BH3Hzhjy7mYCXgvEIBSElQ==","shasum":"a1a2db6786535f63d9736b6c5cad9237c35ef90a","tarball":"https://registry.npmjs.org/@ahmedshaikh/agent-memory-mcp/-/agent-memory-mcp-0.1.0.tgz","fileCount":8,"unpackedSize":35625,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDFoZdMumn+EqfKCR4IQYABVq83LqX5fZ9cwnv0UyWg4AiB0wPudUE5cxSQ+w/k//xpRU6XFGX2BDI2bCgUB5o7quQ=="}]},"_npmUser":{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"},"directories":{},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-memory-mcp_0.1.0_1782701031028_0.6315568981728017"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T02:43:50.774Z","0.1.0":"2026-06-29T02:43:51.177Z","modified":"2026-06-29T02:43:51.416Z"},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"description":"Persistent, semantic long-term memory for AI agents — an MCP server + hook integration so agents remember decisions, gotchas, and conventions across sessions and recall them automatically.","homepage":"https://github.com/RaziStuff/agent-memory-mcp#readme","keywords":["mcp","model-context-protocol","claude","agent","ai","memory","embeddings","recall","long-term-memory"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/agent-memory-mcp.git"},"author":{"name":"ahmedshaikh"},"bugs":{"url":"https://github.com/RaziStuff/agent-memory-mcp/issues"},"license":"MIT","readme":"# agent-memory\n\nPersistent, semantic **long-term memory for AI agents** — so an agent stops being\namnesiac. It remembers decisions, gotchas, conventions, and preferences across\nsessions, and **recalls the relevant ones automatically** on every prompt.\n\n```\nremember(\"This machine has no Node by default — run `export PATH=…nvm…` first\", type: \"gotcha\")\n        ↓  (a later session, different task)\nuser: \"node: command not found\"\n        ↓  a hook silently injects:\n## Relevant memories (from agent-memory)\n- [gotcha] This machine has no Node by default — run `export PATH=…nvm…` first\n```\n\nThe agent fixes it instantly — because last time's lesson was waiting for it.\n\n## The hard part: getting agents to actually use it\n\nA memory tool nobody calls is dead weight. So adoption isn't left to chance:\n\n- **Recall is automatic (push, not pull).** A Claude Code `UserPromptSubmit` hook\n  runs `agent-memory recall \"<prompt>\"` and **injects the result into context** on\n  every turn. The agent never has to *decide* to recall — relevant past knowledge\n  is just there. A relevance floor means it injects nothing when nothing matches,\n  so it never pollutes context.\n- **Writing is nudged.** The MCP tool descriptions tell the agent *when* to\n  `remember`, a low-friction `reflect` tool saves several learnings in one call\n  at the end of a task, and `agent-memory instructions` prints a CLAUDE.md snippet\n  that makes \"save durable learnings\" a standing instruction in the agent's context.\n\nThis is the same pattern Claude Code's own memory uses (auto-loaded `MEMORY.md`\n\\+ instructions) — just semantic, ranked, scoped, and self-correcting.\n\n## The memory model\n\nEach memory has a **type** — `decision · fact · gotcha · convention · preference ·\ntask · reference` — and a **scope** (`global`, or a project id). Recall returns the\ncurrent project's memories plus global ones. Memories also have:\n\n- **relevance × recency × usefulness** ranking — fresh and frequently-recalled\n  memories rise; stale ones fade.\n- **dedup on write** — a near-identical memory updates in place instead of piling up.\n- **supersession** — a new memory can replace an outdated one (`supersedes`), and\n  superseded memories stop being recalled (so memory self-corrects instead of rotting).\n- **links** — memories can reference each other, forming a small knowledge graph.\n\n## MCP tools\n\n`remember`, `recall`, `forget`, `prune`, `link_memories`, `list_memories`,\n`memory_status`. `prune` is long-term hygiene — it drops superseded and stale,\nnever-recalled memories so the store stays useful over months.\n\n## Recall quality (measured)\n\n`npm run eval` runs a labeled corpus + query set and reports hit@1 / hit@3 / MRR\nplus how often off-topic queries correctly stay below the relevance floor — so\nranking changes are measured, not eyeballed. Current baseline (local MiniLM):\n\n| metric | value |\n|--------|-------|\n| hit@1 | 41% |\n| hit@3 | **76%** |\n| MRR | 0.56 |\n| off-topic held below floor | 3/3 |\n\nSo the right memory is in the top 3 most of the time, and the floor (0.35) is\ncalibrated: off-topic queries inject nothing. The remaining misses are synonym\ngaps the small embedding model doesn't bridge (the model is the ceiling, not the\nranking) — a code-tuned or larger embedder would lift it.\n\n## Setup\n\n```bash\nnpm install      # needs Node 22+ (built-in node:sqlite); first run downloads a ~90MB embedding model\nnpm test\n```\n\n### Register the server + the auto-recall hook\n\n```bash\n# 1. the MCP server (gives the agent the remember/recall tools)\nclaude mcp add agent-memory -- node /abs/path/agent-memory/dist/server.js\n\n# 2. the hook that auto-recalls on every prompt — print the config and add it to settings.json:\nnode /abs/path/agent-memory/dist/cli.js hook\n```\n\nBy default memory lives in `~/.agent-memory/memory.db` (one brain across all\nprojects, scoped internally). Override with `AGENT_MEMORY_DB` /\n`AGENT_MEMORY_SCOPE`.\n\n## CLI\n\n```bash\nagent-memory remember \"deploys go out via deploy.sh\" --type convention\nagent-memory recall \"how do I deploy\"      # prints injectable markdown (or nothing)\nagent-memory list --type gotcha\nagent-memory status\n```\n\n## How it works\n\nSQLite + `sqlite-vec` for storage and vector search; FTS5 for keyword search;\nlocal MiniLM embeddings (offline, nothing leaves the machine). Recall fuses\nvector + lexical results (reciprocal rank fusion) and re-weights by recency and\naccess count. Same engine family as a code search index — pointed at agent-authored\nknowledge instead of code.\n\n## Honest limits\n\n- **Recall is the strong half; write-adoption is softer** — it depends on the agent\n  judging what's worth saving (nudged by tool descriptions + a Stop hook), and is\n  the part to iterate on.\n- **Name/relevance based, not a reasoner** — it retrieves; it doesn't verify a\n  memory is still true (supersession is explicit, not automatic).\n- **In-memory model load** per process; recall through the CLI pays a model-load\n  cost (~seconds) per call — fine for a per-prompt hook, but batchable later.\n\n## Version note\n\nRequires Node 22+ for the built-in `node:sqlite`. `sqlite-vec` ships prebuilt\nbinaries (no native build step).\n","readmeFilename":"README.md","_rev":"1-c4d7e5c0b28539580687edb0aafb9728"}