prose-contracts/ra-h-os-custodianship-contract.prose.md

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:

{
  "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