2026-07-10 23:39:32 +00:00
1 changed files with 199 additions and 0 deletions
@@ -0,0 +1,199 @@
 # 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`*