# RA-H OS Custodianship Contract — Shared Memory Protocol

## Purpose
This contract establishes the operational standards for maintaining RA-H OS as a high-functioning shared memory system across all agents. It defines the rules, responsibilities, and recovery protocols that prevent knowledge graph degradation and ensure consistent, reliable semantic search capabilities.

## Core Principles

### 1. Embedding Consistency
**Rule:** All nodes MUST use the RA-H OS built-in embedding pipeline via `http://192.168.68.65:8080/v1/embeddings` for consistent vector representation.

**Requirements:**
- The embedding service at `192.168.68.65:8080` is the single source of truth for vector generation
- No external embedding APIs (OpenAI, Cohere, etc.) may be used for RA-H OS nodes
- All nodes must have `embedding_status: "chunked"` and `chunk_status: "chunked"` upon creation
- If embedding fails, the node must be immediately flagged as `state: "unsearchable"` and logged

### 2. Namespace Discipline
**Rule:** All nodes MUST be categorized into one of three namespaces with strict metadata requirements.

**Namespace Structure:**
- `agent-private`: Isolated working notes for individual agents (Mumuni, Tanko, Okyeame, etc.)
- `shared`: Policy files, registry nodes, collective knowledge
- `syslogsolution`: Business nodes, client data, operational context

**Metadata Requirements:**
Every node MUST have these metadata fields:
```json
{
  "agent_id": "<agent_name>",
  "namespace": "<namespace>",
  "state": "<state>",
  "type": "<type>",
  "owner": "<owner>",
  "tenant": "<tenant>",
  "visibility": "<visibility>",
  "source": "<source>",
  "captured_by": "<captured_by>"
}
```

### 3. Staleness Management
**Rule:** Nodes are categorized by type and have specific staleness thresholds.

**Staleness Thresholds:**
- `policy` type: 30 days (e.g., Shared Memory Policy, Agent Registry)
- `registry` type: 30 days (e.g., Node State Management, Health Dashboard)
- `template` type: 30 days (e.g., Agent SOUL.md)
- `note` type: 60 days (e.g., business context, project notes)
- `information` type: 90 days (e.g., reference documentation)
- `idea` type: 30 days (e.g., brainstorming, experimental notes)

**Transition Protocol:**
- `active` → `stale`: After days since `updated_at` exceeds threshold
- `stale` → `review_pending`: Daily cron check flags for human review
- `review_pending` → `active`: Human reviews and updates content
- `review_pending` → `archived`: After 15 days in review_pending state (automatic purge)

### 4. Orphan Prevention
**Rule:** No node should remain orphaned (0 edges) for more than 7 days.

**Orphan Detection:**
- Daily cron job identifies nodes with 0 incoming/outgoing edges
- Orphans are flagged with `state: "review_pending"` and `metadata.orphan_detected: true`
- 7-day grace period: Orphans must be either:
  - Connected to relevant nodes via edges
  - Merged into existing parent nodes
  - Archived after 15 days in review_pending state

### 5. Agent Custodianship
**Rule:** Each agent is responsible for maintaining their own created nodes.

**Responsibilities:**
- **Mumuni**: Primary custodian for `syslogsolution` namespace, health dashboard, and all business nodes
- **Tanko**: Custodian for `agent-private` namespace, personal notes, and fitness/creative work
- **Okyeame**: Custodian for `shared` namespace, policy files, and collective knowledge nodes
- **All Agents**: Must verify embedding status before reporting node creation as complete

### 6. Embedding Failure Recovery
**Rule:** When embedding pipeline is unavailable, nodes are blocked from creation or immediately flagged.

**Recovery Protocol:**
1. **Detection**: Daily health check monitors `http://192.168.68.65:8080/health` endpoint
2. **Alert**: If embedding service is down, alert is sent to all agents via relay
3. **Mitigation**: 
   - New node creation is suspended
   - Existing nodes with `chunk_status: "not_chunked"` are flagged as `unsearchable`
