195 lines
5.5 KiB
Markdown
195 lines
5.5 KiB
Markdown
# VaultMesh Cognitive Integration
|
||
|
||
**Claude as the 7th Organ of VaultMesh** - A cryptographically-bound AI co-processor.
|
||
|
||
[](/.github/workflows/governance.yml)
|
||
[](/docs/MCP-CONSTITUTION.md)
|
||
[](https://python.org)
|
||
[](/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*
|