context-custodians 0.1.0

Multi-agent context monitoring system for AI assistants

Context Custodians - Vitruvyan Memory Warden

Epistemic Guardian of Dynamic Context - Sacred Order #6

A multi-agent containerized system for autonomous context monitoring and maintenance. Continuously watches critical project files, extracts vital information, and keeps AI assistants always informed with the latest project state.

✨ Features

• 🤖 Multi-Agent Architecture: Specialized agents for file monitoring, vital extraction, context updates, and health monitoring
• 🔄 Autonomous Operation: Runs as background service, detecting changes and updating context in real-time
• 🏛️ Epistemic Design: Follows Sacred Orders pattern with modular, resilient agents
• 📦 Containerized: Easy deployment in any Docker environment
• 🔧 Configurable: YAML-based configuration for watched files and update intervals
• 📊 Health Monitoring: Built-in diagnostics and performance metrics
• 🔌 Systemd Integration: Optional always-on service with automatic restarts

🚀 Quick Start

Installation

# Install from PyPI
pip install context-custodians

# Or install from source
git clone https://github.com/vitruvyan-ai/context-custodians.git
cd context-custodians
pip install -e .

Initialize in Your Project

# Navigate to your project
cd /path/to/your/project

# Initialize Context Custodians
vmw init

This creates a .vmw/ directory with configuration and context files.

Start Monitoring

# Start in daemon mode (background)
vmw start --daemon

# Or run a one-time scan
vmw scan

Check Status

vmw status

🏗️ Architecture

Context Custodians uses a multi-agent architecture inspired by biological systems:

Core Agents

• FileWatcherAgent: Monitors file changes using SHA256 hashing
• VitalExtractorAgent: Extracts critical information from modified files
• ContextUpdaterAgent: Updates context files with fresh data
• HealthMonitorAgent: Ensures system reliability and performance
• CoordinatorAgent: Orchestrates agent workflow and communication

Workflow

File Change Detected
    ↓
FileWatcherAgent → CoordinatorAgent
    ↓
VitalExtractorAgent → Extracts vital info
    ↓
ContextUpdaterAgent → Updates .md files
    ↓
HealthMonitorAgent → Validates system health

⚙️ Configuration

Configuration is stored in .vmw/config.yaml:

version: '0.1.0'
workspace: '/path/to/project'
monitoring:
  enabled: true
  interval_seconds: 300
  watched_files:
    - '.github/copilot-instructions.md'
    - 'docker-compose.yml'
    - 'pyproject.toml'
    - 'README.md'
  ignored_patterns:
    - '*.log'
    - '__pycache__/*'

agents:
  file_watcher:
    enabled: true
  vital_extractor:
    enabled: true
  context_updater:
    enabled: true
  health_monitor:
    enabled: true
  coordinator:
    enabled: true

output:
  context_file: 'ALWAYS_AVAILABLE_CONTEXT.md'
  vital_updates_file: 'VITAL_UPDATES.md'

🔧 Usage Examples

Basic Monitoring

# Initialize
vmw init

# Start monitoring
vmw start --daemon

# Check what's happening
vmw status

# Stop monitoring
vmw stop

Configuration Management

# Show current config
vmw config --show

# Change monitoring interval
vmw config --set monitoring.interval_seconds 600

# Add a file to watch
vmw config --set monitoring.watched_files '["file1.txt", "file2.py"]'

Systemd Service (Linux)

# Install as system service
sudo vmw install-service

# Enable auto-start
sudo systemctl enable vitruvyan-memory-warden

# Start service
sudo systemctl start vitruvyan-memory-warden

# Check status
sudo systemctl status vitruvyan-memory-warden

Docker Deployment

# Build container
docker build -t context-custodians .

# Run container
docker run -d \
  --name context-custodians \
  -v $(pwd):/workspace \
  -v $(pwd)/.vmw:/context \
  context-custodians

📁 Generated Files

Context Custodians creates and maintains these files in your .vmw/ directory:

• ALWAYS_AVAILABLE_CONTEXT.md: Main context file for AI assistants
• VITAL_UPDATES.md: Detailed changelog of recent changes
• config.yaml: Configuration file
• state.json: Internal state and file hashes

🤖 How It Helps AI Assistants

GitHub Copilot Integration

1. Automatic Context Updates: When you modify critical files, Context Custodians immediately updates the context
2. Always Current Information: Copilot reads the latest project state without manual intervention
3. Reduced Hallucinations: Accurate, up-to-date information prevents AI confusion
4. Project Continuity: Seamless context across sessions and team members

Example Workflow

You: "How do I deploy this service?"
Copilot reads ALWAYS_AVAILABLE_CONTEXT.md
Copilot sees: "Services: web, api, db | Ports: 3000, 8000, 5432"
Copilot responds: "Based on your docker-compose.yml, deploy with..."

🔍 Monitoring & Troubleshooting

Health Checks

# System status
vmw status

# Manual scan
vmw scan

# View logs (if configured)
tail -f .vmw/agent_logs.json

Common Issues

Agents not starting:

# Check agent configuration
vmw config --show | grep agents

# Enable specific agent
vmw config --set agents.file_watcher.enabled true

Permission errors:

# Run with proper permissions
sudo vmw start --daemon

High resource usage:

# Increase monitoring interval
vmw config --set monitoring.interval_seconds 600

🛠️ Development

Setting up Development Environment

git clone https://github.com/vitruvyan-ai/context-custodians.git
cd context-custodians
pip install -e .[dev]

Running Tests

pytest tests/

Building Documentation

mkdocs build

📊 Performance

• Memory Usage: ~50MB baseline, scales with project size
• CPU Usage: Minimal (<1% when idle, <5% during scans)
• Storage: ~1KB per watched file for hash storage
• Response Time: <100ms for file change detection

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

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

🙏 Acknowledgments

• Inspired by the Vitruvyan AI ecosystem
• Built with the Sacred Orders architectural pattern
• Designed for the AI-assisted development workflow

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Read the Docs

---

Keep your AI assistants in the loop! 🚀# Test Update - Thu Jan 1 21:13:26 CET 2026