Context Management System

A context management system for AI development tools like Cursor, Claude Code, and Gemini CLI that enables leveraging previous context from chat sessions while maintaining dynamic workflows.

🚀 Quick Start (5 Minutes)

Get up and running immediately:

1. Install dependencies:

   pip install -r requirements.txt
   # Or install in development mode:
   pip install -e .
   

2. Set up MCP integration (choose your tool):

   • Cursor: Copy mcp-config-cursor.json to ~/.cursor/mcp.json or .cursor/mcp.json in your project
   • Gemini CLI: Copy mcp-config-gemini.json to .gemini/settings.json in your project
   • Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

3. Restart your AI tool - The context management tools are now available!

4. Start using it - The AI will automatically:

   • Create context branches for different tasks
   • Log reasoning steps as it works
   • Create checkpoints when you make progress
   • Remember context across sessions

That's it! The system auto-detects your project workspace and creates a .context/ directory automatically.

✨ What You Get

Once set up, your AI assistant can:

• Remember across sessions: Pick up exactly where you left off, even days later
• Organize by task: Automatically branch context for different features/bugs
• Track progress: See what's been done, what's pending, and what's next
• Smart context switching: Automatically detect which branch matches your current work
• No manual work: The AI handles all context management automatically

Features

• LOG: Record reasoning steps as the AI works through problems
• COMMIT: Checkpoint important points in chat sessions
• BRANCH: Create new branches with easy access to previous branch context
• MERGE: Merge context from multiple branches into the current branch
• INFO: Get project information at different levels (project goals, branch summaries, detailed chat sessions)
• TODO Management: Track and manage TODO items across branches
• Smart Branch Detection: Automatically suggest the right branch for your work

Installation

Option 1: Development Install (Recommended)

# Clone or download this repository
cd context-engineering

# Install in development mode
pip install -e .

Option 2: Direct Install

pip install -r requirements.txt

Integration Options

Option 1: MCP Server (Recommended)

The MCP (Model Context Protocol) server allows AI tools to call context management functions directly. This is the recommended approach as it enables seamless integration.

For Cursor

Quick Setup:

1. Copy the config file:

   # For project-specific setup (recommended):
   cp mcp-config-cursor.json .cursor/mcp.json
   
   # Or for global setup:
   mkdir -p ~/.cursor
   cp mcp-config-cursor.json ~/.cursor/mcp.json
   

2. Edit the cwd path in the config file to point to this repository:

   {
     "mcpServers": {
       "context-management": {
         "command": "python3",
         "args": ["-m", "src.mcp_server"],
         "cwd": "/absolute/path/to/context-engineering"
       }
     }
   }
   

   Note: Use ${workspaceFolder} for project-specific configs (Cursor will auto-replace it)

3. Restart Cursor - The AI will now have access to context management tools!

What happens next:

• When you start a new chat, the AI can call context_status() to check your workspace
• The AI will automatically create a .context/ directory in your project root
• All context management happens automatically - no manual intervention needed

For Gemini CLI

1. Create the config directory:

   mkdir -p .gemini
   cp mcp-config-gemini.json .gemini/settings.json
   

2. Edit .gemini/settings.json and update the cwd path:

   {
     "mcpServers": {
       "context-management": {
         "command": "python3",
         "args": ["-m", "src.mcp_server"],
         "cwd": "/absolute/path/to/context-engineering"
       }
     }
   }
   

3. Restart Gemini CLI - Context management tools are now available!

For Claude Desktop

1. Edit the config file:

   # On macOS:
   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # On Windows:
   # %APPDATA%\Claude\claude_desktop_config.json
   
   # On Linux:
   # ~/.config/Claude/claude_desktop_config.json
   

2. Add or merge this configuration:

   {
     "mcpServers": {
       "context-management": {
         "command": "python3",
         "args": ["-m", "src.mcp_server"],
         "cwd": "/absolute/path/to/context-engineering"
       }
     }
   }
   

3. Restart Claude Desktop - You're all set!

Option 2: CLI Commands

Use the CLI directly or have the AI invoke shell commands:

# Log reasoning steps
python3 -m src.cli log "Investigating the auth module..."

# Commit progress
python3 -m src.cli commit --from-log all

# Create/switch branches
python3 -m src.cli branch fix-login-bug --empty

# Get info
python3 -m src.cli info --level branch

🎯 First Steps After Setup

Once you've configured MCP and restarted your AI tool, here's what to expect:

1. Automatic Workspace Detection

When you start a new chat session, the AI will:

• Automatically detect your project workspace (via git root or existing .context/ directory)
• Create a .context/ directory structure if it doesn't exist
• Initialize the main context file with your project goals

2. Start Working Normally

Just work with your AI as usual! The system will:

• Automatically branch when you switch to different tasks
• Log reasoning steps as the AI thinks through problems
• Create checkpoints when significant progress is made
• Track TODOs across your work sessions

3. Example: Your First Session

You: "Help me add user authentication to my app"

