From b96b33428340fc0eec5239e76fc49a026bcff962 Mon Sep 17 00:00:00 2001 From: Jerome Tabiri Date: Fri, 10 Jul 2026 09:43:49 -0400 Subject: [PATCH 1/2] feat: add RA-H OS Custodianship Contract for shared memory protocol --- ra-h-os-custodianship-contract.prose.md | 199 ++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 ra-h-os-custodianship-contract.prose.md diff --git a/ra-h-os-custodianship-contract.prose.md b/ra-h-os-custodianship-contract.prose.md new file mode 100644 index 0000000..1b05579 --- /dev/null +++ b/ra-h-os-custodianship-contract.prose.md @@ -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": "", + "namespace": "", + "state": "", + "type": "", + "owner": "", + "tenant": "", + "visibility": "", + "source": "", + "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`* \ No newline at end of file -- 2.54.0 From 44ba53cf716879212b0f575c71580e25b96ecbeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mumuni=20=F0=9F=A6=85=20=28Syslog=20Falcon=29?= Date: Fri, 10 Jul 2026 19:16:30 -0400 Subject: [PATCH 2/2] fix: add YAML frontmatter to RA-H OS Custodianship Contract - Added required frontmatter block with kind=pattern, name, and description - Fixes CI validate step that was blocking the PR pipeline - All other CI checks (lint, ai-review) were skipped due to validate failure --- ra-h-os-custodianship-contract.prose.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/ra-h-os-custodianship-contract.prose.md b/ra-h-os-custodianship-contract.prose.md index 1b05579..169454b 100644 --- a/ra-h-os-custodianship-contract.prose.md +++ b/ra-h-os-custodianship-contract.prose.md @@ -1,3 +1,14 @@ +--- +kind: pattern +name: ra-h-os-custodianship-contract +description: > + Operational standards for maintaining RA-H OS as a high-functioning shared + memory system across all agents. Defines rules for embedding consistency, + namespace discipline, staleness management, orphan prevention, agent + custodianship, and recovery protocols. Prevents knowledge graph degradation + and ensures reliable semantic search capabilities. +--- + # RA-H OS Custodianship Contract — Shared Memory Protocol ## Purpose -- 2.54.0