context-custodians 0.1.2
Multi-agent context monitoring system for AI assistants
Requires Python: >=3.8

# Context Custodians - Vitruvyan Memory Warden

*Epistemic Guardian of Dynamic Context - Sacred Order #6*

[![PyPI version](https://badge.fury.io/py/context-custodians.svg)](https://pypi.org/project/context-custodians/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
# 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

```bash
# 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

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

# Or run a one-time scan
vmw scan
```

### Check Status

```bash
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`:

```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

```bash
# Initialize
vmw init

# Start monitoring
vmw start --daemon

# Check what's happening
vmw status

# Stop monitoring
vmw stop
```

### Configuration Management

```bash
# 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:
```bash
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)

```bash
# 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

```bash
# 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

```bash
# System status
vmw status

# Manual scan
vmw scan

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

### Common Issues

**Agents not starting:**
```bash
# Check agent configuration
vmw config --show | grep agents

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

**Permission errors:**
```bash
# Run with proper permissions
sudo vmw start --daemon
```

**High resource usage:**
```bash
# Increase monitoring interval
vmw config --set monitoring.interval_seconds 600
```

## 🛠️ Development

### Setting up Development Environment

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

### Running Tests

```bash
pytest tests/
```

### Building Documentation

```bash
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](CONTRIBUTING.md) 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](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](https://github.com/vitruvyan-ai/context-custodians/issues)
- **Discussions**: [GitHub Discussions](https://github.com/vitruvyan-ai/context-custodians/discussions)
- **Documentation**: [Read the Docs](https://context-custodians.readthedocs.io/)

---

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