Skip to main content

​
ContextKeeper v3.0 Sacred Layer

License Python Node.js
AI-aware development context management with immutable architectural constraints
ContextKeeper is a RAG-powered development context awareness system that prevents AI agents from derailing from approved architectural plans through the Sacred Layer - an immutable plan storage system with 2-layer verification.

​
🚀 Quick Start

# Clone and setup
git clone https://github.com/lostmind008/contextkeeper.git
cd contextkeeper
./setup.sh

# Configure environment
cp .env.template .env
# Edit .env with your Google Cloud credentials and SACRED_APPROVAL_KEY

# Start ContextKeeper (runs on port 5556)
source venv/bin/activate
python rag_agent.py start

# Create your first project
./scripts/rag_cli.sh projects create "My Project" /path/to/project

# Ask questions with LLM-enhanced responses
./scripts/rag_cli.sh ask "What is this project about?"

# Get daily briefing
./scripts/rag_cli.sh briefing

​
✨ Key Features

​
🛡️ Sacred Layer Protection

  • Immutable Plans: Architectural constraints that cannot be modified once approved
  • 2-Layer Verification: Hash-based codes + environment key security
  • AI Guardrails: Prevent AI agents from suggesting non-compliant changes

​
🎯 Intelligent Context Management

  • Multi-Project Support: Isolated contexts for different projects
  • Smart File Filtering: Automatically excludes node_modules, venv, build files, binaries, and non-relevant languages
  • LLM-Enhanced Queries: Natural language responses instead of raw code chunks
  • Git Integration: Track development activity through git commits
  • Drift Detection: Real-time monitoring of alignment with sacred plans

​
🔗 Claude Code Integration

  • 8 MCP Tools: Sacred-aware tools for seamless AI collaboration
  • Natural Language: LLM-enhanced responses for technical queries
  • Real-time Context: Automatic architectural constraint provision

​
📋 Documentation

DocumentDescription
Installation GuideComplete setup instructions
Usage GuideHow to use ContextKeeper effectively
API ReferenceComplete API documentation
MCP ToolsClaude Code integration guide
ArchitectureSystem design and components

​
🏗️ Architecture

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Git Activity   │  │  Multi-Project  │  │  Sacred Layer   │
│  Tracker        │  │  RAG Agent      │  │  Manager        │
└─────────┬───────┘  └─────────┬───────┘  └─────────┬───────┘
          │                    │                    │
          ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────┐
│               ChromaDB Vector Storage                   │
│  • Project Collections (isolated)                      │
│  • Sacred Collections (immutable)                      │
│  • Decision & Objective Tracking                       │
└─────────────────────────────────────────────────────────┘

​
🔧 Core Workflows

​
Project Management (✅ Currently Working)

# List all projects
./scripts/rag_cli.sh projects list

# Create a new project with automatic file filtering
./scripts/rag_cli.sh projects create "My Project" /path/to/project

# Focus on a specific project
./scripts/rag_cli.sh projects focus proj_123

# Ask questions with LLM-enhanced natural language responses
./scripts/rag_cli.sh ask "What authentication system are we using?"

# Get daily briefing with project statistics
./scripts/rag_cli.sh briefing

# Track decisions and objectives
./scripts/rag_cli.sh decisions add "Using Redis for caching" "Performance reasons"
./scripts/rag_cli.sh objectives add "Implement user auth" "High priority"

​
Sacred Plan Management (✅ Currently Working)

# Create architectural plan
./scripts/rag_cli.sh sacred create proj_123 "Database Architecture" plan.md

# Approve with 2-layer verification
./scripts/rag_cli.sh sacred approve plan_abc123

# Check alignment
./scripts/rag_cli.sh sacred drift proj_123

# Check Sacred Layer health
curl http://localhost:5556/sacred/health

​
Claude Code Integration

{
  "env": {
    "RAG_AGENT_URL": "http://localhost:5556"
  }
}

​
📊 Project Structure

contextkeeper/
├── docs/                          # Documentation
│   ├── api/                      # API documentation
│   ├── guides/                   # User guides
│   ├── INSTALLATION.md           # Setup instructions
│   └── USAGE.md                  # Usage guide
├── examples/                      # Usage examples
├── mcp-server/                    # Claude Code integration
├── scripts/                       # CLI and setup scripts
├── tests/                         # Test suite
├── rag_agent.py                  # Main RAG orchestrator
├── sacred_layer_implementation.py # Sacred Layer core
├── git_activity_tracker.py       # Git integration
└── enhanced_drift_sacred.py      # Drift detection

​
🛠️ Development

​
Prerequisites

  • Python 3.8+ with pip
  • Node.js 16+ with npm
  • Git
  • Google Cloud account (for GenAI API)

​
Running Tests

# Install test dependencies
pip install -r requirements.txt

# Run all tests
pytest tests/ -v

# Run specific test suite
pytest tests/sacred/ -v

​
Contributing

We welcome contributions! Please see the repository guidelines: https://github.com/lostmind008/contextkeeper/blob/main/CONTRIBUTING.md

​
📈 Use Cases

  • AI-Assisted Development: Provide architectural context to AI coding assistants
  • Team Collaboration: Shared architectural constraints across development teams
  • Compliance Monitoring: Ensure development aligns with approved designs
  • Knowledge Management: Capture and preserve architectural decisions

​
🔐 Security

  • Local-only storage: No data sent to external services (except Google GenAI for embeddings)
  • Immutable plans: Sacred plans cannot be modified once approved
  • 2-layer verification: Prevents unauthorized plan changes
  • Audit trail: Complete history of all sacred operations

​
📜 License

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

​
🙏 Acknowledgments

​
📞 Support

Made with ❤️ by LostMindAI