{"id":50219446,"url":"https://github.com/never00miss/allan-mcp-memory-code","last_synced_at":"2026-05-26T11:01:28.763Z","repository":{"id":359630675,"uuid":"1246564230","full_name":"never00miss/allan-mcp-memory-code","owner":"never00miss","description":"🧠 Knowledge Graph Memory for AI Coding Agents - Full offline mode with Docker. Integrates with Claude, Cline, Cursor, Windsurf, and more. Auto-extracts entities \u0026 relationships. No API keys required.","archived":false,"fork":false,"pushed_at":"2026-05-22T21:14:34.000Z","size":190,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T21:32:00.776Z","etag":null,"topics":["ai-agents","claude","cline","coding","cursor","docker","graphiti","knowledge-graph","llm","mcp","memory","offline-first","plan","token","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/never00miss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T10:14:03.000Z","updated_at":"2026-05-22T21:09:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/never00miss/allan-mcp-memory-code","commit_stats":null,"previous_names":["never00miss/allan-mcp-memory-code"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/never00miss/allan-mcp-memory-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/never00miss%2Fallan-mcp-memory-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/never00miss%2Fallan-mcp-memory-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/never00miss%2Fallan-mcp-memory-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/never00miss%2Fallan-mcp-memory-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/never00miss","download_url":"https://codeload.github.com/never00miss/allan-mcp-memory-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/never00miss%2Fallan-mcp-memory-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33517124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude","cline","coding","cursor","docker","graphiti","knowledge-graph","llm","mcp","memory","offline-first","plan","token","token-optimization"],"created_at":"2026-05-26T11:01:27.655Z","updated_at":"2026-05-26T11:01:28.754Z","avatar_url":"https://github.com/never00miss.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Allan MCP Memory Code\n\n🧠 Persistent knowledge graph memory for AI coding assistants (Claude, Cline, Cursor, Windsurf). Runs 100% offline with Docker. Auto-extracts entities \u0026 relationships from conversations.\n\n## Features\n\n- **Full Offline Mode** - No API keys required, runs entirely on local hardware\n- **Cloud Mode** - Use OpenRouter/OpenAI for low-resource machines (~$0.50/month)\n- Auto-extract entities + relationships from text\n- Hybrid search (text + vector) for nodes and facts\n- All-in-one Docker setup (FalkorDB + Ollama + LLM + Embedding)\n- Integrates with Claude, Cline, Kilo Code, Cursor, Windsurf, and more\n\n---\n\n## Quick Start (Offline)\n\n**No API keys required!** Everything runs locally.\n\n```bash\n# Clone the repository\ngit clone https://github.com/never00miss/allan-mcp-memory-code.git\ncd allan-mcp-memory-code\n\n# Start all services (FalkorDB + Ollama + Models)\ndocker compose up -d\n\n# First run downloads ~5GB of models (5-15 min depending on internet)\n# Wait until models are ready:\ndocker compose logs ollama-init -f\n\n# When you see \"All models ready!\", the service is available at:\n# http://localhost:19089\n```\n\n**That's it!** Now integrate with your AI coding assistant below.\n\n---\n\n## Quick Start (Cloud - OpenRouter)\n\n**Lightweight setup!** Only FalkorDB runs locally, LLM/Embedding via cloud.\n\n```bash\n# Clone the repository\ngit clone https://github.com/never00miss/allan-mcp-memory-code.git\ncd allan-mcp-memory-code\n\n# Start only FalkorDB (graph database)\ndocker compose up falkordb -d\n\n# Configure cloud API\ncp .env.example .env\n```\n\nEdit `.env` for OpenRouter:\n\n```env\n# LLM (OpenRouter)\nLLM_API_URL=https://openrouter.ai/api/v1\nLLM_API_KEY=sk-or-v1-your-key-here\nLLM_MODEL=qwen/qwen-2.5-7b-instruct\n\n# Embedding (OpenRouter or local Ollama)\nEMBEDDER_API_URL=https://openrouter.ai/api/v1\nEMBEDDER_API_KEY=sk-or-v1-your-key-here\nEMBEDDER_MODEL=openai/text-embedding-3-small\n\n# FalkorDB\nFALKORDB_URI=redis://localhost:6380\n```\n\n```bash\n# Install and run\nnpm install\nnpm start\n\n# Health check\ncurl http://localhost:19089/v1/health\n```\n\n### OpenRouter Cost Estimate (1 Hour Coding Session)\n\n| Activity | Requests | Tokens/Req | Total Tokens | Cost |\n|----------|----------|------------|--------------|------|\n| Entity extraction | ~20 | ~500 | ~10,000 | ~$0.002 |\n| Embedding generation | ~50 | ~100 | ~5,000 | ~$0.0001 |\n| Search queries | ~30 | ~200 | ~6,000 | ~$0.001 |\n| **Total per hour** | **~100** | - | **~21,000** | **~$0.003** |\n\n**Monthly estimate (8hr/day, 20 days):** ~$0.50\n\n\u003e 💡 **Tip:** Use `qwen/qwen-2.5-7b-instruct` ($0.00018/1K tokens) - extremely cheap and reliable for entity extraction.\n\n### Recommended Cloud Models\n\n| Provider | Model | Cost/1K tokens | Notes |\n|----------|-------|----------------|-------|\n| OpenRouter | `qwen/qwen-2.5-7b-instruct` | $0.00018 | **Best value** |\n| OpenRouter | `google/gemma-3-4b-it` | $0.00010 | Cheapest |\n| OpenRouter | `openai/gpt-4o-mini` | $0.00015 | High quality |\n| OpenAI | `gpt-4o-mini` | $0.00015 | Direct API |\n\n---\n\n## Integration\n\n### Claude Code (MCP Server) ⭐ Recommended\n\nUse MCP tools directly in Claude Code - shows up in `/mcp` command.\n\n\u003e **Important:** Always use `claude mcp add` to configure the MCP server. Do **NOT** manually edit `~/.claude/settings.json` or `~/.claude/mcp.json` for MCP config. Claude Code reads MCP settings from `~/.claude.json` (managed by the CLI), not from those files. Editing the wrong file will cause \"Connection closed\" errors.\n\n---\n\n#### Step 1: Prerequisites\n\n```bash\n# Start FalkorDB\ndocker compose up falkordb -d\n\n# Install \u0026 build allan-memory\ncd allan-mcp-memory-code\nnpm install\nnpm run build\nnpm link\n```\n\n#### Step 2: Setup Claude Code Config\n\nCopy the ready-made config files from `extensions/`:\n\n```bash\n# Copy hooks + CLAUDE.md\ncp -r extensions/.claude ~/.claude\nchmod +x ~/.claude/hooks/observe-read.sh ~/.claude/hooks/observe-edit.sh\n```\n\nThen edit the hook scripts — replace the placeholder env vars with your actual values:\n\n| Cloud (OpenRouter) | Local (Ollama) |\n|---|---|\n| `LLM_API_URL=https://openrouter.ai/api/v1` | `LLM_API_URL=http://localhost:11435/v1` |\n| `LLM_API_KEY=sk-or-v1-your-key-here` | `LLM_API_KEY=ollama` |\n| `LLM_MODEL=qwen/qwen-2.5-7b-instruct` | `LLM_MODEL=qwen2.5:7b-instruct` |\n| `EMBEDDER_API_URL=https://openrouter.ai/api/v1` | `EMBEDDER_API_URL=http://localhost:11435/v1` |\n| `EMBEDDER_API_KEY=sk-or-v1-your-key-here` | `EMBEDDER_API_KEY=ollama` |\n| `EMBEDDER_MODEL=openai/text-embedding-3-small` | `EMBEDDER_MODEL=nomic-embed-text` |\n\nAdd the `hooks` section to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"description\": \"Inject project-specific context\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo 'see allan-memory too and always do remember save'\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Read\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"/Users/YOUR_USER/.claude/hooks/observe-read.sh\",\n            \"timeout\": 30\n          }\n        ]\n      },\n      {\n        \"matcher\": \"Edit|Write|MultiEdit\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"/Users/YOUR_USER/.claude/hooks/observe-edit.sh\",\n            \"timeout\": 60\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n\u003e Replace `/Users/YOUR_USER` with your actual home directory path.\n\nThe `UserPromptSubmit` hook prepends a short reminder to every prompt so the assistant keeps using `recall` / `remember` instead of falling back to raw file search. It runs locally — no network calls, no secrets.\n\n#### Step 3: Add MCP Server\n\n**Local (Ollama):**\n```bash\nclaude mcp add allan-memory \\\n  -e FALKORDB_URI=redis://localhost:6380 \\\n  -e LLM_API_URL=http://localhost:11435/v1 \\\n  -e LLM_API_KEY=ollama \\\n  -e LLM_MODEL=qwen2.5:7b-instruct \\\n  -e EMBEDDER_API_URL=http://localhost:11435/v1 \\\n  -e EMBEDDER_API_KEY=ollama \\\n  -e EMBEDDER_MODEL=nomic-embed-text \\\n  -- node /full/path/to/allan-mcp-memory-code/dist/mcp-server.js\n```\n\n**Cloud (OpenRouter):**\n```bash\nclaude mcp add allan-memory \\\n  -e FALKORDB_URI=redis://localhost:6380 \\\n  -e FALKORDB_GRAPH_NAME=allan_memory \\\n  -e LLM_API_URL=https://openrouter.ai/api/v1 \\\n  -e LLM_API_KEY=sk-or-v1-your-key-here \\\n  -e LLM_MODEL=qwen/qwen-2.5-7b-instruct \\\n  -e EMBEDDER_API_URL=https://openrouter.ai/api/v1 \\\n  -e EMBEDDER_API_KEY=sk-or-v1-your-key-here \\\n  -e EMBEDDER_MODEL=openai/text-embedding-3-small \\\n  -- node /full/path/to/allan-mcp-memory-code/dist/mcp-server.js\n```\n\n**Hybrid (Local LLM + Cloud Embedding):**\n```bash\nclaude mcp add allan-memory \\\n  -e FALKORDB_URI=redis://localhost:6380 \\\n  -e LLM_API_URL=http://localhost:11435/v1 \\\n  -e LLM_API_KEY=ollama \\\n  -e LLM_MODEL=qwen2.5:7b-instruct \\\n  -e EMBEDDER_API_URL=https://openrouter.ai/api/v1 \\\n  -e EMBEDDER_API_KEY=sk-or-v1-your-key-here \\\n  -e EMBEDDER_MODEL=openai/text-embedding-3-small \\\n  -- node /full/path/to/allan-mcp-memory-code/dist/mcp-server.js\n```\n\n\u003e Replace `/full/path/to/allan-mcp-memory-code` with your actual path. The path must point to `dist/mcp-server.js`, **not** `lib/mcp-server.js`.\n\n**Remove MCP:**\n```bash\nclaude mcp remove allan-memory\n```\n\n---\n\n#### Step 4: Verify\n\n1. **Restart VS Code** completely (Cmd+Q, not just reload window)\n2. Type `/mcp` in Claude Code chat\n3. You should see `allan-memory` with 6 tools\n\n**Troubleshooting:**\n\n| Issue | Solution |\n|-------|----------|\n| \"Connection closed\" error | You likely edited `~/.claude/settings.json` manually. Run `claude mcp remove allan-memory` then re-add with `claude mcp add` |\n| \"SyntaxError: Cannot use import\" | Path points to `lib/` instead of `dist/`. Use `dist/mcp-server.js` |\n| MCP shows but tools don't work | FalkorDB not running. Start it: `docker compose up falkordb -d` |\n| MCP not showing in `/mcp` | Run `claude mcp list` to verify it's registered |\n\n#### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `register_project` | Register project root for path resolution and freshness |\n| `remember` | Store a memory with structured fields (type, scope, content) |\n| `recall` | Search with inline freshness (check `freshness.stale` on results!) |\n| `relate` | Find relationships between entities |\n| `list` | Enumerate stored entities by type |\n| `refresh` | Re-extract entities from a file (use when recall returns stale) |\n\n\u003cdetails\u003e\u003csummary\u003eLegacy Tools (backward compat)\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `add_memory` | Store knowledge (name, content, group_id) |\n| `search_nodes` | Search entities by query |\n| `search_facts` | Search relationships by query |\n| `regenerate_file` | Auto-extract entities from a source file |\n\n\u003c/details\u003e\n\n---\n\n\n### Claude Code (HTTP/curl Alternative)\n\nIf MCP doesn't work, use HTTP API with curl commands.\n\n#### Step 1: Allow curl Commands\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(curl*)\",\n      \"Bash(curl -s*)\",\n      \"Bash(curl -X POST http://localhost:19089*)\",\n      \"Bash(curl http://localhost:19089*)\"\n    ],\n    \"deny\": []\n  }\n}\n```\n\n#### Step 2: Add Instructions to CLAUDE.md\n\nCopy the ready-made instructions from `extensions/.claude/CLAUDE.md` to `~/.claude/CLAUDE.md`:\n\n```bash\ncp extensions/.claude/CLAUDE.md ~/.claude/CLAUDE.md\n```\n\nIf you have an existing `~/.claude/CLAUDE.md`, append the content manually.\n\n#### Step 3: Restart Claude Code\n\nAfter editing settings, **restart Claude Code completely** for changes to take effect.\n\n---\n\n### Prompt Tips for Auto-Triggering\n\nTo make Claude use memory tools automatically, use these phrases:\n\n| Phrase in Prompt | Triggers |\n|------------------|----------|\n| \"Check your memory first...\" | `search_nodes` before answering |\n| \"What do you remember about...?\" | `search_nodes` |\n| \"Remember this for later...\" | `add_memory` |\n| \"Search your knowledge of...\" | `search_nodes` |\n| \"What patterns have you seen in...?\" | `search_facts` |\n| \"Store this insight...\" | `add_memory` |\n| \"Before answering, check if...\" | `search_nodes` |\n\n#### Example Prompts:\n```\n\"Check your memory first, then explain the authentication flow\"\n\n\"What do you remember about the database schema?\"\n\n\"Remember this: the API uses JWT tokens with 24h expiry\"\n\n\"Search your knowledge of error handling patterns in this codebase\"\n```\n\n#### Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| MCP not showing in `/mcp` | Verify path is absolute, restart VS Code |\n| Popup for `curl` commands | Add `\"Bash(curl*)\"` to `permissions.allow` |\n| Server errors | Ensure Docker is running: `docker compose ps` |\n\n---\n\n### OpenClaw\n\nAllan Memory integrates with [OpenClaw](https://github.com/openclaw/openclaw) as a skill.\n\n#### Option 1: Install Skill from GitHub\n\n```bash\nopenclaw skills install git:never00miss/allan-mcp-memory-code@main --as allan-memory\n```\n\n#### Option 2: Copy Skill Locally\n\nCopy the `openclaw-skill/SKILL.md` file to your OpenClaw skills directory:\n\n```bash\nmkdir -p ~/.openclaw/skills/allan-memory\ncp openclaw-skill/SKILL.md ~/.openclaw/skills/allan-memory/SKILL.md\n```\n\n#### Configure MCP Server\n\nAdd to `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"allan-memory\": {\n        \"enabled\": true,\n        \"env\": {\n          \"FALKORDB_URI\": \"redis://localhost:6380\"\n        }\n      }\n    }\n  },\n  \"mcpServers\": {\n    \"allan-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"LLM_API_KEY\": \"your-openrouter-key\",\n        \"LLM_MODEL\": \"qwen/qwen-2.5-7b-instruct\",\n        \"EMBEDDING_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"EMBEDDING_API_KEY\": \"your-openrouter-key\",\n        \"EMBEDDING_MODEL\": \"openai/text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n#### Available Tools in OpenClaw\n\nOnce configured, you can use these tools in OpenClaw:\n\n- `add_memory` - Store knowledge (files, functions, patterns)\n- `search_nodes` - Find entities by semantic search\n- `search_facts` - Find relationships between entities\n- `check_freshness` - Verify stored knowledge isn't stale\n- `regenerate_file` - Update knowledge after file edits\n- `get_episodes` - List recent memory entries\n- `delete_episode` - Remove stale entries\n\nSee `openclaw-skill/SKILL.md` for detailed usage instructions.\n\n---\n\n### Cline (VS Code)\n\n#### Step 1: Add MCP Server\n\nAdd to Cline MCP settings (`cline_mcp_settings.json`):\n\n**Local (Ollama):**\n```json\n{\n  \"mcpServers\": {\n    \"allan-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"http://localhost:11435/v1\",\n        \"LLM_API_KEY\": \"ollama\",\n        \"LLM_MODEL\": \"qwen2.5:7b-instruct\",\n        \"EMBEDDER_API_URL\": \"http://localhost:11435/v1\",\n        \"EMBEDDER_API_KEY\": \"ollama\",\n        \"EMBEDDER_MODEL\": \"nomic-embed-text\"\n      }\n    }\n  }\n}\n```\n\n**Cloud (OpenRouter):**\n```json\n{\n  \"mcpServers\": {\n    \"allan-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"LLM_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"LLM_MODEL\": \"qwen/qwen-2.5-7b-instruct\",\n        \"EMBEDDER_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"EMBEDDER_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"EMBEDDER_MODEL\": \"openai/text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n#### Step 2: Add Custom Instructions\n\nGo to **Cline Settings → Custom Instructions** and add the content from `extensions/.claude/CLAUDE.md`.\n\nOr copy it directly:\n\n```bash\ncat extensions/.claude/CLAUDE.md\n```\n\n---\n\n### Kilo Code\n\n#### Step 1: Add MCP Server\n\nAdd to Kilo Code MCP settings:\n\n**Local (Ollama):**\n```json\n{\n  \"servers\": {\n    \"allan-memory\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"http://localhost:11435/v1\",\n        \"LLM_API_KEY\": \"ollama\",\n        \"LLM_MODEL\": \"qwen2.5:7b-instruct\",\n        \"EMBEDDER_API_URL\": \"http://localhost:11435/v1\",\n        \"EMBEDDER_API_KEY\": \"ollama\",\n        \"EMBEDDER_MODEL\": \"nomic-embed-text\"\n      }\n    }\n  }\n}\n```\n\n**Cloud (OpenRouter):**\n```json\n{\n  \"servers\": {\n    \"allan-memory\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"LLM_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"LLM_MODEL\": \"qwen/qwen-2.5-7b-instruct\",\n        \"EMBEDDER_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"EMBEDDER_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"EMBEDDER_MODEL\": \"openai/text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n#### Step 2: Add Custom Instructions\n\nGo to **Kilo Code Settings → Custom Instructions** and add the content from `extensions/.claude/CLAUDE.md`.\n\nOr copy it directly:\n\n```bash\ncat extensions/.claude/CLAUDE.md\n```\n\n---\n\n### Windsurf (Codeium)\n\n#### Step 1: Add MCP Server\n\nAdd to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):\n\n**Local (Ollama):**\n```json\n{\n  \"mcpServers\": {\n    \"allan-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"http://localhost:11435/v1\",\n        \"LLM_API_KEY\": \"ollama\",\n        \"LLM_MODEL\": \"qwen2.5:7b-instruct\",\n        \"EMBEDDER_API_URL\": \"http://localhost:11435/v1\",\n        \"EMBEDDER_API_KEY\": \"ollama\",\n        \"EMBEDDER_MODEL\": \"nomic-embed-text\"\n      }\n    }\n  }\n}\n```\n\n**Cloud (OpenRouter):**\n```json\n{\n  \"mcpServers\": {\n    \"allan-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/allan-mcp-memory-code/dist/mcp-server.js\"],\n      \"env\": {\n        \"FALKORDB_URI\": \"redis://localhost:6380\",\n        \"LLM_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"LLM_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"LLM_MODEL\": \"qwen/qwen-2.5-7b-instruct\",\n        \"EMBEDDER_API_URL\": \"https://openrouter.ai/api/v1\",\n        \"EMBEDDER_API_KEY\": \"sk-or-v1-your-key-here\",\n        \"EMBEDDER_MODEL\": \"openai/text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n#### Step 2: Add Global AI Rules\n\nGo to **Windsurf Settings → AI Rules → Global AI Rules** and add the content from `extensions/.claude/CLAUDE.md`.\n\nOr copy it directly:\n\n```bash\ncat extensions/.claude/CLAUDE.md\n```\n\n---\n\n### Cursor\n\nCreate `.cursorrules` in your project root with the content from `extensions/.claude/CLAUDE.md`.\n\nOr copy it directly:\n\n```bash\ncp extensions/.claude/CLAUDE.md .cursorrules\n```\n\n---\n\n### Continue.dev\n\n#### Step 1: Add Context Provider\n\nAdd to `~/.continue/config.json`:\n\n```json\n{\n  \"contextProviders\": [\n    {\n      \"name\": \"http\",\n      \"params\": {\n        \"url\": \"http://localhost:19089/v1/memory/search/nodes\",\n        \"method\": \"POST\",\n        \"headers\": { \"Content-Type\": \"application/json\" },\n        \"body\": { \"query\": \"{{{ input }}}\", \"limit\": 5 },\n        \"title\": \"Allan Memory\"\n      }\n    }\n  ]\n}\n```\n\n#### Step 2: Add System Message\n\nAdd to `~/.continue/config.json` under `models[].systemMessage`:\n\nUse the system instructions from [`extensions/.claude/CLAUDE.md`](extensions/.claude/CLAUDE.md), adapting the tool commands to use the HTTP API (`curl`) instead of MCP tools.\n\n---\n\n### GitHub Copilot\n\nCreate `.github/copilot-instructions.md` using the instructions from [`extensions/.claude/CLAUDE.md`](extensions/.claude/CLAUDE.md), adapting the tool commands to use the HTTP API (`curl`) instead of MCP tools.\n\n---\n\n### Generic HTTP API\n\n| Action | Method | Endpoint | Body |\n|--------|--------|----------|------|\n| Store | POST | `/v1/memory` | `{\"name\":\"...\",\"episode_body\":\"...\",\"group_id\":\"...\"}` |\n| Search Entities | POST | `/v1/memory/search/nodes` | `{\"query\":\"...\",\"limit\":10}` |\n| Search Relations | POST | `/v1/memory/search/facts` | `{\"query\":\"...\",\"limit\":10}` |\n| List Episodes | GET | `/v1/memory/episodes?group_id=...` | - |\n| Health Check | GET | `/v1/health` | - |\n\n---\n\n## Exposed Ports\n\n| Port | Service |\n|------|---------|\n| 19089 | Allan Memory API |\n| 6380 | FalkorDB (Redis protocol) |\n| 3001 | FalkorDB Web UI |\n| 11435 | Ollama API |\n\n---\n\n## Hardware Requirements\n\n### Minimum\n\n| Component | Requirement |\n|-----------|-------------|\n| **RAM** | 16GB |\n| **Storage** | 15GB free |\n| **CPU** | 4+ cores |\n\n### Model Sizes\n\n| Model | Download | RAM Usage |\n|-------|----------|-----------|\n| nomic-embed-text | ~270MB | ~500MB |\n| qwen2.5:7b-instruct | ~4.7GB | ~6GB |\n| **Total** | **~5GB** | **~6.5GB** |\n\n### Tested Platforms\n\n| Platform | Performance |\n|----------|-------------|\n| MacBook Pro M2 16GB | ✅ Smooth (~10 tok/s) |\n| MacBook Pro M1 16GB | ✅ Good (~8 tok/s) |\n| Linux + RTX 3060 | ✅ Fast (~25 tok/s) |\n| Linux + RTX 4090 | ✅ Very fast (~40 tok/s) |\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | 19089 | Service port |\n| `LLM_API_URL` | http://localhost:11435/v1 | LLM endpoint |\n| `LLM_MODEL` | qwen2.5:7b-instruct | LLM model for MCP tools (recall, relate, etc.) |\n| `EMBEDDER_API_URL` | http://localhost:11435/v1 | Embedding endpoint |\n| `EMBEDDER_MODEL` | nomic-embed-text | Embedding model |\n| `FALKORDB_URI` | redis://localhost:6380 | FalkorDB connection |\n| `OBSERVE_LLM` | true | Enable LLM extraction for observe hooks (set `false` for regex-only) |\n| `OBSERVE_LLM_MODEL` | *(same as LLM_MODEL)* | Cheaper model for observe hooks (e.g. `deepseek/deepseek-v4-flash`) |\n| `HASH_CACHE_LIMIT` | 3000 | Max file hashes to track for skip-if-unchanged |\n| `ALLAN_MEMORY_DEBOUNCE_SECONDS` | 60 | Observe hook debounce — wait this long after last read/edit before extracting |\n| `ALLAN_MEMORY_DEBOUNCE_DIR` | /tmp/allan-memory-debounce | Where the debounce state markers are stored |\n\n### Observe Hook Hash Cache\n\nObserve hooks use a **content hash cache** (`~/.allan-memory/hashes.json`) to skip reprocessing unchanged files:\n\n- `observe-read`: computes MD5 of file content, **skips** if hash matches a previous run\n- `observe-edit`: **always processes** (file was edited), updates hash so next read skips\n- Cache is capped at `HASH_CACHE_LIMIT` entries (default 3000), evicts oldest when full\n\n### Observe Hook Debouncing (Async)\n\nThe shipped `observe-read.sh` / `observe-edit.sh` hooks are **non-blocking** — they record a marker and exit in ~150ms, then a backgrounded worker waits `ALLAN_MEMORY_DEBOUNCE_SECONDS` (default 60s) before invoking the CLI.\n\nIf the same file is touched again within the debounce window, the older worker bails and only the newest one runs. Net effect:\n\n```text\nedit foo.js → edit foo.js → edit foo.js   (within 60s)\n                                       └─► one extraction, 60s after the last edit\n```\n\nThis avoids piling up LLM calls when the assistant edits the same file repeatedly. Set `ALLAN_MEMORY_DEBOUNCE_SECONDS=0` to disable (still async).\n\n### Observe Hook LLM Models\n\nThe observe hooks (triggered on every file read/edit) can use a **separate, cheaper model** than your main MCP tools:\n\n| Provider | Model | Input/1M | Output/1M | Notes |\n| --- | --- | --- | --- | --- |\n| **OpenRouter** | `deepseek/deepseek-v4-flash` | $0.10 | $0.20 | Best quality/price |\n| **OpenRouter** | `deepseek/deepseek-v4-flash:free` | $0.00 | $0.00 | Free tier |\n| **OpenRouter** | `google/gemma-4-31b-it:free` | $0.00 | $0.00 | Free tier, strong code |\n| **OpenRouter** | `qwen/qwen3.5-9b` | $0.04 | $0.15 | Very cheap |\n| **Ollama** | `qwen2.5:7b-instruct` | Free | Free | Local, ~8 tok/s on M2 |\n| **Ollama** | `qwen2.5:3b-instruct` | Free | Free | Fastest local option |\n| **Ollama** | `gemma3:4b` | Free | Free | Good for extraction |\n| **Disabled** | *(set `OBSERVE_LLM=false`)* | - | - | Regex-only, instant |\n\n\u003e **Tip**: For observe hooks, you only need simple JSON extraction — a small/cheap model works great. Your main `LLM_MODEL` handles the complex MCP tool calls.\n\n---\n\n## Use Cases \u0026 Benchmark\n\n### Quick Summary\n\n| Scenario | Queries | Token Savings | Cost Savings |\n|----------|---------|---------------|--------------|\n| Single Function Query | 1 | -7% | -7% |\n| Repeated Queries (Same File) | 5 | **74%** | 74% |\n| Cross-File Queries | 5 | **78%** | 78% |\n| Full Codebase Exploration | 10 | **88%** | 88% |\n| Long Coding Session | 20 | **94%** | 94% |\n\n\u003e **Break-even: 2 queries** — MCP pays for itself after just 2 queries about the same code.\n\n### Live MCP Performance\n\nMeasured on localhost with FalkorDB + OpenRouter (qwen/qwen-2.5-7b-instruct):\n\n| Operation | Time | Notes |\n|-----------|------|-------|\n| `add_memory` | **17ms** | Episode storage (LLM extraction is async) |\n| `search_nodes` | **765ms** | Hybrid search (text + vector + embeddings) |\n| `search_facts` | **410ms** | Relationship search |\n| `check_freshness` | **358ms** | Staleness detection |\n\n### Detailed Scenario Comparison\n\n#### 1. Single Function Query\n*1 query about one function — MCP has slight overhead*\n\n| Metric | Without MCP | With MCP | Savings |\n|--------|-------------|----------|---------|\n| Input Tokens | 3,400 | 3,650 | -7.4% |\n| File Reads | 1 | 1 | 0 saved |\n| Est. Cost (Claude 3.5) | $0.0177 | $0.0185 | -4.2% |\n\n#### 2. Repeated Queries (Same File)\n*5 queries about the same file — MCP wins big*\n\n| Metric | Without MCP | With MCP | Savings |\n|--------|-------------|----------|---------|\n| Input Tokens | 17,000 | 4,450 | **73.8%** |\n| File Reads | 5 | 1 | 4 saved |\n| Memory Cache Hits | 0 | 4 | - |\n| Est. Cost (Claude 3.5) | $0.0885 | $0.0508 | **42.5%** |\n\n#### 3. Cross-File Queries\n*5 queries across 4 different files*\n\n| Metric | Without MCP | With MCP | Savings |\n|--------|-------------|----------|---------|\n| Input Tokens | 86,000 | 19,300 | **77.6%** |\n| File Reads | 20 | 4 | 16 saved |\n| Memory Cache Hits | 0 | 4 | - |\n| Est. Cost (Claude 3.5) | $0.2955 | $0.0954 | **67.7%** |\n\n#### 4. Full Codebase Exploration\n*10 queries exploring entire codebase (6 files)*\n\n| Metric | Without MCP | With MCP | Savings |\n|--------|-------------|----------|---------|\n| Input Tokens | 248,000 | 28,600 | **88.5%** |\n| File Reads | 60 | 6 | 54 saved |\n| Memory Cache Hits | 0 | 9 | - |\n| Est. Cost (Claude 3.5) | $0.8190 | $0.1608 | **80.4%** |\n\n#### 5. Long Coding Session\n*Simulates 1-hour session with 20 queries*\n\n| Metric | Without MCP | With MCP | Savings |\n|--------|-------------|----------|---------|\n| Input Tokens | 496,000 | 30,600 | **93.8%** |\n| File Reads | 120 | 6 | 114 saved |\n| Memory Cache Hits | 0 | 19 | - |\n| Est. Cost (Claude 3.5) | $1.6380 | $0.2418 | **85.2%** |\n\n### Break-Even Analysis\n\n```\nQuery 1: MCP has slight overhead (storing knowledge)\n  Without MCP: ~3,200 tokens (read file)\n  With MCP:    ~3,350 tokens (read + store)\n  Result: MCP slightly more expensive\n\nQuery 2: MCP wins\n  Without MCP: ~3,200 tokens (read file again)\n  With MCP:    ~100 tokens (search_nodes hit)\n  Cumulative:  6,400 vs 3,450 tokens\n\nQuery 3+: MCP advantage compounds\n  Each additional query saves ~3,100 tokens\n```\n\n### When to Use MCP\n\n| Scenario | Recommendation | Expected Savings |\n|----------|----------------|------------------|\n| Single one-off question | ❌ Skip MCP | - |\n| 2-5 related questions | ✅ Use MCP | 50-80% |\n| Long coding session (1hr+) | ✅ Use MCP | 80-95% |\n| Large codebase (50+ files) | ✅ Use MCP | 90%+ |\n| Team with shared memory | ✅ Use MCP | 95%+ |\n\n### Run Benchmark Yourself\n\n```bash\ncd allan-mcp-memory-code\nnode benchmark.js\n```\n\n---\n\n## Freshness Checking\n\nWhen code changes, stored memories become **stale**. Use `check_freshness` to detect this.\n\n### How It Works\n\n```\n1. AI calls check_freshness({ query, group_id, max_age_hours })\n                              │\n                              ▼\n2. Generate query embedding via Ollama/OpenRouter\n                              │\n                              ▼\n3. Hybrid search in FalkorDB (text + vector)\n                              │\n                              ▼\n4. For each result, calculate age:\n   - age = now - created_at\n   - status = age \u003c max_age_hours ? FRESH : STALE\n                              │\n                              ▼\n5. Return formatted results:\n   \n   ---\n   Found 3 memories: 2 FRESH, 1 STALE (threshold: 24h)\n   login [FUNCTION] FRESH 2h ago | src/auth.js\n   validateToken [FUNCTION] FRESH 5h ago | src/auth.js  \n   hashPassword [FUNCTION] STALE 3d ago | src/crypto.js\n                              │\n                              ▼\n6. AI decides:\n   - FRESH → Trust memory, use directly\n   - STALE → Re-read file, update with add_memory\n```\n\n### MCP Tool Usage\n\n```javascript\n// Check freshness before using cached knowledge\ncheck_freshness({\n  query: \"auth functions\",\n  group_id: \"my-project\",\n  max_age_hours: 24  // optional, default 24\n})\n```\n\n### HTTP API Usage\n\n```bash\ncurl -X POST http://localhost:19089/v1/memory/check-freshness \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"auth functions\",\"group_id\":\"my-project\",\"max_age_hours\":24}'\n```\n\n### Best Practice Workflow\n\n```\n1. search_nodes(\"function X\")\n2. Results found?\n   ├─ Yes → check_freshness(\"function X\")\n   │        ├─ FRESH → Use memory ✓\n   │        └─ STALE → regenerate_file(file_path) OR re-read → add_memory\n   └─ No → Read file → add_memory (create)\n```\n\n---\n\n## File Regeneration\n\nAfter editing a file, use `regenerate_file` to automatically update the knowledge graph.\n\n### How It Works\n\n```\n1. AI calls regenerate_file({ file_path, project_root, group_id })\n                              │\n                              ▼\n2. MCP reads file content from disk\n                              │\n                              ▼\n3. Check .gitignore / .dockerignore (skip if matched)\n                              │\n                              ▼\n4. LLM extracts structured entities:\n   - File: purpose, exports, dependencies\n   - Functions: name, line numbers, signature, description\n                              │\n                              ▼\n5. Sync with knowledge graph:\n   - CREATE new entities for new functions\n   - UPDATE existing entities if changed\n   - DELETE entities for removed functions\n                              │\n                              ▼\n6. Return summary:\n   {\n     \"file_path\": \"src/auth.js\",\n     \"status\": \"success\",\n     \"created\": [\"func:project:src/auth.js:10-45@login\"],\n     \"updated\": [\"file:project:src/auth.js\"],\n     \"deleted\": [\"func:project:src/auth.js:80-100@oldFunc\"]\n   }\n```\n\n### MCP Tool Usage\n\n```javascript\n// After editing a file, regenerate its entities\nregenerate_file({\n  file_path: \"src/auth/login.js\",      // relative or absolute\n  project_root: \"/path/to/project\",    // project root directory\n  group_id: \"my-project\"               // required\n})\n```\n\n### HTTP API Usage\n\n```bash\ncurl -X POST http://localhost:19089/v1/memory/regenerate-file \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"file_path\":\"src/auth.js\",\"project_root\":\"/path/to/project\",\"group_id\":\"my-project\"}'\n```\n\n### Ignored Files\n\nRespects `.gitignore` and `.dockerignore` patterns, plus:\n- `node_modules/`\n- `.git/`\n- `dist/`, `build/`\n- `*.min.js`, `*.map`\n- `package-lock.json`, `yarn.lock`\n\n---\n\n## Local Development\n\n```bash\n# Start dependencies only\ndocker compose up falkordb ollama ollama-init -d\n\n# Run locally\ncp .env.example .env\nnpm install\nnpm run build   # Compile lib/ → dist/ (Babel transpilation)\nnpm run dev     # Dev server with nodemon (auto-transpiles via @babel/register)\nnpm start       # Production (runs transpiled dist/)\n```\n\n\u003e **Note:** The `lib/` source uses ES module `import` syntax. Always run `npm run build` before `npm start`. The `dev` script handles transpilation on-the-fly via `@babel/register`.\n\n---\n\n## Architecture\n\n```\nlib/\n├── index.js                # Entry point\n├── domain/                 # Entities + Repository Interfaces\n├── application/use_cases/  # Business logic\n├── interface/              # Controllers, Routes, Repositories\n└── infrastructure/         # Gateways (FalkorDB, LLM, Embedder)\n```\n\n## License\n\n[GNU AGPL-3.0](LICENSE) — you may use, modify, and redistribute this software, but any redistribution or network/SaaS deployment must release the complete corresponding source (including your modifications) under the same license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnever00miss%2Fallan-mcp-memory-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnever00miss%2Fallan-mcp-memory-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnever00miss%2Fallan-mcp-memory-code/lists"}