AI: [Automatically calls context_detect_branch()]
    → Creates branch "add-user-auth"
    → Logs: "Starting authentication feature implementation"
    → Works on the task...

You: "Actually, let's fix the login bug first"

AI: [Automatically calls context_detect_branch()]
    → Switches to branch "fix-login-bug" (or creates it)
    → Has access to previous login-related context
    → Continues from where you left off

4. Returning Later

When you come back days or weeks later:

You: "What were we working on?"

AI: [Calls context_summary()]
    → Shows: Current branch, pending TODOs, recent progress
    → Picks up exactly where you left off

No manual context management needed - it all happens automatically!

MCP Tools

When using the MCP server, the AI has access to these tools:

context_status() - Check workspace path and current branch. Used at session start.

context_set_workspace(workspace_path) - Set the project workspace directory. Used if auto-detection fails.

context_summary() - Get quick overview of TODOs and progress. Used at session start and when checking status.

context_detect_branch(context_hint) - Smart branching: find the right branch for current work. Used before starting new tasks.

context_todos(action, item, todo_id) - View, add, or complete TODO items. Used throughout the session.

context_log(reasoning_step) - Log a reasoning step during AI thought process. Used as the AI works through problems.

context_commit(message, from_log) - Checkpoint progress by creating a commit. Used when significant progress is made.

context_branch(name, purpose, from_branch, empty) - Create a new branch or switch to existing one. Used when switching tasks.

context_merge(branches) - Merge context from other branches. Used when combining work from multiple branches.

context_info(level, branch) - Get detailed project/branch/session information. Used when you need detailed context.

Note: The AI uses these tools automatically - you don't need to call them manually!

Workflow Example

Here's a real-world example of how the system works across multiple sessions:

Day 1: Starting a New Feature

You ask: "Let's add user authentication"

The AI automatically:

• Detects this is a new task and calls context_detect_branch("user authentication")
• Creates a new branch called "add-user-auth"
• Logs: "Starting auth implementation..."
• Works on the feature, logging steps like "Created User model..." and "Implemented login endpoint..."
• Creates a checkpoint with context_commit(from_log="all")

Day 2: Switching Tasks

You say: "Actually, let's fix the login bug first"

The AI automatically:

• Detects the task switch and calls context_detect_branch("login bug fix")
• Switches to (or creates) the "fix-login-bug" branch
• Logs: "Investigating login issue..."
• Finds and fixes the bug
• Commits: "Fixed password validation"

Day 5: Returning to Previous Work

You ask: "What were we working on?"

The AI automatically:

• Calls context_summary() to load your context
• Shows you're on branch "add-user-auth"
• Shows pending TODO: "Add password reset"
• Shows last commit: "Implemented login endpoint"
• Picks up exactly where you left off

Key Benefits:

• No context loss between sessions
• Automatic task organization
• Seamless switching between features
• Progress tracking and TODO management

Project Structure

The system creates a .context/ directory in your project root:

your-project/
├── .context/                    # Context management directory
│   ├── main.md                  # Project goals, milestones, shared TODOs
│   ├── .current_branch          # Current branch pointer (hidden file)
│   └── branches/
│       └── <branch-name>/       # One directory per branch
│           ├── commits.yaml     # Checkpoint history (structured)
│           ├── log.yaml         # Detailed reasoning steps (append-only)
│           └── metadata.yaml    # Branch metadata (file structure, env, etc.)
├── src/                         # Your actual project code
└── ...

Important: The .context/ directory should be committed to git so context is shared across machines and team members.

Troubleshooting

MCP Server Not Working

Problem: AI doesn't have access to context tools

Solutions:

1. Check the config file path - Make sure you edited the correct config file for your tool
2. Verify the cwd path - Use absolute paths, not relative ones
3. Check Python path - Ensure python3 is in your PATH
4. Restart your AI tool - MCP configs are only loaded on startup
5. Check for errors - Look in your AI tool's logs/console for MCP errors

Workspace Not Detected

Problem: context_status() shows wrong workspace or "not found"

Solutions:

1. Set workspace manually: The AI can call context_set_workspace(workspace_path="/path/to/project")
2. Ensure git repository: The system auto-detects via git root
3. Create .context/ manually: If needed, create .context/ in your project root

Branch Detection Not Working

Problem: AI creates new branches instead of switching to existing ones

Solutions:

1. Use descriptive hints: When the AI calls context_detect_branch(), provide clear context
2. Check branch names: Existing branches are matched by name similarity
3. Manual switch: You can ask the AI to switch branches explicitly

Context Not Persisting

Problem: Context is lost between sessions

Solutions:

1. Check .context/ exists: The directory should be in your project root
2. Verify git commit: Make sure .context/ is committed to git
3. Check branch: Ensure you're on the same branch as before

Development

This tool is under active development. See TODO.md for implementation progress.

Contributing

Contributions are welcome! The system is designed to be extensible and modular.

Requirements

• Python 3.8+
• See requirements.txt for dependencies