{"id":31537712,"url":"https://github.com/lcbcfoo/heimdall-mcp-server","last_synced_at":"2025-10-04T08:10:42.260Z","repository":{"id":300658965,"uuid":"1005217706","full_name":"lcbcFoo/heimdall-mcp-server","owner":"lcbcFoo","description":"Your AI Coding Assistant's Long-Term Memory","archived":false,"fork":false,"pushed_at":"2025-09-21T23:44:18.000Z","size":82488,"stargazers_count":80,"open_issues_count":0,"forks_count":16,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-28T04:23:33.193Z","etag":null,"topics":["assistant-chat-bots","claude","claude-code","cognitive","llm","mcp-server","memory"],"latest_commit_sha":null,"homepage":"","language":"Python","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/lcbcFoo.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}},"created_at":"2025-06-19T21:47:10.000Z","updated_at":"2025-09-27T21:39:55.000Z","dependencies_parsed_at":"2025-06-23T00:31:48.969Z","dependency_job_id":null,"html_url":"https://github.com/lcbcFoo/heimdall-mcp-server","commit_stats":null,"previous_names":["lcbcfoo/heimdall-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lcbcFoo/heimdall-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcbcFoo%2Fheimdall-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcbcFoo%2Fheimdall-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcbcFoo%2Fheimdall-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcbcFoo%2Fheimdall-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lcbcFoo","download_url":"https://codeload.github.com/lcbcFoo/heimdall-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcbcFoo%2Fheimdall-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278283509,"owners_count":25961311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["assistant-chat-bots","claude","claude-code","cognitive","llm","mcp-server","memory"],"created_at":"2025-10-04T08:10:37.584Z","updated_at":"2025-10-04T08:10:42.252Z","avatar_url":"https://github.com/lcbcFoo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heimdall MCP Server - Your AI Coding Assistant's Long-Term Memory\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/heimdall-mcp/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](hhttps://github.com/lcbcFoo/heimdall-mcp-server/blob/main/README.mdttps://opensource.org/licenses/Apache-2.0)\n[![MCP Protocol](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io/)\n[![Heimdall Demo Video](https://img.shields.io/badge/YouTube-red)](https://youtu.be/7X1gntAXsao)\n![PyPI - Version](https://img.shields.io/pypi/v/heimdall-mcp)\n\n\n**The Problem:** Your AI coding assistant has short-lived memory. Every chat session starts from a blank slate.\n\n**The Solution:** Heimdall gives your LLM a persistent, growing, cognitive memory of your specific codebase, lessons and memories carry over time.\n\n\nhttps://github.com/user-attachments/assets/120b3d32-72d1-4d42-b3ab-285e8a711981\n\n\n## Key Features\n\n- 🧠 **Context-Rich Memory**: Heimdall learns from your documentation, session insights, and development history, allowing your LLM to recall specific solutions and architectural patterns across conversations.\n- 📚 **Git-Aware Context**: It indexes your project's entire git history, understanding not just what changed, but also who changed it, when, and context.\n- 🔗 **Isolated \u0026 Organized**: Each project gets its own isolated memory space, ensuring that context from one project doesn't leak into another.\n- ⚡ **Efficient Integration**: Built on the Model Context Protocol (MCP), it provides a standardized, low-overhead way for LLMs to access this powerful memory.\n\n## 🚀 Getting Started\n\n**Prerequisites**: Python 3.11+ and Docker (for Qdrant vector database).\n\nHeimdall provides a unified `heimdall` CLI that manages everything from project setup to MCP integration.\n\n### 1. Install Heimdall\n\n```bash\npip install heimdall-mcp\n```\n\nThis installs the `heimdall` command-line tool with all necessary dependencies.\n\n### 2. Initialize Your Project\n\nNavigate to your project directory and set up Heimdall:\n\n```bash\ncd /path/to/your/project\n\n# Initialize project memory (starts Qdrant, creates collections, sets up config)\nheimdall project init\n```\n\nThis single command interactively builds up everything asking user preferences:\n- ✅ Starts Qdrant vector database automatically\n- ✅ Creates project-specific memory collections\n- ✅ Sets up `.heimdall/` configuration directory\n- ✅ Downloads required AI models\n- ✅ File monitoring\n- ✅ Git hooks\n- ✅ MCP integration\n\n**Note: this creates a `.heimdall/` directory in your project for configuration - you should NOT commit this - add to .gitignore!**\n\n## Load Project Knowledge\n\n**Recommended: Use automatic file monitoring** and place files in `.heimdall/docs/`:\n\n```bash\n# Copy or symlink your documentation to the monitored directory\nln -r -s my-project-docs ./.heimdall/docs/project-docs\n\n# Start automatic monitoring (files are loaded instantly when changed)\nheimdall monitor start\n```\n\n**Alternative: Manual loading** for one-time imports:\n\n```bash\n# Load documentation and files manually\nheimdall load docs/ --recursive\nheimdall load README.md\n```\n\nYour project's memory is now active and ready for your LLM.\n\n#### Real-time Git Integration\n\nYou can parse your entire git history with:\n\n```bash\n# Load git commit history\nheimdall git-load .\n```\n\nYou can also install git hooks for automatic memory updates on commits:\n\n```bash\n# Install the post-commit hook (Python-based, cross-platform)\nheimdall git-hooks install\n```\n\n**Note**: If you have existing post-commit hooks, they'll be safely chained and preserved - but proceed carefully.\n\n\n## 🧹 Cleanup\n\nTo remove Heimdall from a project:\n\n```bash\n# Navigate to the project you want to clean up\ncd /path/to/project\n\n# Cleanup data, remove collections, uninstall git hooks\nmemory_system project clean\n```\n\nThis cleanly removes project-specific data while preserving the shared Qdrant instance for other projects.\n\n## ⚙️ How It Works Under the Hood\n\nHeimdall extracts unstructured knowledge from your documentation and structured data from your git history. This information is vectorized and stored in a Qdrant database. The LLM can then query this database using a simple set of tools to retrieve relevant, context-aware information.\n\n```mermaid\ngraph TD\n    %% Main client outside the server architecture\n    AI_Assistant[\"🤖 AI Assistant (e.g., Claude)\"]\n\n    %% Top-level subgraph for the entire server\n    subgraph Heimdall MCP Server Architecture\n\n        %% 1. Application Interface Layer\n        subgraph Application Interface\n            MCP_Server[\"MCP Server (heimdall-mcp)\"]\n            CLI[\"CognitiveCLI (heimdall/cli.py)\"]\n            style MCP_Server fill:#b2ebf2,stroke:#00acc1,color:#212121\n            style CLI fill:#b2ebf2,stroke:#00acc1,color:#212121\n        end\n\n        %% 2. Core Logic Engine\n        style Cognitive_System fill:#ccff90,stroke:#689f38,color:#212121\n        Cognitive_System[\"🧠 CognitiveSystem (core/cognitive_system.py)\u003cbr/\u003e\"]\n\n        %% 3. Storage Layer (components side-by-side)\n        subgraph Storage Layer\n            Qdrant[\"🗂️ Qdrant Storage\u003cbr/\u003e\u003chr/\u003e- Vector Similarity Search\u003cbr/\u003e- Multi-dimensional Encoding\"]\n            SQLite[\"🗃️ SQLite Persistence\u003cbr/\u003e\u003chr/\u003e- Memory Metadata \u0026 Connections\u003cbr/\u003e- Caching \u0026 Retrieval Stats\"]\n        end\n\n        %% 4. Output Formatting\n        style Formatted_Response fill:#fff9c4,stroke:#fbc02d,color:#212121\n        Formatted_Response[\"📦 Formatted MCP Response\u003cbr/\u003e\u003ci\u003e{ core, peripheral }\u003c/i\u003e\"]\n\n        %% Define internal flow\n        MCP_Server -- calls --\u003e CLI\n        CLI -- calls --\u003e Cognitive_System\n\n        Cognitive_System -- \"1\\. Vector search for candidates\" --\u003e Qdrant\n        Cognitive_System -- \"2\\. Hydrates with metadata\" --\u003e SQLite\n        Cognitive_System -- \"3\\. Performs Bridge Discovery\" --\u003e Formatted_Response\n\n    end\n\n    %% Define overall request/response flow between client and server\n    AI_Assistant -- \"recall_memorie\" --\u003e MCP_Server\n    Formatted_Response -- \"Returns structured memories\" --\u003e AI_Assistant\n\n    %% --- Styling Block ---\n\n    %% 1. Node Styling using Class Definitions\n    classDef aiClientStyle fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a\n    classDef interfaceNodeStyle fill:#cffafe,stroke:#22d3ee,color:#0e7490\n    classDef coreLogicStyle fill:#dcfce7,stroke:#4ade80,color:#166534\n    classDef qdrantNodeStyle fill:#ede9fe,stroke:#a78bfa,color:#5b21b6\n    classDef sqliteNodeStyle fill:#fee2e2,stroke:#f87171,color:#991b1b\n    classDef responseNodeStyle fill:#fef9c3,stroke:#facc15,color:#854d0e\n\n    %% 2. Assigning Classes to Nodes\n    class AI_Assistant aiClientStyle\n    class MCP_Server,CLI interfaceNodeStyle\n    class Cognitive_System coreLogicStyle\n    class Qdrant qdrantNodeStyle\n    class SQLite sqliteNodeStyle\n    class Formatted_Response responseNodeStyle\n\n    %% 3. Link (Arrow) Styling\n    %% Note: Styling edge label text is not reliably supported. This styles the arrow lines themselves.\n    %% Primary request/response flow (links 0 and 1)\n    linkStyle 0,1 stroke:#3b82f6,stroke-width:2px\n    %% Internal application calls (links 2 and 3)\n    linkStyle 2,3 stroke:#22d3ee,stroke-width:2px,stroke-dasharray: 5 5\n    %% Internal data access calls (links 4 and 5)\n    linkStyle 4,5 stroke:#9ca3af,stroke-width:2px\n    %% Final processing call (link 6)\n    linkStyle 6 stroke:#4ade80,stroke-width:2px\n\n```\n\n## LLM Tool Reference\n\nYou can instruct your LLM to use the following six tools to interact with its memory:\n\n| Tool              | Description                                                          |\n| :---------------- | :------------------------------------------------------------------- |\n| `store_memory`    | Stores a new piece of information, such as an insight or a solution. |\n| `recall_memories` | Performs a semantic search for relevant memories based on a query.   |\n| `session_lessons` | Records a key takeaway from the current session for future use.      |\n| `memory_status`   | Checks the health and statistics of the memory system.               |\n| `delete_memory`   | Delete a specific memory by its unique ID.                          |\n| `delete_memories_by_tags` | Delete all memories that have any of the specified tags.    |\n\n\n## 💡 Best Practices\n\nTo maximize the effectiveness of Heimdall:\n\n  * **Provide Quality Documentation:** Think architecture decision records, style guides, and API documentation.\n  * **Keep documents updated:** Heilmdall will use documents in `.heimdall/docs` to provide memories - if they are outdated, so will be the memories. We suggest you use symbolic links to your actual docs directory in `.heimdall/docs` so Heimdall automatically refreshes memories with latest document versions.\n  * **Maintain Good Git Hygiene:** Write clear and descriptive commit messages. A message like `feat(api): add user authentication endpoint` is far more valuable than `more stuff`.\n  * **Set Up Automation:** Use `heimdall monitor start` and `heimdall git-hooks install` for hands-free memory updates.\n  * **Guide Your Assistant:** Use a system prompt (like a `CLAUDE.md` file) to instruct your LLM on *how* and *when* to use the available memory tools.\n  * **Use Strategic Tagging:** Establish rules for your LLM to tag memories consistently. Use temporary tags like `temp-analysis`, `task-specific`, or `cleanup-after-project` for memories that should be deleted after completion, enabling easy cleanup with `delete_memories_by_tags`.\n\n## 🛠️ Command Reference\n\n### Core Commands\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall store \u003ctext\u003e` | Store experience in cognitive memory |\n| `heimdall recall \u003cquery\u003e` | Retrieve relevant memories based on query |\n| `heimdall load \u003cpath\u003e` | Load files/directories into memory |\n| `heimdall git-load [repo]` | Load git commit patterns into memory |\n| `heimdall status` | Show system status and memory statistics |\n| `heimdall remove-file \u003cpath\u003e` | Remove memories for deleted file |\n| `heimdall delete-memory \u003cid\u003e` | Delete specific memory by ID |\n| `heimdall delete-memories-by-tags --tag \u003ctag\u003e` | Delete memories by tags |\n| `heimdall doctor` | Run comprehensive health checks |\n| `heimdall shell` | Start interactive memory shell |\n\n### Project Management\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall project init` | Initialize project memory with interactive setup |\n| `heimdall project list` | List all projects in shared Qdrant instance |\n| `heimdall project clean` | Remove project collections and cleanup |\n\n### Vector Database (Qdrant)\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall qdrant start` | Start Qdrant vector database service |\n| `heimdall qdrant stop` | Stop Qdrant service |\n| `heimdall qdrant status` | Check Qdrant service status |\n| `heimdall qdrant logs` | View Qdrant service logs |\n\n### File Monitoring\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall monitor start` | Start automatic file monitoring service |\n| `heimdall monitor stop` | Stop file monitoring service |\n| `heimdall monitor restart` | Restart monitoring service |\n| `heimdall monitor status` | Check monitoring service status |\n| `heimdall monitor health` | Detailed monitoring health check |\n\n### Git Integration\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall git-hook install` | Install post-commit hook for automatic memory processing |\n| `heimdall git-hook uninstall` | Remove Heimdall git hooks |\n| `heimdall git-hook status` | Check git hook installation status |\n\n### MCP Integration\n\n| Command | Description |\n| :------ | :---------- |\n| `heimdall mcp install \u003cplatform\u003e` | Install MCP server for platform (vscode, cursor, claude-code, visual-studio, codex) |\n| `heimdall mcp remove \u003cplatform\u003e` | Remove MCP integration from platform |\n| `heimdall mcp status` | Show installation status for all platforms |\n| `heimdall mcp list` | List available platforms and installation status |\n| `heimdall mcp generate \u003cplatform\u003e` | Generate configuration snippets for manual installation |\n\n#### Platforms\n\nHeimdall MCP server is compatible with any platform that supports STDIO MCP servers. The following platforms are supported for automatic installation using `heimdall mcp` commands.\n\n- `vscode` - Visual Studio Code\n- `cursor` - Cursor IDE\n- `claude-code` - Claude Code\n- `visual-studio` - Visual Studio\n- `codex` - Codex CLI (project-local CODEX_HOME config)\n\n## Technology Stack:\n\n- Python 3.11+\n- Vector Storage: Qdrant\n- Mmeory information and metadata: SQLite\n- Embeddings: all-MiniLM-L6-v2\n- Sentiment analysis: NRCLex emotion lexicon\n- Semantic analysis: spaCy\n- Integration: Model Context Protocol (MCP)\n\n## 🗺️Short Term Roadmap\n\n  * [x] ~~Git `post-commit` hook for automatic, real-time memory updates~~ ✅ **Completed**\n  * [x] ~~Watcher to auto-detect and load new documents in the `.heimdall-mcp` directory.~~ ✅ **Completed**\n  * [x] ~~Release v0.1.0 publicly~~ ✅ **Completed**\n  * [x] ~~Heimdall pip package available~~ ✅ **Completed**\n  * [x] ~~Simplify installation~~ ✅ **Completed**\n  * [x] ~~Delete memories support (manually or by tags - for md docs already supported)~~ ✅ **Completed**\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Setting up the development environment\n- Our dual licensing model\n- Code style guidelines\n- Pull request process\n\n**Important:** All contributors must agree to our [Contributor License Agreement](CLA.md) before their contributions can be merged.\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch targeting `dev` (not `main`)\n3. Make your changes following our style guidelines\n4. Submit a pull request with the provided template\n5. Sign the CLA when prompted by the CLA Assistant\n\nFor questions, open an issue or start a discussion!\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License for open source use. See our [Contributing Guide](CONTRIBUTING.md) for information about our dual licensing model for commercial applications.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcbcfoo%2Fheimdall-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flcbcfoo%2Fheimdall-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcbcfoo%2Fheimdall-mcp-server/lists"}