Skip to content
Back to search

heimdall-mcp-server

Your AI Coding Assistant's Long-Term Memory

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lcbcfoo--heimdall-mcp-server/badge.svg)](/listings/lcbcfoo--heimdall-mcp-server)

HTML

<a href="/listings/lcbcfoo--heimdall-mcp-server"><img src="/api/listings/lcbcfoo--heimdall-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites**: Python 3.11+ and Docker (for Qdrant vector database).

Heimdall provides a unified `heimdall` CLI that manages everything from project setup to MCP integration.

1. Install Heimdall

pip install heimdall-mcp

This installs the `heimdall` command-line tool with all necessary dependencies.

2. Initialize Your Project

Navigate to your project directory and set up Heimdall:

cd /path/to/your/project

# Initialize project memory (starts Qdrant, creates collections, sets up config)
heimdall project init

This single command interactively builds up everything asking user preferences: - ✅ Starts Qdrant vector database automatically - ✅ Creates project-specific memory collections - ✅ Sets up `.heimdall/` configuration directory - ✅ Downloads required AI models - ✅ File monitoring - ✅ Git hooks - ✅ MCP integration

**Note: this creates a `.heimdall/` directory in your project for configuration - you should NOT commit this - add to .gitignore!**

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 334 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Heimdall MCP Server - Your AI Coding Assistant's Long-Term Memory
  2. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/heimdall-mcp/)
  3. [![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)
  4. [![MCP Protocol](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io/)
  5. [![Heimdall Demo Video](https://img.shields.io/badge/YouTube-red)](https://youtu.be/7X1gntAXsao)
  6. ![PyPI - Version](https://img.shields.io/pypi/v/heimdall-mcp)
  7. **The Problem:** Your AI coding assistant has short-lived memory. Every chat session starts from a blank slate.
  8. **The Solution:** Heimdall gives your LLM a persistent, growing, cognitive memory of your specific codebase, lessons and memories carry over time.
  9. https://github.com/user-attachments/assets/120b3d32-72d1-4d42-b3ab-285e8a711981
  10. ## Key Features
  11. - 🧠 **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.
  12. - 📚 **Git-Aware Context**: It indexes your project's entire git history, understanding not just what changed, but also who changed it, when, and context.
  13. - 🔗 **Isolated & Organized**: Each project gets its own isolated memory space, ensuring that context from one project doesn't leak into another.
  14. - ⚡ **Efficient Integration**: Built on the Model Context Protocol (MCP), it provides a standardized, low-overhead way for LLMs to access this powerful memory.
  15. ## 🚀 Getting Started
  16. **Prerequisites**: Python 3.11+ and Docker (for Qdrant vector database).
  17. Heimdall provides a unified `heimdall` CLI that manages everything from project setup to MCP integration.
  18. ### 1. Install Heimdall
  19. ```bash
  20. pip install heimdall-mcp
  21. ```
  22. This installs the `heimdall` command-line tool with all necessary dependencies.
  23. ### 2. Initialize Your Project
  24. Navigate to your project directory and set up Heimdall:
  25. ```bash
  26. cd /path/to/your/project
  27. # Initialize project memory (starts Qdrant, creates collections, sets up config)
  28. heimdall project init
  29. ```
  30. This single command interactively builds up everything asking user preferences:
  31. - ✅ Starts Qdrant vector database automatically
  32. - ✅ Creates project-specific memory collections
  33. - ✅ Sets up `.heimdall/` configuration directory
  34. - ✅ Downloads required AI models
  35. - ✅ File monitoring
  36. - ✅ Git hooks
  37. - ✅ MCP integration
  38. **Note: this creates a `.heimdall/` directory in your project for configuration - you should NOT commit this - add to .gitignore!**
  39. ## Load Project Knowledge
  40. **Recommended: Use automatic file monitoring** and place files in `.heimdall/docs/`:
  41. ```bash
  42. # Copy or symlink your documentation to the monitored directory
  43. ln -r -s my-project-docs ./.heimdall/docs/project-docs
  44. # Start automatic monitoring (files are loaded instantly when changed)
  45. heimdall monitor start
  46. ```
  47. **Alternative: Manual loading** for one-time imports:
  48. ```bash
  49. # Load documentation and files manually
  50. heimdall load docs/ --recursive
  51. heimdall load README.md
  52. ```
  53. Your project's memory is now active and ready for your LLM.
  54. #### Real-time Git Integration
  55. You can parse your entire git history with:
  56. ```bash
  57. # Load git commit history
  58. heimdall git-load .
  59. ```
  60. You can also install git hooks for automatic memory updates on commits:
  61. ```bash
  62. # Install the post-commit hook (Python-based, cross-platform)
  63. heimdall git-hooks install
  64. ```
  65. **Note**: If you have existing post-commit hooks, they'll be safely chained and preserved - but proceed carefully.
  66. ## 🧹 Cleanup
  67. To remove Heimdall from a project:
  68. ```bash
  69. # Navigate to the project you want to clean up
  70. cd /path/to/project
  71. # Cleanup data, remove collections, uninstall git hooks
  72. memory_system project clean
  73. ```
  74. This cleanly removes project-specific data while preserving the shared Qdrant instance for other projects.
  75. ## ⚙️ How It Works Under the Hood
  76. Heimdall 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.
  77. ```mermaid
  78. graph TD
  79. %% Main client outside the server architecture
  80. AI_Assistant["🤖 AI Assistant (e.g., Claude)"]
  81. %% Top-level subgraph for the entire server
  82. subgraph Heimdall MCP Server Architecture
  83. %% 1. Application Interface Layer
  84. subgraph Application Interface
  85. MCP_Server["MCP Server (heimdall-mcp)"]
  86. CLI["CognitiveCLI (heimdall/cli.py)"]
  87. style MCP_Server fill:#b2ebf2,stroke:#00acc1,color:#212121
  88. style CLI fill:#b2ebf2,stroke:#00acc1,color:#212121
  89. end
  90. %% 2. Core Logic Engine
  91. style Cognitive_System fill:#ccff90,stroke:#689f38,color:#212121
  92. Cognitive_System["🧠 CognitiveSystem (core/cognitive_system.py)<br/>"]
  93. %% 3. Storage Layer (components side-by-side)
  94. subgraph Storage Layer
  95. Qdrant["🗂️ Qdrant Storage<br/><hr/>- Vector Similarity Search<br/>- Multi-dimensional Encoding"]
  96. SQLite["🗃️ SQLite Persistence<br/><hr/>- Memory Metadata & Connections<br/>- Caching & Retrieval Stats"]
  97. end
  98. %% 4. Output Formatting
  99. style Formatted_Response fill:#fff9c4,stroke:#fbc02d,color:#212121
  100. Formatted_Response["📦 Formatted MCP Response<br/><i>{ core, peripheral }</i>"]
  101. %% Define internal flow
  102. MCP_Server -- calls --> CLI
  103. CLI -- calls --> Cognitive_System
  104. Cognitive_System -- "1\. Vector search for candidates" --> Qdrant
  105. Cognitive_System -- "2\. Hydrates with metadata" --> SQLite
  106. Cognitive_System -- "3\. Performs Bridge Discovery" --> Formatted_Response
  107. end
  108. %% Define overall request/response flow between client and server
  109. AI_Assistant -- "recall_memorie" --> MCP_Server
  110. Formatted_Response -- "Returns structured memories" --> AI_Assistant
  111. %% --- Styling Block ---
  112. %% 1. Node Styling using Class Definitions
  113. classDef aiClientStyle fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
  114. classDef interfaceNodeStyle fill:#cffafe,stroke:#22d3ee,color:#0e7490
  115. classDef coreLogicStyle fill:#dcfce7,stroke:#4ade80,color:#166534
  116. classDef qdrantNodeStyle fill:#ede9fe,stroke:#a78bfa,color:#5b21b6
  117. classDef sqliteNodeStyle fill:#fee2e2,stroke:#f87171,color:#991b1b
  118. classDef responseNodeStyle fill:#fef9c3,stroke:#facc15,color:#854d0e
  119. %% 2. Assigning Classes to Nodes
  120. class AI_Assistant aiClientStyle
  121. class MCP_Server,CLI interfaceNodeStyle
  122. class Cognitive_System coreLogicStyle
  123. class Qdrant qdrantNodeStyle
  124. class SQLite sqliteNodeStyle
  125. class Formatted_Response responseNodeStyle
  126. %% 3. Link (Arrow) Styling
  127. %% Note: Styling edge label text is not reliably supported. This styles the arrow lines themselves.
  128. %% Primary request/response flow (links 0 and 1)
  129. linkStyle 0,1 stroke:#3b82f6,stroke-width:2px
  130. %% Internal application calls (links 2 and 3)
  131. linkStyle 2,3 stroke:#22d3ee,stroke-width:2px,stroke-dasharray: 5 5
  132. %% Internal data access calls (links 4 and 5)
  133. linkStyle 4,5 stroke:#9ca3af,stroke-width:2px
  134. %% Final processing call (link 6)
  135. linkStyle 6 stroke:#4ade80,stroke-width:2px
  136. ```
  137. ## LLM Tool Reference
  138. You can instruct your LLM to use the following six tools to interact with its memory:
  139. | Tool | Description |
  140. | :---------------- | :------------------------------------------------------------------- |
  141. | `store_memory` | Stores a new piece of information, such as an insight or a solution. |
  142. | `recall_memories` | Performs a semantic search for relevant memories based on a query. |
  143. | `session_lessons` | Records a key takeaway from the current session for future use. |
  144. | `memory_status` | Checks the health and statistics of the memory system. |
  145. | `delete_memory` | Delete a specific memory by its unique ID. |
  146. | `delete_memories_by_tags` | Delete all memories that have any of the specified tags. |
  147. ## 💡 Best Practices
  148. To maximize the effectiveness of Heimdall:
  149. * **Provide Quality Documentation:** Think architecture decision records, style guides, and API documentation.
  150. * **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.
  151. * **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`.
  152. * **Set Up Automation:** Use `heimdall monitor start` and `heimdall git-hooks install` for hands-free memory updates.
  153. * **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.
  154. * **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`.
  155. ## 🛠️ Command Reference
  156. ### Core Commands
  157. | Command | Description |
  158. | :------ | :---------- |
  159. | `heimdall store <text>` | Store experience in cognitive memory |
  160. | `heimdall recall <query>` | Retrieve relevant memories based on query |
  161. | `heimdall load <path>` | Load files/directories into memory |
  162. | `heimdall git-load [repo]` | Load git commit patterns into memory |
  163. | `heimdall status` | Show system status and memory statistics |
  164. | `heimdall remove-file <path>` | Remove memories for deleted file |
  165. | `heimdall delete-memory <id>` | Delete specific memory by ID |
  166. | `heimdall delete-memories-by-tags --tag <tag>` | Delete memories by tags |
  167. | `heimdall doctor` | Run comprehensive health checks |
  168. | `heimdall shell` | Start interactive memory shell |
  169. ### Project Management
  170. | Command | Description |
  171. | :------ | :---------- |
  172. | `heimdall project init` | Initialize project memory with interactive setup |
  173. | `heimdall project list` | List all projects in shared Qdrant instance |
  174. | `heimdall project clean` | Remove project collections and cleanup |
  175. ### Vector Database (Qdrant)
  176. | Command | Description |
  177. | :------ | :---------- |
  178. | `heimdall qdrant start` | Start Qdrant vector database service |
  179. | `heimdall qdrant stop` | Stop Qdrant service |
  180. | `heimdall qdrant status` | Check Qdrant service status |
  181. | `heimdall qdrant logs` | View Qdrant service logs |
  182. ### File Monitoring
  183. | Command | Description |
  184. | :------ | :---------- |
  185. | `heimdall monitor start` | Start automatic file monitoring service |
  186. | `heimdall monitor stop` | Stop file monitoring service |
  187. | `heimdall monitor restart` | Restart monitoring service |
  188. | `heimdall monitor status` | Check monitoring service status |
  189. | `heimdall monitor health` | Detailed monitoring health check |
  190. ### Git Integration
  191. | Command | Description |
  192. | :------ | :---------- |
  193. | `heimdall git-hook install` | Install post-commit hook for automatic memory processing |
  194. | `heimdall git-hook uninstall` | Remove Heimdall git hooks |
  195. | `heimdall git-hook status` | Check git hook installation status |
  196. ### MCP Integration
  197. | Command | Description |
  198. | :------ | :---------- |
  199. | `heimdall mcp install <platform>` | Install MCP server for platform (vscode, cursor, claude-code, visual-studio, codex) |
  200. | `heimdall mcp remove <platform>` | Remove MCP integration from platform |
  201. | `heimdall mcp status` | Show installation status for all platforms |
  202. | `heimdall mcp list` | List available platforms and installation status |
  203. | `heimdall mcp generate <platform>` | Generate configuration snippets for manual installation |
  204. #### Platforms
  205. Heimdall MCP server is compatible with any platform that supports STDIO MCP servers. The following platforms are supported for automatic installation using `heimdall mcp` commands.
  206. - `vscode` - Visual Studio Code
  207. - `cursor` - Cursor IDE
  208. - `claude-code` - Claude Code
  209. - `visual-studio` - Visual Studio
  210. - `codex` - Codex CLI (project-local CODEX_HOME config)
  211. ## Technology Stack:
  212. - Python 3.11+
  213. - Vector Storage: Qdrant
  214. - Mmeory information and metadata: SQLite
  215. - Embeddings: all-MiniLM-L6-v2
  216. - Sentiment analysis: NRCLex emotion lexicon
  217. - Semantic analysis: spaCy
  218. - Integration: Model Context Protocol (MCP)
  219. ## 🗺️Short Term Roadmap
  220. * [x] ~~Git `post-commit` hook for automatic, real-time memory updates~~ ✅ **Completed**
  221. * [x] ~~Watcher to auto-detect and load new documents in the `.heimdall-mcp` directory.~~ ✅ **Completed**
  222. * [x] ~~Release v0.1.0 publicly~~ ✅ **Completed**
  223. * [x] ~~Heimdall pip package available~~ ✅ **Completed**
  224. * [x] ~~Simplify installation~~ ✅ **Completed**
  225. * [x] ~~Delete memories support (manually or by tags - for md docs already supported)~~ ✅ **Completed**
  226. ## 🤝 Contributing
  227. We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
  228. - Setting up the development environment
  229. - Our dual licensing model
  230. - Code style guidelines
  231. - Pull request process
  232. **Important:** All contributors must agree to our [Contributor License Agreement](CLA.md) before their contributions can be merged.
  233. ### Quick Start for Contributors
  234. 1. Fork the repository
  235. 2. Create a feature branch targeting `dev` (not `main`)
  236. 3. Make your changes following our style guidelines
  237. 4. Submit a pull request with the provided template
  238. 5. Sign the CLA when prompted by the CLA Assistant
  239. For questions, open an issue or start a discussion!
  240. ## 📄 License
  241. This 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.