{"_id":"@aibrain/mcp","_rev":"3-cfd3885e04c6a36dfda20bdb27353e80","name":"@aibrain/mcp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@aibrain/mcp","version":"0.1.0","keywords":["mcp","memory","ai","agent","vector-search","lancedb"],"license":"MIT","_id":"@aibrain/mcp@0.1.0","maintainers":[{"name":"nkamau","email":"ngumba.kamau@gmail.com"}],"bin":{"aibrain-mcp":"dist/cli.js"},"dist":{"shasum":"75caee40c8e5e9411bb4a8cb2216f55d4e963e81","tarball":"https://registry.npmjs.org/@aibrain/mcp/-/mcp-0.1.0.tgz","fileCount":67,"integrity":"sha512-r2ikjvWoTAQqALYqyTyBpCt6O2pDaBWofr+o1L12MQtlGiF8ePAfMBSCpTXL2F4Eu6GvFeNDZN2Yje5qED2vVQ==","signatures":[{"sig":"MEUCIBldCNk/ieZTaGN5OjA7tzXxDi+TppPGKF9sEjoR546wAiEAnujU4nZDyXsCie/X5nOWeOFQ4lI/IWsUfkuV0Gc1uWY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102227},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"2d32caf93c0ad87b901837daafe8ba5680cdbbf4","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/cli.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"nkamau","email":"ngumba.kamau@gmail.com"},"_npmVersion":"11.11.0","description":"AI agent memory MCP server with hybrid BM25 + vector search — no Docker required","directories":{},"_nodeVersion":"25.8.0","dependencies":{"zod":"^3.22.0","uuid":"^11.0.0","dotenv":"^16.0.0","apache-arrow":"^18.0.0","@lancedb/lancedb":"^0.17.0","@huggingface/transformers":"^3.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/uuid":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.0_1773761503236_0.41540317197432963","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aibrain/mcp","version":"0.1.1","keywords":["mcp","memory","ai","agent","vector-search","lancedb"],"license":"MIT","_id":"@aibrain/mcp@0.1.1","maintainers":[{"name":"nkamau","email":"ngumba.kamau@gmail.com"}],"bin":{"aibrain-mcp":"dist/cli.js"},"dist":{"shasum":"5987eef8eb15f3817f77ec82701e1d847848e50a","tarball":"https://registry.npmjs.org/@aibrain/mcp/-/mcp-0.1.1.tgz","fileCount":67,"integrity":"sha512-jAHp04BaL89ciicvSiqAPuzGxWgJV6tUV0zaAC/XPOqtFdhbjlLtKohdVwQVXxnBNc/zL+sliAhHPKR0vrbh9A==","signatures":[{"sig":"MEUCIQDfsillrdoJmqLmN+0vi+TUDZFUoWQP3ahixrh0DTYyggIgfmoGaNSU+q98+Bpwi9BIoGbbB+x1jdr4AtyioDnc620=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102029},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"2d32caf93c0ad87b901837daafe8ba5680cdbbf4","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/cli.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"nkamau","email":"ngumba.kamau@gmail.com"},"_npmVersion":"11.11.0","description":"AI agent memory MCP server with hybrid BM25 + vector search — no Docker required","directories":{},"_nodeVersion":"25.8.0","dependencies":{"zod":"^3.22.0","uuid":"^11.0.0","dotenv":"^16.0.0","apache-arrow":"^18.0.0","@lancedb/lancedb":"^0.17.0","@huggingface/transformers":"^3.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/uuid":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.1_1773761850488_0.21426730358560064","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aibrain/mcp","version":"0.1.2","description":"AI agent memory MCP server with hybrid BM25 + vector search — no Docker required","keywords":["mcp","memory","ai","agent","vector-search","lancedb"],"license":"MIT","type":"module","engines":{"node":">=20"},"bin":{"aibrain-mcp":"dist/cli.js"},"main":"./dist/index.js","scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/cli.js","prepublishOnly":"npm run build"},"dependencies":{"@huggingface/transformers":"^3.0.0","@lancedb/lancedb":"^0.17.0","@modelcontextprotocol/sdk":"^1.0.0","apache-arrow":"^18.0.0","dotenv":"^16.0.0","uuid":"^11.0.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^22.0.0","@types/uuid":"^10.0.0","typescript":"^5.6.0"},"gitHead":"2d32caf93c0ad87b901837daafe8ba5680cdbbf4","types":"./dist/index.d.ts","_id":"@aibrain/mcp@0.1.2","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-rGOGSw4w1W9sPfU2eutmn01iqDXgjIi661N1qTQ4ohYUSpY/Rk6yO5uawJvXlHiVPH7AKgwr8DuieI/TNJIWSw==","shasum":"80e07e880bf3dadf72d6d8cadfe59374b48af473","tarball":"https://registry.npmjs.org/@aibrain/mcp/-/mcp-0.1.2.tgz","fileCount":67,"unpackedSize":101754,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCwjvyRsB8XNwySSAMa5+UccQV/CJ38ypZ10BBsE+UHvgIgcnjYhaXqc28j+u+Fhrw2myL3RThiQWqdxBEakd5SzZE="}]},"_npmUser":{"name":"nkamau","email":"ngumba.kamau@gmail.com"},"directories":{},"maintainers":[{"name":"nkamau","email":"ngumba.kamau@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.2_1773762050768_0.2379367125395102"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-17T15:31:43.115Z","modified":"2026-03-17T15:40:51.086Z","0.1.0":"2026-03-17T15:31:43.391Z","0.1.1":"2026-03-17T15:37:30.638Z","0.1.2":"2026-03-17T15:40:50.927Z"},"license":"MIT","keywords":["mcp","memory","ai","agent","vector-search","lancedb"],"description":"AI agent memory MCP server with hybrid BM25 + vector search — no Docker required","maintainers":[{"name":"nkamau","email":"ngumba.kamau@gmail.com"}],"readme":"# aiBrain MCP\n\nAI agent memory server with hybrid BM25 + vector search. No Docker required — runs anywhere via `npx`.\n\n## Quick Start\n\n```bash\n# Add to Claude Code (or any MCP client)\nnpx -y @aibrain/mcp\n\n# Optional: install Ollama for semantic search\nnpx -y @aibrain/mcp --setup\n\n# Optional: set up the web dashboard\nnpx -y @aibrain/mcp --setup-ui\nnpx -y @aibrain/mcp --setup-ui ~/projects   # custom location\n```\n\n## Features\n\n- **6 memory tools**: `save_memory`, `search_memories`, `get_recent_memories`, `get_memory`, `delete_memory`, `list_tags`\n- **Hybrid search**: BM25 full-text + vector semantic search with Reciprocal Rank Fusion\n- **Zero external dependencies**: embedded LanceDB + local ONNX embeddings via Transformers.js — no separate server needed\n- **Persistent storage**: memories saved to `~/.aibrain/memories` by default\n- **First-run model download**: the `nomic-embed-text-v1` ONNX model (~50MB) downloads once to `~/.cache/huggingface` and is reused on all subsequent runs\n\n---\n\n## Client Integration\n\n### Claude Code\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"]\n    }\n  }\n}\n```\n\n### Amp\n\nAdd to `~/.config/amp/settings.json` (global) or `.amp/settings.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"]\n    }\n  }\n}\n```\n\n---\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `AIBRAIN_DATA_DIR` | `~/.aibrain/memories` | Where memories are stored |\n| `EMBEDDING_PROVIDER` | `transformers` | Embedding backend: `transformers` or `ollama` |\n| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL (only used when `EMBEDDING_PROVIDER=ollama`) |\n| `OLLAMA_MODEL` | `nomic-embed-text` | Ollama embedding model (only used when `EMBEDDING_PROVIDER=ollama`) |\n| `OLLAMA_TIMEOUT_MS` | `5000` | Ollama request timeout (only used when `EMBEDDING_PROVIDER=ollama`) |\n| `LOG_LEVEL` | `info` | Log level (debug/info/warn/error) |\n\nSet these in your shell profile or pass them via `env` in your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"],\n      \"env\": {\n        \"AIBRAIN_DATA_DIR\": \"/custom/path/to/memories\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## CLI Flags\n\n| Flag | Description |\n|------|-------------|\n| `--setup` | Install Ollama and pull the embedding model (only needed for `EMBEDDING_PROVIDER=ollama`) |\n| `--setup-ui` | Clone and set up the [aibrain-ui](https://github.com/nkamau12/aibrain-ui) web dashboard |\n| `--setup-ui <path>` | Clone aibrain-ui into a custom directory (defaults to current directory) |\n\n---\n\n## Tools\n\n### `save_memory`\nSave a memory with content, summary, tags, and metadata.\n\n### `search_memories`\nHybrid BM25 + vector search. Falls back to fulltext if embeddings are unavailable.\n\n### `get_recent_memories`\nGet most recent memories, optionally filtered by agent, session, or project.\n\n### `get_memory`\nFetch full content of a memory by ID.\n\n### `delete_memory`\nDelete a memory by ID.\n\n### `list_tags`\nList all tags sorted by usage count.\n\n---\n\n## Embeddings\n\n### Default: Transformers.js (no setup required)\n\nEmbeddings run locally via [Transformers.js](https://huggingface.co/docs/transformers.js) using the `nomic-embed-text-v1` ONNX model.\n\n**On first run**, the model (~50MB) downloads automatically to `~/.cache/huggingface/hub`. You'll see:\n\n```\n[aibrain] Loading embedding model on first run (may download ~50MB to ~/.cache/huggingface)...\n[aibrain] Embedding model ready\n```\n\nEvery subsequent run loads the model from disk instantly — no network call.\n\n### Alternative: Ollama\n\nIf you prefer Ollama (e.g. you're already running it, or want GPU acceleration):\n\n```bash\n# Install Ollama and pull the model\nnpx -y @aibrain/mcp --setup\n\n# Then tell aibrain to use it\nEMBEDDING_PROVIDER=ollama npx -y @aibrain/mcp\n```\n\nOr set it permanently in your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibrain/mcp\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"ollama\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Agent Instructions\n\nInstalling the MCP server gives your AI agent access to the tools, but you also need to tell it **when and how to use them**. Add the instructions below to your agent's rules/instructions file.\n\n### Where to put them\n\n| Scope | Claude Code | Amp | Cursor |\n|-------|------------|-----|--------|\n| Global (all projects) | `~/.claude/CLAUDE.md` | `~/.config/amp/AGENTS.md` | `~/.cursor/rules` |\n| Project-local | `CLAUDE.md` in project root | `.amp/AGENTS.md` in project root | `.cursor/rules` in project root |\n\nUse **global** for general memory behaviour you always want. Use **project-local** to scope memories to a specific codebase or workflow.\n\n### Recommended instructions\n\nAdd this block to your chosen file:\n\n````markdown\n## Memory (aiBrain)\n\nAt the start of every session:\n1. Call `aibrain:get_recent_memories` (limit: 10, filter by current `projectPath`) — returns summaries only\n2. Call `aibrain:search_memories` with a query summarizing what the user just asked — returns summaries only\n3. For any result that looks relevant, call `aibrain:get_memory` with its `id` to fetch the full content\n\nDuring and after work, call `aibrain:save_memory` whenever you learn something worth remembering:\n- Decisions made and why\n- Bugs found and how they were fixed\n- Architecture patterns or conventions in this project\n- User preferences and feedback\n- External service details (API quirks, endpoint structures, config conventions)\n\nWhen saving:\n- `projectPath`: absolute path of the current working directory (or `\"\"` for global context)\n- `tags`: lowercase kebab-case (e.g. `bug-fix`, `architecture`, `user-preference`)\n- `summary`: under 200 chars — the tldr\n- `content`: full detail\n\nAt the end of every session, save one memory summarizing what was accomplished, what was left incomplete, and any important context for the next session.\n\nFor in-progress or incomplete work, still save a memory but include the tag `in-progress`. Update or delete it once the work is complete.\n\nDo NOT save: things already in the codebase, or git history.\n\n## Directory Exploration → aiBrain\n\nWhenever you read or explore a directory and discover new information (project structure, tech stack, conventions, dependencies, config patterns, etc.) that isn't already in aiBrain, save it immediately with `aibrain:save_memory`. Tag with `codebase-discovery` plus any relevant tags.\n\n## aiBrain Subagents\n\nRun all aiBrain operations (save, search, get, delete) as background subagents where possible, so they don't block the main conversation. Batch multiple saves into a single subagent call. Only await aiBrain results when the response directly depends on them (e.g. session-start memory load).\n````\n\n### Minimal version\n\nIf you want lighter-touch behaviour, this shorter version works well:\n\n````markdown\n## Memory (aiBrain)\n\n- At session start: call `aibrain:get_recent_memories` and `aibrain:search_memories` to load relevant context\n- During work: call `aibrain:save_memory` for decisions, bugs, conventions, and user preferences\n- At session end: save a summary of what was done and what's left\n- Always set `projectPath` to the current working directory when saving\n````\n\n---\n\n## Web Dashboard (aibrain-ui)\n\nBrowse, search, and manage your memories visually with **[aibrain-ui](https://github.com/nkamau12/aibrain-ui)** — a dark-themed web dashboard built on top of aibrain-mcp.\n\n### Automatic setup\n\n```bash\n# Clones aibrain-ui into current directory\nnpx -y @aibrain/mcp --setup-ui\n\n# Or specify a custom location\nnpx -y @aibrain/mcp --setup-ui ~/projects\n```\n\nThis clones aibrain-ui, installs dependencies, and creates the `.env` file. Then:\n\n```bash\ncd aibrain-ui\nnpm run dev\n```\n\nDashboard opens at [http://localhost:5173](http://localhost:5173).\n\n### Manual setup\n\nSee the [aibrain-ui README](https://github.com/nkamau12/aibrain-ui#readme) for manual installation instructions.\n\n---\n\n## Troubleshooting\n\n**Server doesn't start**\n- Ensure Node.js >= 20 is installed: `node --version`\n\n**First run is slow / hangs**\n- The embedding model is downloading (~50MB). Wait for `[aibrain] Embedding model ready` to appear. This only happens once.\n\n**Search returns no results**\n- Check that memories have been saved first via `get_recent_memories`\n- If using `EMBEDDING_PROVIDER=ollama`, verify Ollama is running: `curl http://localhost:11434/api/tags`\n\n**Embedding model fails to load**\n- Check you have internet access for the one-time download\n- Check available disk space (`~/.cache/huggingface` needs ~200MB for model files)\n- To force a re-download, delete `~/.cache/huggingface/hub/models--Xenova--nomic-embed-text-v1`\n\n**Ollama setup fails** (when using `EMBEDDING_PROVIDER=ollama`)\n- Run `EMBEDDING_PROVIDER=ollama npx -y @aibrain/mcp --setup` again — it's idempotent\n- Or install Ollama manually from [ollama.com](https://ollama.com), then `ollama pull nomic-embed-text`\n\n**Memories stored in wrong location**\n- Set `AIBRAIN_DATA_DIR` to your preferred path (see Configuration above)\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}