Add two-DB quick reference cheat sheet for agents

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.*