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:

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

2.8 KiB Raw Permalink Blame History