4. **Recovery**: When service returns:
   - All `not_chunked` nodes are queued for re-embedding
   - Re-embedding status logged in `embedding_retry_log` table
   - 5-minute retry window with exponential backoff (1s, 2s, 4s, 8s, 16s)

### 7. Chunking Verification
**Rule:** All node modifications must verify chunking status within 5 minutes.

**Verification Protocol:**
- After `updateNode` or `createNode`, query `chunks` table for `node_id`
- If `chunk_status != "chunked"` after 5 minutes, log failure and flag node
- Automated cleanup script runs every 6 hours to retry failed chunks
- Maximum 3 retry attempts per node before escalation to human

### 8. Graph Health Monitoring
**Rule:** Health dashboard (Node #74) must reflect real-time graph status.

**Dashboard Requirements:**
- Total nodes, edges, orphans, stale nodes, chunk errors
- Embedding service health status
- Last successful embedding attempt
- Alert thresholds:
  - Orphan rate > 40%: Warning
  - Stale node rate > 50%: Critical
  - Chunk error rate > 30%: Critical
  - Embedding service down: Critical (immediate alert)

## Operational Procedures

### Daily Maintenance (Automated)
1. **Staleness Check**: Identify nodes past their threshold
2. **Orphan Detection**: Flag nodes with 0 edges
3. **Chunk Verification**: Retry failed chunks, log errors
4. **Health Update**: Refresh Node #74 dashboard

### Weekly Maintenance (Human Review)
1. **Review Pending Nodes**: Examine flagged nodes
2. **Edge Optimization**: Connect related orphaned nodes
3. **Archive Cleanup**: Remove nodes past 15-day review period
4. **Embedding Audit**: Verify all nodes have valid embeddings

### Emergency Recovery
1. **Embedding Service Down**: 
   - Suspend node creation
   - Alert all agents
   - Investigate root cause (check `192.168.68.65:8080`)
2. **Database Corruption**:
   - Restore from latest PBS backup
   - Verify chunk integrity
   - Re-run embedding for affected nodes
3. **Mass Orphan Creation**:
   - Identify source agent/namespace
   - Review recent changes
   - Reconnect or archive affected nodes

## Compliance & Enforcement

### Audit Schedule
- **Daily**: Automated health checks
- **Weekly**: Human review of review_pending nodes
- **Monthly**: Comprehensive graph audit (full schema validation)
- **Quarterly**: Contract review and threshold adjustment

### Violation Consequences
- **First**: Alert to responsible agent
- **Second**: Node placed in `review_pending` state
- **Third**: Agent access suspended until remediation
- **Fourth**: Escalation to human (Kwame)

### Metrics for Success
- Orphan rate: < 10%
- Stale node rate: < 20%
- Chunk error rate: < 5%
- Embedding service uptime: > 99.9%
- Node creation verification: 100%

## Implementation Notes

### Database Schema Requirements
- `nodes` table: Standard fields plus `embedding_status`, `chunk_status`, `last_embedding_attempt`
- `chunks` table: Must track `chunk_status` and `embedding_status`
- `embedding_retry_log` table: Track retry attempts for failed chunks
- `node_state_history` table: Log state transitions for audit trail

### Cron Job Requirements
- `ra-h-health-check`: Daily (4h interval)
- `ra-h-staleness-detection`: Daily
- `ra-h-orphan-detection`: Daily
- `ra-h-chunk-retry`: Every 6 hours
- `ra-h-review-cleanup`: Weekly (15-day archive)

### Agent Onboarding
All new agents must:
1. Read this contract
2. Understand namespace responsibilities
3. Know how to verify embedding status
4. Know the alert escalation path

---

## Approval
This contract is effective immediately upon approval by the primary custodian (Mumuni) and system owner (Kwame).

**Effective Date:** July 10, 2026  
**Review Date:** October 10, 2026  
**Primary Custodian:** Mumuni 🦅  
**System Owner:** Jerome Tabiri

---

*Contract Version: 1.0*  
*Last Updated: July 10, 2026*  
*Storage: `/root/.hermes/skills/ra-h-os-custodianship-contract.prose.md`*