Persistent-Code MCP Server with LlamaIndex

A Model Context Protocol (MCP) server that creates and maintains a semantic knowledge graph of code generated by Claude. Powered by LlamaIndex, this allows maintaining context across sessions with advanced semantic search capabilities without requiring the entire codebase to be present in the context window.

Problem & Solution

When developing software with Claude:

• Context windows are limited, making it difficult to work with large codebases
• Previous code context is lost between sessions
• Claude lacks persistent understanding of project structure
• Redundant explanation of code is required in each session
• Maintaining implementation consistency is challenging

Persistent-Code solves these problems by:

• Creating a knowledge graph of code components and their relationships
• Tracking implementation status of each component
• Providing tools to navigate, query, and understand the codebase
• Assembling minimal necessary context for specific coding tasks
• Maintaining persistent knowledge across chat sessions

LlamaIndex Integration

Persistent-Code leverages LlamaIndex to provide enhanced semantic understanding:

1. Semantic Search: Find code components based on meaning, not just keywords
2. Vector Embeddings: Code is embedded into vector space for similarity matching
3. Knowledge Graph: Relationships between components are tracked semantically
4. Contextual Retrieval: Related code is retrieved based on semantic relevance

This integration allows Claude to understand your codebase at a deeper level:

• Find functions based on what they do, not just what they're called
• Get more relevant code components when preparing context
• Better understand the relationships between components
• More accurately retrieve examples of similar implementations

Installation

Prerequisites

• Python 3.10 or higher
• UV package manager (recommended) or pip

Setting Up

# Clone repository
git clone https://github.com/your-username/persistent-code-mcp.git
cd persistent-code-mcp

# Set up environment with UV
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Or with pip
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Usage

Initializing a Project

python -m persistent_code init --project-name "YourProject"

Starting the Server

python -m persistent_code serve --project-name "YourProject"

Configuring Claude for Desktop

1. Edit your Claude for Desktop config file:
   • Location: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Add the following configuration:

{
  "mcpServers": {
    "persistent-code": {
      "command": "path to python in venv",
      "args": [
        "-m",
        "persistent_code",
        "serve",
        "--project-name",
        "default"
      ],
      "cwd": "persistent-code-mcp",
      "env": {
        "PYTHONPATH": "abs path to persistent-code-mcp"
      }
    }
  }
}

2. Restart Claude for Desktop
3. Connect to your MCP server by asking Claude about your code

Available Tools

Knowledge Graph Management

• add_component: Add a new code component to the graph
• update_component: Update an existing component
• add_relationship: Create a relationship between components

Code Retrieval and Navigation

• get_component: Retrieve a component by ID or name
• find_related_components: Find components related to a given component
• search_code: Search the codebase semantically

Status Management

• update_status: Update implementation status of a component
• get_project_status: Retrieve implementation status across the project
• find_next_tasks: Suggest logical next components to implement

Context Assembly

• prepare_context: Assemble minimal context for a specific task
• continue_implementation: Provide context to continue implementing a component
• get_implementation_plan: Generate a plan for implementing pending components

Code Analysis

• analyze_code: Analyze code and update the knowledge graph

Example Workflow

1. Initialize a project:

   python -m persistent_code init --project-name "TodoApp"

2. Start the server:

   python -m persistent_code serve --project-name "TodoApp"

3. Ask Claude to design your project:

   Can you help me design a Todo app with Python and FastAPI? Let's start with the core data models.
   

4. Claude will create components and track them in the knowledge graph

5. Continue development in a later session:

   Let's continue working on the Todo app. What's our implementation status?
   

6. Claude will retrieve the current status and suggest next steps

7. Implement specific components:

   Let's implement the task completion endpoint for our Todo app
   

8. Claude will retrieve relevant context and provide consistent implementation

Using Semantic Search

With the LlamaIndex integration, you can now use more natural language to find components:

Find me all code related to handling task completion

Claude will use semantic search to find relevant components, even if they don't explicitly contain the words "task completion".

Running the LlamaIndex Demo

We've included a demo script to showcase the semantic capabilities:

# Activate your virtual environment
source .venv/bin/activate  # or source venv/bin/activate

# Run the demo
python examples/llama_index_demo.py

This will demonstrate analyzing a Calendar application and performing semantic searches for functionality.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.