context-custodians 0.1.2

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"]'

📋 CLI Commands Reference

Context Custodians provides a comprehensive CLI interface for all operations:

Global Options

• --version, -v: Show package version information
• --workspace, -w: Specify workspace path (default: current directory)
• --log-level, -l: Set logging level (DEBUG, INFO, WARNING, ERROR)

Core Commands

vmw init

Initialize Context Custodians in the current workspace.

• Creates .vmw/ directory with configuration and context files
• Sets up default monitoring configuration

vmw start [--daemon]

Start the monitoring system.

• --daemon: Run in background mode (recommended for production)
• Without --daemon: Run in foreground (useful for testing)

vmw stop

Stop all running agents and monitoring processes.

vmw status

Display comprehensive system status including:

• System health overview
• Individual agent status (running/stopped, enabled/disabled)
• Last scan timestamp
• Configuration summary
• Monitored files count

vmw scan

Execute a manual scan of all monitored files.

• Triggers all agents to process current file state
• Useful for testing and immediate updates

Configuration Commands

vmw config --show

Display current configuration in YAML format.

vmw config --set <key> <value>

Modify configuration values. Examples:

vmw config --set monitoring.interval_seconds 300
vmw config --set agents.file_watcher.enabled false
vmw config --set output.context_file 'CUSTOM_CONTEXT.md'

Service Management (Linux)

vmw install-service

Install Context Custodians as a systemd service.

• Creates service file in /etc/systemd/system/
• Requires sudo privileges

vmw uninstall-service

Remove the systemd service.

• Deletes service file
• Requires sudo privileges

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