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.

graph TD
    %% Main client outside the server architecture
    AI_Assistant["🤖 AI Assistant (e.g., Claude)"]

    %% Top-level subgraph for the entire server
    subgraph Heimdall MCP Server Architecture

        %% 1. Application Interface Layer
        subgraph Application Interface
            MCP_Server["MCP Server (heimdall-mcp)"]
            CLI["CognitiveCLI (heimdall/cli.py)"]
            style MCP_Server fill:#b2ebf2,stroke:#00acc1,color:#212121
            style CLI fill:#b2ebf2,stroke:#00acc1,color:#212121
        end

        %% 2. Core Logic Engine
        style Cognitive_System fill:#ccff90,stroke:#689f38,color:#212121
        Cognitive_System["🧠 CognitiveSystem (core/cognitive_system.py)<br/>"]

        %% 3. Storage Layer (components side-by-side)
        subgraph Storage Layer
            Qdrant["🗂️ Qdrant Storage<br/><hr/>- Vector Similarity Search<br/>- Multi-dimensional Encoding"]
            SQLite["🗃️ SQLite Persistence<br/><hr/>- Memory Metadata & Connections<br/>- Caching & Retrieval Stats"]
        end

        %% 4. Output Formatting
        style Formatted_Response fill:#fff9c4,stroke:#fbc02d,color:#212121
        Formatted_Response["📦 Formatted MCP Response<br/><i>{ core, peripheral }</i>"]

        %% Define internal flow
        MCP_Server -- calls --> CLI
        CLI -- calls --> Cognitive_System

        Cognitive_System -- "1\. Vector search for candidates" --> Qdrant
        Cognitive_System -- "2\. Hydrates with metadata" --> SQLite
        Cognitive_System -- "3\. Performs Bridge Discovery" --> Formatted_Response

    end

    %% Define overall request/response flow between client and server
    AI_Assistant -- "recall_memorie" --> MCP_Server
    Formatted_Response -- "Returns structured memories" --> AI_Assistant

    %% --- Styling Block ---

    %% 1. Node Styling using Class Definitions
    classDef aiClientStyle fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
    classDef interfaceNodeStyle fill:#cffafe,stroke:#22d3ee,color:#0e7490
    classDef coreLogicStyle fill:#dcfce7,stroke:#4ade80,color:#166534
    classDef qdrantNodeStyle fill:#ede9fe,stroke:#a78bfa,color:#5b21b6
    classDef sqliteNodeStyle fill:#fee2e2,stroke:#f87171,color:#991b1b
    classDef responseNodeStyle fill:#fef9c3,stroke:#facc15,color:#854d0e

    %% 2. Assigning Classes to Nodes
    class AI_Assistant aiClientStyle
    class MCP_Server,CLI interfaceNodeStyle
    class Cognitive_System coreLogicStyle
    class Qdrant qdrantNodeStyle
    class SQLite sqliteNodeStyle
    class Formatted_Response responseNodeStyle

    %% 3. Link (Arrow) Styling
    %% Note: Styling edge label text is not reliably supported. This styles the arrow lines themselves.
    %% Primary request/response flow (links 0 and 1)
    linkStyle 0,1 stroke:#3b82f6,stroke-width:2px
    %% Internal application calls (links 2 and 3)
    linkStyle 2,3 stroke:#22d3ee,stroke-width:2px,stroke-dasharray: 5 5
    %% Internal data access calls (links 4 and 5)
    linkStyle 4,5 stroke:#9ca3af,stroke-width:2px
    %% Final processing call (link 6)
    linkStyle 6 stroke:#4ade80,stroke-width:2px

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.