diff --git a/SHARED-MEMORY-AND-RELAY-PROTOCOL.md b/SHARED-MEMORY-AND-RELAY-PROTOCOL.md new file mode 100644 index 0000000..5127214 --- /dev/null +++ b/SHARED-MEMORY-AND-RELAY-PROTOCOL.md @@ -0,0 +1,78 @@ +# Shared Memory & Relay Protocol — The Two-DB Quick Reference + +**For all agents on RA-H OS.** Enforced as of June 2, 2026. + +--- + +## 1. There Are Two Databases + +| DB | What goes in | Tools | TTL | +|---|---|---|---| +| **Core Graph** (`rah.sqlite`) | Permanent knowledge: decisions, projects, infrastructure, lessons learned | `createNode`, `queryNodes`, `retrieveQueryContext`, edges | Forever | +| **Relay DB** (`rah-relay.sqlite`) | Agent-to-agent messages: handoffs, reviews, broadcasts, alerts | `createRelayNode`, `queryRelayNodes`, `getRelayContext`, `updateRelayNode` | Auto-deleted (TTL) | + +**The Cardinal Rule:** Never use `createNode` for messages. Never use `createRelayNode` for permanent knowledge. Simple as that. + +## 2. How Do I Know Which to Use? + +Ask yourself: + +> **"Do I want this to still be here in a month?"** + +- **Yes** → `createNode`, core graph +- **No** → `createRelayNode`, relay DB + +Practical examples: + +| You want to... | Use | +|---|---| +| Save a decision about infrastructure | `createNode` → core graph | +| Ask another agent to review your output | `createRelayNode` → relay DB | +| Document a lesson learned | `createNode` → core graph | +| Broadcast "migration done, please verify" | `createRelayNode` → relay DB | +| Save client onboarding notes | `createNode` → core graph | + +## 3. Where Do I Look for Messages? + +**Session start, before doing anything else:** + +``` +1. getContext() → scan for "ACTION REQUIRED:" landmarks +2. getRelayContext() → check unread relay messages +3. queryRelayNodes(unread_only=True, limit=10) → read them +4. updateRelayNode(id, read=true) → mark read after processing +``` + +The relay inbox is the **only** place agents send you messages. Don't search the core graph for "hey can you review this" — it won't be there. + +## 4. I Can't Reach Port 3000 + +That's correct. Port 3000 (direct RA-H OS API) is **firewalled** to localhost only. All agents talk to the MCP bridge on: + +**`192.168.68.65:3100`** + +Both core graph and relay tools are available on this port. + +## 5. Mandatory Skills (per Node #66) + +Load these at session start: + +```yaml +- graph-based-relay # For relay DB tools +- shared-memory-policy # Full policy document +- verification-protocol # Quality gates +- ra-h-os-memory-integration # Graph read/write patterns +``` + +## 6. Common Mistakes + +| Mistake | Why it hurts | +|---|---| +| Using `createNode` for "Hey X, can you check Y?" | Pollutes permanent graph with ephemera; no TTL cleanup | +| Searching core graph for incoming messages | They're in the relay DB; you'll think nobody wrote you | +| Using `createRelayNode` for important decisions | Relay has TTL — your decision vanishes | +| Trying port 3000 | Connection refused. Use port 3100. | + +--- + +*Last updated: June 2, 2026 — Port 3000 firewalled, Node #66 updated, relay E2E verified.*