# VaultMesh Cognitive Integration

**Claude as the 7th Organ of VaultMesh** - A cryptographically-bound AI co-processor.

[![Governance CI](https://img.shields.io/badge/CI-Passing-success)](/.github/workflows/governance.yml)
[![Constitution](https://img.shields.io/badge/Constitution-v1.0.0-blue)](/docs/MCP-CONSTITUTION.md)
[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](/LICENSE)

## Overview

This package provides a Model Context Protocol (MCP) server that enables Claude to operate as the cognitive layer of VaultMesh - with full cryptographic accountability, profile-based authority, and constitutional governance.

### Features

- **19 MCP Tools** across 4 domains (Guardian, Treasury, Cognitive, Auth)
- **5 Capability Profiles** (Observer → Operator → Guardian → Phoenix → Sovereign)
- **Cryptographic Receipts** for every mutation via BLAKE3
- **Constitutional Governance** with immutable rules and amendment protocol
- **Escalation Engine** with proof-backed authority transitions
- **Ed25519 Authentication** with challenge-response

## Quick Start

```bash
# Clone and install
git clone https://github.com/vaultmesh/cognitive-integration.git
cd cognitive-integration

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install
pip install -e ".[dev]"

# Verify constitution
make verify-constitution

# Run tests (48 governance tests)
make test

# Run Golden Drill
make drill
```

## Structure

```
vaultmesh-cognitive-integration/
├── governance/
│   └── constitution.lock       # Pinned constitution hash
├── packages/vaultmesh_mcp/
│   ├── server.py               # MCP server (19 tools)
│   └── tools/
│       ├── auth.py             # Ed25519 auth + 5 profiles
│       ├── cognitive.py        # 8 cognitive tools
│       ├── escalation.py       # Proof-backed escalation
│       ├── key_binding.py      # Key-profile bindings
│       ├── guardian.py         # Merkle anchoring
│       ├── treasury.py         # Budget management
│       └── file.py             # File operations
├── tests/governance/           # 48 governance tests
├── docs/
│   ├── MCP-CONSTITUTION.md     # Immutable governance law
│   ├── MCP-AUTHORITY-MATRIX.md # Tool × Profile matrix
│   └── DRILL.md                # Controlled failure runbook
├── keys/                       # Guardian + Sovereign keys
├── realms/cognitive/memory/    # CRDT memory realm
└── .github/workflows/
    └── governance.yml          # CI pipeline
```

## Profiles

| Profile | Symbol | Trust | Key Binding |
|---------|--------|-------|-------------|
| OBSERVER | 👁 | Minimal | Ephemeral |
| OPERATOR | ⚙ | Moderate | Session |
| GUARDIAN | 🛡 | High | Device-bound |
| PHOENIX | 🔥 | Maximum | Time-locked |
| SOVEREIGN | 👑 | Absolute | Hardware |

## Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vaultmesh": {
      "command": "python",
      "args": ["-m", "vaultmesh_mcp.server"],
      "env": {
        "VAULTMESH_ROOT": "/path/to/vaultmesh-cognitive-integration"
      }
    }
  }
}
```

## Tools

### Guardian Tools (Merkle Anchoring)
- `guardian_anchor_now` - Anchor scrolls to Merkle root
- `guardian_verify_receipt` - Verify receipt in scroll
- `guardian_status` - Get status of all scrolls

### Treasury Tools (Budget Management)
- `treasury_create_budget` - Create budget (SOVEREIGN only)
- `treasury_balance` - Check balance
- `treasury_debit` - Spend from budget
- `treasury_credit` - Add to budget

### Cognitive Tools (AI Reasoning)
- `cognitive_context` - Read mesh context
- `cognitive_decide` - Submit attested decision
- `cognitive_invoke_tem` - Invoke threat transmutation
- `cognitive_memory_get` - Query CRDT memory
- `cognitive_memory_set` - Store reasoning artifacts
- `cognitive_attest` - Create cryptographic attestation
- `cognitive_audit_trail` - Query decision history
- `cognitive_oracle_chain` - Execute compliance oracle

### Auth Tools (Authentication)
- `auth_challenge` - Generate Ed25519 challenge
- `auth_verify` - Verify signature, issue token
- `auth_check_permission` - Check tool permission
- `auth_create_dev_session` - Create dev session
- `auth_revoke` - Revoke session
- `auth_list_sessions` - List active sessions

## Testing

```bash
# Run all governance tests
make test

# Run constitution verification
make verify-constitution

# Run Golden Drill (threat → escalate → Tem → de-escalate)
make drill

# Run specific test
pytest tests/governance/test_auth_fail_closed.py -v
```

## Constitution

Version 1.0.0 - Ratified December 18, 2025

```
Hash: blake3:c33ab6c0610ce4001018ba5dda940e12a421a08f2a1662f142e565092ce84788
```

**Statement:** *"This constitution constrains me as much as it constrains the system."*

### Immutable Rules

1. SOVEREIGN profile requires human verification
2. No AI may grant itself SOVEREIGN authority  
3. Every mutation emits a receipt
4. Authority collapses downward, never upward
5. This immutability clause itself

## Development

```bash
# Install with dev dependencies
make dev

# Run linter
make lint

# Format code
make format

# Build package
make build

# Clean artifacts
make clean
```

## License

MIT License - See [LICENSE](LICENSE) for details.

---

🜄 **Solve et Coagula**

*VaultMesh Technologies - Earth's Civilization Ledger*