Skip to content

DEV Community

Twly

Posted on Jul 27

I built CodeMind: A persistent codebase memory & AST context engine for AI agents

#agents #ai #architecture #tooling

Why Simple Vector Search Isn't Enough for Code

When building AI coding assistants or autonomous agents, one of the biggest hurdles is context management. Standard retrieval methods—like chunking code by arbitrary line counts or relying solely on basic keyword search—frequently break down when navigating complex software architectures.

An AI agent doesn't just need random snippets of text; it needs to understand relationships. It needs to know that class Server in server.py relies on a method defined in engine.py, and how an edit in one place propagates across the codebase.

To solve this, I built CodeMind—a persistent codebase memory and semantic context engine designed specifically for AI development agents.

What is CodeMind?

CodeMind provides AI agents and LLMs with a persistent, real-time memory layer over large codebases. Instead of dumping raw files into context windows, CodeMind parses project architecture into Abstract Syntax Tree (AST) chunks and maps dependencies into a symbol graph store.

Here’s what makes it work behind the scenes:

AST-Aware Chunking: Parses source files intelligently by structure (classes, functions, methods) rather than arbitrary line limits.
Symbol Graph Store: Maps cross-references, dependencies, and relationships between entities across your project.
Model Context Protocol (MCP) Integration: Exposes standard endpoints so it can plug directly into MCP clients like Claude Desktop, Cursor, or custom agent frameworks.
Automated File Scanner: Keeps track of local file changes and maintains live index updates automatically.

Getting Started

CodeMind is open source and easy to set up locally.

1. Installation

Clone the repository and set up your environment:

git clone https://github.com/twly7ho2/codemind.git
cd codemind
python -m venv venv

Activate your virtual environment and install in editable mode:

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

pip install --upgrade pip
pip install -e

.

2. Running as an MCP Server

CodeMind runs out of the box as an MCP server. You can launch it directly from your terminal:

python -m codemind.mcp.server

To link it with Claude Desktop, add the following block to your claude_desktop_config.json:

{
  "mcpServers": {
    "codemind": {
      "command": "python",
      "args": [
        "-m",
        "codemind.mcp.server"
      ],
      "env": {
        "PYTHONPATH": "C:\\Users\\YOUR_USERNAME\\codemind"
      }
    }
  }
}

Project Architecture

Here is how the repository is organized:

codemind/
|-- codemind/
| |-- indexer/
| | |-- engine.py # Main indexing orchestration
| | -- scanner.py # File crawler & change detection | |-- parser/ | |-- chunker.py # AST-based syntax chunking
| |-- storage/
| | -- graph_store.py # Symbol graph & dependency store |-- mcp/
| -- server.py # Model Context Protocol endpoints |-- pyproject.toml # Package build config-- README.md

Check Out the Repo & Contribute

The project is live on GitHub:

twly7ho2 / codemind

CodeMind is an AI agent memory system that maintains persistent, real-time context over complex codebases. By utilizing symbol graph storage, AST chunking, and intelligent file scanning, CodeMind enables LLMs to reason about relationships across large code structures without losing track of dependencies

CodeMind

Persistent codebase memory and semantic context engine for AI development agents.

CodeMind provides AI agents and LLMs with a persistent, real-time memory layer over large codebases. Instead of relying on raw token dumps or simple keyword searches, CodeMind indexes software architecture into symbol graphs and Abstract Syntax Tree (AST) chunks. This allows AI tools to analyze dependencies, track code changes, and navigate complex structures effortlessly.

Features

AST-Aware Chunking: Parses source files intelligently by structure (classes, functions, methods) rather than arbitrary line counts.
Symbol Graph Store: Maps relationships, cross-references, and dependencies between codebase entities.
Model Context Protocol (MCP) Integration: Directly connects into MCP-compatible clients like Claude Desktop, Cursor, or custom agent frameworks.
Automated File Scanner: Keeps track of codebase changes and keeps indexing pipelines up to date.

Prerequisites

Before installing CodeMind, ensure you have the following setup on your machine:

Python 3.10+
Git
Virtual environment tool (venv or conda)

Installation

…

If you're building AI agents, experimenting with MCP, or interested in codebase context indexing, feel free to give it a star, open an issue, or drop a PR I'd wanna to hear your feedback on how you manage codebase context in your agent workflows.

Top comments (0)

Subscribe