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