Content
# 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 Steps
### 1. Clone the Repository
git clone https://github.com/twly7ho2/codemind.git
cd codemind
---
### 2. Set Up a Virtual Environment
It is recommended to use a virtual environment to manage dependencies isolated from your main system.
On Windows:
python -m venv venv
venv\Scripts\activate
On macOS / Linux:
python3 -m venv venv
source venv/bin/activate
---
### 3. Install Package and Dependencies
Install CodeMind in editable mode along with required packages using pyproject.toml:
pip install --upgrade pip
pip install -e .
---
## Usage and Execution
### Running the MCP Server
CodeMind exposes an MCP server interface to communicate directly with AI agent clients.
To launch the server directly from terminal:
python -m codemind.mcp.server
---
### Local MCP Configuration Example
To connect CodeMind to Claude Desktop or another MCP client, add the following entry to your claude_desktop_config.json:
{
"mcpServers": {
"codemind": {
"command": "python",
"args": [
"-m",
"codemind.mcp.server"
],
"env": {
"PYTHONPATH": "C:\\Users\\YOUR_USERNAME\\codemind"
}
}
}
}
---
## Repository Structure
codemind/
|-- codemind/
| |-- indexer/
| | |-- engine.py # Main indexing orchestration engine
| | `-- scanner.py # Codebase file crawler and change detection
| |-- parser/
| | `-- chunker.py # AST-based syntax chunking logic
| |-- storage/
| | `-- graph_store.py # Symbol graph and dependency storage
| `-- mcp/
| `-- server.py # Model Context Protocol server endpoints
|-- pyproject.toml # Build system and metadata configuration
|-- .gitignore # Ignored files (venv, caches, indexes)
`-- README.md # Project documentation
---
## Contributing
Contributions, issues, and feature requests are welcome!
1. Fork the project.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.
---
## License
Distributed under the MIT License. See LICENSE for more information.
