Context Management System

# 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:** ```bash 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) ```bash # Clone or download this repository cd context-engineering # Install in development mode pip install -e . ``` ### Option 2: Direct Install ```bash 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:** ```bash # 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: ```json { "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:** ```bash mkdir -p .gemini cp mcp-config-gemini.json .gemini/settings.json ``` 2. **Edit `.gemini/settings.json`** and update the `cwd` path: ```json { "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:** ```bash # 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:** ```json { "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: ```bash # 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