{"_id":"@aabadin/agent-memory-mcp","_rev":"3-248bd564f4e95da554b0eb88e55dfc02","name":"@aabadin/agent-memory-mcp","dist-tags":{"latest":"2.3.0"},"versions":{"2.0.0":{"name":"@aabadin/agent-memory-mcp","version":"2.0.0","keywords":["mcp","memory","lancedb","vector-search","bm25","embeddings","model-context-protocol","agent-memory"],"author":{"name":"Adam Drew"},"license":"GPL-3.0-or-later","_id":"@aabadin/agent-memory-mcp@2.0.0","maintainers":[{"name":"aabadin","email":"aabadin@gmail.com"}],"homepage":"https://github.com/adamrdrew/agent-memory-mcp#readme","bugs":{"url":"https://github.com/adamrdrew/agent-memory-mcp/issues"},"bin":{"agent-memory-mcp":"dist/index.js"},"dist":{"shasum":"48a377f03ba3e0f10de1072f4802bacbe427b6db","tarball":"https://registry.npmjs.org/@aabadin/agent-memory-mcp/-/agent-memory-mcp-2.0.0.tgz","fileCount":33,"integrity":"sha512-UeS4mzcXGiy8Hu4Z6gxsZszoRH3aNfD2OmhavzEXtKqRrP/XoTPsQgad5My69uvuJ4wpufzgvuwjQyqdYX0rmA==","signatures":[{"sig":"MEYCIQCw9V6fLNJLIfa/pKxNYYrrDgbbCOv2t8d0s0eto9X+kwIhANXjik630bRTXfzZRxYStjSGRKPKFkaYHVo8RVazVuBR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":137365},"main":"dist/index.js","type":"module","_from":"file:aabadin-agent-memory-mcp-2.0.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"aabadin","email":"aabadin@gmail.com"},"_resolved":"C:\\Users\\aabad\\Documents\\CODE\\ia\\memory-context\\agent-memory-mcp\\aabadin-agent-memory-mcp-2.0.0.tgz","_integrity":"sha512-UeS4mzcXGiy8Hu4Z6gxsZszoRH3aNfD2OmhavzEXtKqRrP/XoTPsQgad5My69uvuJ4wpufzgvuwjQyqdYX0rmA==","repository":{"url":"git+https://github.com/adamrdrew/agent-memory-mcp.git","type":"git"},"_npmVersion":"11.12.1","description":"MCP server for persistent agent memory — hybrid BM25 + vector search backed by LanceDB with local ONNX embeddings. No API keys, fully local.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"zod":"^3.24.0","@lancedb/lancedb":"^0.26.2","@huggingface/transformers":"^4.2.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-memory-mcp_2.0.0_1779172751785_0.5188940079314917","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@aabadin/agent-memory-mcp","version":"2.1.0","keywords":["mcp","memory","sqlite","embeddings","vector-search","bm25","agent"],"author":{"name":"Adrian Abadin"},"license":"GPL-3.0-or-later","_id":"@aabadin/agent-memory-mcp@2.1.0","maintainers":[{"name":"aabadin","email":"aabadin@gmail.com"}],"homepage":"https://github.com/adrianabadin/agent-memory-mcp#readme","bugs":{"url":"https://github.com/adrianabadin/agent-memory-mcp/issues"},"bin":{"agent-memory-mcp":"dist/index.js"},"dist":{"shasum":"e270aae77e0337509f4d55edd49592ea109f7e0d","tarball":"https://registry.npmjs.org/@aabadin/agent-memory-mcp/-/agent-memory-mcp-2.1.0.tgz","fileCount":54,"integrity":"sha512-hxuJbruVuX1pS5iU/JYtzzz4Fh8UUpdG+EcwWLwpC+PSMKZVsJEsCG4HKO10pjL1od0SOGMEy1i/QYnRb//ceA==","signatures":[{"sig":"MEQCIFAKckssJnR6z/chJinghboYXZPZse6cQM4Nb65H6t8DAiBYJAlxNg6NrHsq+H0Z03DTApi9FQ6My7X+PdJ+wgoYDA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":181607},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.5.0"},"gitHead":"18178e183fdca55411319b7da0dc306d587269a4","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","migrate":"tsx scripts/migrate-lance.ts","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"aabadin","email":"aabadin@gmail.com"},"repository":{"url":"git+https://github.com/adrianabadin/agent-memory-mcp.git","type":"git"},"_npmVersion":"11.12.1","description":"MCP server for agent memory backed by SQLite (WAL mode) with hybrid FTS5 BM25 + cosine vector search","directories":{},"_nodeVersion":"24.15.0","dependencies":{"zod":"^3.24.0","@huggingface/transformers":"^4.2.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.0.0","@lancedb/lancedb":"^0.26.2"},"_npmOperationalInternal":{"tmp":"tmp/agent-memory-mcp_2.1.0_1780573098014_0.8911962894369618","host":"s3://npm-registry-packages-npm-production"}},"2.3.0":{"name":"@aabadin/agent-memory-mcp","version":"2.3.0","description":"MCP server for agent memory backed by SQLite (WAL mode) with hybrid FTS5 BM25 + cosine vector search","license":"GPL-3.0-or-later","type":"module","main":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./compose":{"types":"./dist/compose.d.ts","default":"./dist/compose.js"},"./package.json":"./package.json"},"bin":{"agent-memory-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"vitest run","test:watch":"vitest","migrate":"tsx scripts/migrate-lance.ts","prepublishOnly":"npm run build"},"keywords":["mcp","memory","sqlite","embeddings","vector-search","bm25","agent"],"repository":{"type":"git","url":"git+https://github.com/adrianabadin/agent-memory-mcp.git"},"author":{"name":"Adrian Abadin"},"dependencies":{"@huggingface/transformers":"^4.2.0","@modelcontextprotocol/sdk":"^1.12.0","zod":"^3.24.0"},"devDependencies":{"@lancedb/lancedb":"^0.26.2","@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.7.0","vitest":"^4.1.8"},"engines":{"node":">=22.5.0"},"publishConfig":{"access":"public"},"gitHead":"bc83324196a40e287ab65d3a6d1fe1c8a5899037","types":"./dist/index.d.ts","_id":"@aabadin/agent-memory-mcp@2.3.0","bugs":{"url":"https://github.com/adrianabadin/agent-memory-mcp/issues"},"homepage":"https://github.com/adrianabadin/agent-memory-mcp#readme","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-YaITSs14/sGdTLvI45q3BcTO4YZ/SMmfmBfzsWXUwpF+p+8P6zuw+WTUxLglane2wzlfnCv1oSr46ROW3xAPDg==","shasum":"6366f4802e09688642984dd9604db671c61e95d8","tarball":"https://registry.npmjs.org/@aabadin/agent-memory-mcp/-/agent-memory-mcp-2.3.0.tgz","fileCount":85,"unpackedSize":636335,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFwiKxaXzdpwsgEmQzXPqKhQTyc5z56LKM/xDZGNI5X3AiEA11Y65znLpm0ZS8ifxmDkmJqbuZkkiPf79zsvWaY5mRM="}]},"_npmUser":{"name":"aabadin","email":"aabadin@gmail.com"},"directories":{},"maintainers":[{"name":"aabadin","email":"aabadin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-memory-mcp_2.3.0_1782355003752_0.270893762474256"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T06:39:11.718Z","modified":"2026-06-25T02:36:44.078Z","2.0.0":"2026-05-19T06:39:11.948Z","2.1.0":"2026-06-04T11:38:18.162Z","2.3.0":"2026-06-25T02:36:43.976Z"},"bugs":{"url":"https://github.com/adrianabadin/agent-memory-mcp/issues"},"author":{"name":"Adrian Abadin"},"license":"GPL-3.0-or-later","homepage":"https://github.com/adrianabadin/agent-memory-mcp#readme","keywords":["mcp","memory","sqlite","embeddings","vector-search","bm25","agent"],"repository":{"type":"git","url":"git+https://github.com/adrianabadin/agent-memory-mcp.git"},"description":"MCP server for agent memory backed by SQLite (WAL mode) with hybrid FTS5 BM25 + cosine vector search","maintainers":[{"name":"aabadin","email":"aabadin@gmail.com"}],"readme":"# @aabadin/agent-memory-mcp\r\n\r\nMCP server for persistent agent memory, backed by **SQLite** (`node:sqlite` built-in, Node 22.5+) with hybrid BM25 + vector search. Gives AI agents the ability to store, search, and manage memories across sessions using the [Model Context Protocol](https://modelcontextprotocol.io/).\r\n\r\nAll data stays on your machine. Embeddings are generated locally using [bge-m3](https://huggingface.co/Xenova/bge-m3) via ONNX — no API keys, no network dependencies after initial setup.\r\n\r\n## Features\r\n\r\n- **Hybrid search** — combines BM25 full-text search with cosine vector similarity via Reciprocal Rank Fusion (RRF)\r\n- **Cross-project search** — opt-in `all_projects` flag queries across multiple project memory DBs and merges results by score\r\n- **Conflict resolution** — semantic collision detection during `store()` (configurable threshold), `compare` and `judge` MCP tools, and 6-relation `memory_relations` table for LLM-driven verdicts\r\n- **Pin / unpin memories** — explicitly mark memories as important; pinned memories sort first and are exempt from temporal decay\r\n- **Review queue** — `review_queue` tool surfaces memories flagged by staged decay (dimmed / shadow / gist_only); pinned and `non_forgettable` memories are skipped\r\n- **Local embeddings** — runs Xenova/bge-m3 locally via ONNX, no external API calls\r\n- **12 memory categories** — structured taxonomy for organising memories\r\n- **Batch operations** — store multiple memories in a single call\r\n- **Session ledger** — captures prompts, responses, tool calls, and summaries; auto-links stores to active session\r\n- **Hardcopy backup** — optional JSON file mirror of all mutations for human-readable backup\r\n- **Temporal decay** — exponential time-based decay favors recent memories when relevance is similar. Configurable half-life, with `evergreen` and `never-forget` tag exemptions\r\n- **Runtime protocol flag** — `get_memory_protocol` exposes dual/persistent memory backend state to MCP clients\r\n- **Fully local** — all data stays on disk, no network dependencies after first model download\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install -g @aabadin/agent-memory-mcp\r\n```\r\n\r\nWarning: the first run downloads `Xenova/bge-m3`. Keep at least 1 GB free for the local model cache and SQLite store.\r\n\r\nSupported platforms: Linux x64/arm64, macOS x64/arm64, Windows x64.\r\n\r\nThen add the server to your MCP client configuration.\r\n\r\n### Claude Desktop\r\n\r\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"agent-memory\": {\r\n      \"command\": \"agent-memory-mcp\",\r\n      \"env\": {\r\n        \"MEMORY_DB_PATH\": \"/path/to/your/memory-db\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Claude Code\r\n\r\nAdd to your project's `.mcp.json`:\r\n\r\n```json\r\n{\r\n  \"agent-memory\": {\r\n    \"command\": \"agent-memory-mcp\",\r\n    \"env\": {\r\n      \"MEMORY_DB_PATH\": \"/path/to/your/memory-db\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Configuration\r\n\r\n| Variable | Required | Description |\r\n|---|---|---|\r\n| `MEMORY_DB_PATH` | Yes | Base path for the SQLite database. The actual file is created at `${MEMORY_DB_PATH}.db`. If a LanceDB directory exists at this path, the store migrates it automatically on first start. |\r\n| `EMBEDDING_MODEL` | No | HuggingFace model ID (default: `Xenova/bge-m3`) |\r\n| `EMBEDDING_DIMENSIONS` | No | Expected vector size. Default: inferred from model (`1024` for `Xenova/bge-m3`) |\r\n| `EMBEDDING_POOLING` | No | Pooling strategy. Default: inferred from model (`cls` for BGE models, `mean` otherwise) |\r\n| `EMBEDDING_CACHE_PATH` | No | Directory for content-addressed binary embedding cache. Speeds up repeated runs by skipping ONNX inference for previously-seen text |\r\n| `MEMORY_DECAY_HALF_LIFE` | No | Decay half-life in days (default: `30`). Set to `0` to disable temporal decay |\r\n| `ENABLE_HARDCOPY` | No | Set to `true` to enable JSON file backup |\r\n| `HARDCOPY_PATH` | If hardcopy enabled | Directory for JSON mirror files |\r\n\r\n## Storage Backend\r\n\r\nAs of v2.0, the storage backend is **SQLite** via Node's built-in `node:sqlite` module (requires Node ≥ 22.5.0). No external database dependency is needed.\r\n\r\n**Automatic LanceDB migration:** If a LanceDB directory exists at `MEMORY_DB_PATH` when the server starts, it is automatically migrated to the SQLite file at `${MEMORY_DB_PATH}.db`. The original LanceDB directory is left intact after migration.\r\n\r\n## Upgrading From MiniLM\r\n\r\nIf you already have a database created with a smaller embedding model such as `Xenova/all-MiniLM-L6-v2` (384 dimensions), you must rebuild that database before using `bge-m3` (1024 dimensions). Mixing vector sizes in the same store is not supported.\r\n\r\nTypical upgrade flow:\r\n\r\n1. Stop the MCP server.\r\n2. Backup or delete the old `MEMORY_DB_PATH` files (the `.db` file and any LanceDB directory).\r\n3. Start the server again so all memories are re-embedded with the new model.\r\n\r\n## Tools\r\n\r\n### Core CRUD\r\n| Tool | Description |\r\n|---|---|\r\n| `store` | Store a single memory with content, category, and tags. Opt-in `detect_conflicts` flag triggers collision detection (returns `{ judgment_required, candidates }` without persisting when matches found) |\r\n| `store_batch` | Store multiple memories in one call |\r\n| `search` | Search memories by meaning and/or keywords. Supports `hybrid` (default), `keyword`, `semantic`. Opt-in `all_projects` flag for cross-project search. Pinned memories sort first |\r\n| `recall` | Multi-topic contextual recall — searches multiple topics in parallel and includes recent memories |\r\n| `find_related` | Find memories similar to a specific memory |\r\n| `list_recent` | List most recent memories, optionally filtered by category. Excludes archived. Pinned sort first |\r\n| `update` | Update an existing memory — re-embeds automatically if content changes. Preserves lifecycle status |\r\n| `delete` | Permanently remove a memory by ID |\r\n| `stats` | Get database statistics: total count, breakdown by category, timestamps, prune candidates |\r\n| `prune` | Preview or prune low-strength and dormant memories. Dry-run by default |\r\n\r\n### Pin & Lifecycle\r\n| Tool | Description |\r\n|---|---|\r\n| `pin` | Mark a memory as explicitly important. Pinned memories sort first and are exempt from temporal decay |\r\n| `unpin` | Remove pin marker (memory re-enters normal decay schedule) |\r\n| `update_memory_status` | Transition a memory through lifecycle states: `active` → `needs_review` → `archived`. Pinned memories and `archived` (terminal) are rejected for further transitions |\r\n\r\n### Conflict Resolution\r\n| Tool | Description |\r\n|---|---|\r\n| `compare` | Compare two memories: cosine similarity, shared entities, content diff, and a relation recommendation |\r\n| `judge` | Persist a verdict to the `memory_relations` table. Relations: `related`, `compatible`, `scoped`, `conflicts_with`, `supersedes`, `not_conflict`. The `supersedes` relation cascades to archive the older memory |\r\n\r\n### Review Queue\r\n| Tool | Description |\r\n|---|---|\r\n| `review_queue` | List memories with `status='needs_review'`, ordered by oldest first. Filterable by `project_id`. Default limit 50 |\r\n\r\n### Topic Aliases\r\n| Tool | Description |\r\n|---|---|\r\n| `upsert_topic_alias` | Bind a `topic_key` to a memory id. Topic keys enable upsert-by-topic semantics: re-storing with the same topic updates the existing memory |\r\n| `resolve_topic` | Resolve a `topic_key` to its memory |\r\n| `suggest_topic_key` | Slugify content into a deterministic `topic_key`, deduplicating against existing keys |\r\n\r\n### Session Ledger\r\n| Tool | Description |\r\n|---|---|\r\n| `store_session_prompt` | Record a user prompt in the session ledger |\r\n| `store_session_response` | Record an assistant response linked to its prompt |\r\n| `store_session_tool_call` | Record an important tool call during the session |\r\n| `store_session_summary` | Generate and store a structured session summary (decisions, key titles, memory ids, artifact refs) |\r\n| `get_session` | Retrieve all ledger entries for a session, ordered by `created_at ASC` |\r\n| `list_sessions` | List distinct sessions, ordered by last activity desc, with prompt counts |\r\n| `link_prompt_to_memory` | Create a many-to-many link between a prompt and a memory (with optional response id) |\r\n| `set_session_context` | Set the active session context. Subsequent stores auto-link to this session |\r\n| `get_session_context` | Retrieve the current session context |\r\n\r\n### Cross-Project & Errors\r\n| Tool | Description |\r\n|---|---|\r\n| `register_project` | Register a project in the global project registry |\r\n| `sync_project_metadata` | Update the global context snapshot for a project (objective, stack, architecture, minimap) |\r\n| `merge_projects` | Merge memories from one project into another in the global store |\r\n| `search_global_errors` | Search the cross-project error database |\r\n| `record_error` | Record a debugged error and its solution in the global error store |\r\n\r\n### Symbols & Protocol\r\n| Tool | Description |\r\n|---|---|\r\n| `attach_symbol` | Bind a memory to a code symbol (lang/path/kind/scope/name/arity) for graph-aware lookup |\r\n| `get_by_symbol` | Retrieve all memories and session items linked to a symbol key |\r\n| `get_memory_protocol` | Read the dual-save memory protocol flag (`dual` \\| `pmc-only`) and runtime availability of PMC + Engram backends |\r\n\r\n## Search Modes\r\n\r\nThe `search` tool supports three modes:\r\n\r\n- **`hybrid`** (default) — combines BM25 keyword scoring with vector similarity using RRF reranking. Falls back to semantic-only if the full-text index is unavailable.\r\n- **`keyword`** — BM25 full-text search only.\r\n- **`semantic`** — cosine vector similarity only.\r\n\r\nAll modes support filtering by category, tags, and date range.\r\n\r\n## Temporal Decay\r\n\r\nSearch results are scored with exponential time-based decay so that recent memories surface above older ones when semantic relevance is similar. The decay follows a half-life model: a memory one half-life old has its score halved, two half-lives old gets quartered, and so on.\r\n\r\n- **Default half-life**: 30 days (configurable via `MEMORY_DECAY_HALF_LIFE`)\r\n- **Disable**: set `MEMORY_DECAY_HALF_LIFE=0`\r\n- **Exempt tags**: memories tagged `evergreen` or `never-forget` are never decayed\r\n\r\n## Memory Categories\r\n\r\n`code-solution` · `bug-fix` · `architecture` · `learning` · `tool-usage` · `debugging` · `performance` · `security` · `observation` · `personal` · `relationship` · `other`\r\n\r\n## Development\r\n\r\n```bash\r\ngit clone https://github.com/adrianabadin/agent-memory-mcp.git\r\ncd agent-memory-mcp\r\nnpm install\r\nnpm run dev          # Run with tsx (no build step)\r\nnpm run build        # Compile TypeScript to dist/\r\nnpm test             # Run all tests\r\nnpm run test:watch   # Run tests in watch mode\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the [GNU General Public License v3.0](LICENSE).\r\n","readmeFilename":"README.md"}