heimdall-mcp-server

Heimdall MCP Server - Your AI Coding Assistant’s Long-Term Memory

The Problem: Your AI coding assistant has short-lived memory. Every chat session starts from a blank slate.

The Solution: Heimdall gives your LLM a persistent, growing, cognitive memory of your specific codebase, lessons and memories carry over time.

https://github.com/user-attachments/assets/120b3d32-72d1-4d42-b3ab-285e8a711981

Key Features

• 🧠 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.
• 📚 Git-Aware Context: It indexes your project’s entire git history, understanding not just what changed, but also who changed it, when, and context.
• 🔗 Isolated & Organized: Each project gets its own isolated memory space, ensuring that context from one project doesn’t leak into another.
• ⚡ Efficient Integration: Built on the Model Context Protocol (MCP), it provides a standardized, low-overhead way for LLMs to access this powerful memory.

🚀 Getting Started

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!

Load Project Knowledge

Recommended: Use automatic file monitoring and place files in .heimdall/docs/:

# Copy or symlink your documentation to the monitored directory
ln -r -s my-project-docs ./.heimdall/docs/project-docs

# Start automatic monitoring (files are loaded instantly when changed)
heimdall monitor start

Alternative: Manual loading for one-time imports:

# Load documentation and files manually
heimdall load docs/ --recursive
heimdall load README.md

Your project’s memory is now active and ready for your LLM.

Real-time Git Integration

You can parse your entire git history with:

# Load git commit history
heimdall git-load .

You can also install git hooks for automatic memory updates on commits:

# Install the post-commit hook (Python-based, cross-platform)
heimdall git-hooks install

Note: If you have existing post-commit hooks, they’ll be safely chained and preserved - but proceed carefully.

🧹 Cleanup

To remove Heimdall from a project:

# Navigate to the project you want to clean up
cd /path/to/project

# Cleanup data, remove collections, uninstall git hooks
memory_system project clean

This cleanly removes project-specific data while preserving the shared Qdrant instance for other projects.

⚙️ How It Works Under the Hood

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.

LLM Tool Reference

You can instruct your LLM to use the following six tools to interact with its memory:

💡 Best Practices

To maximize the effectiveness of Heimdall:

• Provide Quality Documentation: Think architecture decision records, style guides, and API documentation.
• 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.
• 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.
• Set Up Automation: Use heimdall monitor start and heimdall git-hooks install for hands-free memory updates.
• 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.
• 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.

🛠️ Command Reference

Core Commands

Project Management

Vector Database (Qdrant)

File Monitoring

Git Integration

MCP Integration

Platforms

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.

• vscode - Visual Studio Code
• cursor - Cursor IDE
• claude-code - Claude Code
• visual-studio - Visual Studio
• codex - Codex CLI (project-local CODEX_HOME config)

Technology Stack:

• Python 3.11+
• Vector Storage: Qdrant
• Mmeory information and metadata: SQLite
• Embeddings: all-MiniLM-L6-v2
• Sentiment analysis: NRCLex emotion lexicon
• Semantic analysis: spaCy
• Integration: Model Context Protocol (MCP)

🗺️Short Term Roadmap

• Git post-commit hook for automatic, real-time memory updates ✅ Completed
• Watcher to auto-detect and load new documents in the .heimdall-mcp directory. ✅ Completed
• Release v0.1.0 publicly ✅ Completed
• Heimdall pip package available ✅ Completed
• Simplify installation ✅ Completed
• Delete memories support (manually or by tags - for md docs already supported) ✅ Completed

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up the development environment
• Our dual licensing model
• Code style guidelines
• Pull request process

Important: All contributors must agree to our Contributor License Agreement before their contributions can be merged.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch targeting dev (not main)
3. Make your changes following our style guidelines
4. Submit a pull request with the provided template
5. Sign the CLA when prompted by the CLA Assistant

For questions, open an issue or start a discussion!

📄 License

This project is licensed under the Apache 2.0 License for open source use. See our Contributing Guide for information about our dual licensing model for commercial applications.