ra-h-os/docs/3_context-and-memory.md

Context & Memory

How RA-H decides what information to show the AI during conversations.

How it works: RA-H automatically identifies your 10 most-connected knowledge nodes (by edge count) and shares their titles with the AI as background context. When you focus on a specific node, the AI also sees a preview of that content. This means the AI always knows about your most important ideas without you having to manually select them.

---

Context System Overview

Every conversation includes context assembled by the context builder. This context tells the AI about your knowledge base, available tools, and what you're currently working on.

What Gets Included

Block	Contents	Cached?
Base Context	How nodes, edges, dimensions work; formatting rules	✅ Yes
Agent Instructions	Role-specific prompts (ra-h, ra-h-easy, wise-rah, mini-rah)	✅ Yes
Tool Definitions	Available tools and their parameters	✅ Yes
Workflow Definitions	Available workflows (orchestrators only)	✅ Yes
Background Context	Top 10 most-connected nodes (if enabled)	✅ Yes
Focused Nodes	Currently open node(s) with content previews	❌ No

---

Auto-Context System

Auto-context automatically includes your most important knowledge in every conversation. It replaces the old manual "pinning" system.

How It Works

1. Toggle: Enable in Settings → Context tab
2. Query: Finds top 10 nodes by edge count (most connections = most important)
3. Format: Shows [NODE:id:"title"] (edges: X) for each hub node
4. Agent behavior: Agents see titles only; they call queryNodes or getNodesById when they need full content

The Query

SELECT n.id, n.title, COUNT(DISTINCT e.id) AS edge_count
FROM nodes n
LEFT JOIN edges e ON (e.from_node_id = n.id OR e.to_node_id = n.id)
WHERE n.type IS NULL OR n.type != 'memory'
GROUP BY n.id
ORDER BY edge_count DESC, n.updated_at DESC
LIMIT 10

Tie-breaking: When nodes have equal edge counts, most recently updated wins.

Settings Storage

Location: ~/Library/Application Support/RA-H/config/settings.json

{
  "autoContextEnabled": true,
  "lastPinnedMigration": "2025-12-09T00:00:00Z"
}

Legacy migration: If you had pinned nodes before the auto-context update, the system automatically enabled auto-context on first run.

Context Block Format

When enabled, agents see this in their system prompt:

=== BACKGROUND CONTEXT ===
Top 10 most-connected nodes (important knowledge hubs). Use queryNodes/getNodesById if relevant.

[NODE:1573:"building ra-h - knowledge management system"] (edges: 47)
[NODE:4436:"Continual learning explains some interesting phenomena"] (edges: 32)
[NODE:3014:"Multi-Agent Research Systems: Insights from Simon Willison"] (edges: 28)
...

---

Focused Nodes

Focused nodes are the node(s) you currently have open in the Focus panel.

What Agents See

• Primary focused node: The active tab
• Additional focused nodes: Other open tabs
• Content preview: First ~25 words
• Metadata: Title, ID, link, dimensions, chunk status

Example Format

=== FOCUSED NODES ===

### Primary: [NODE:4523:"How RAG systems work"]
Preview: Retrieval-augmented generation (RAG) combines information retrieval with language model generation to produce more accurate and grounded responses...
Link: https://example.com/rag-systems
Dimensions: research, ai, papers
Chunk status: chunked (embeddings available)

### Also Open:
- [NODE:4520:"Vector databases explained"] (25 words preview...)

---

Context Caching

RA-H uses provider-specific caching to reduce costs and latency.

Anthropic (Claude)

• Explicit cache control: Blocks marked with cache_control: { type: 'ephemeral' }
• What's cached: Base context, instructions, tools, workflows, background context
• What's NOT cached: Focused nodes (change too frequently)

OpenAI (GPT)

• Implicit caching: Based on prefix matching
• Same structure: Identical blocks, just no explicit markers
• Optimization: Prompts structured for maximum cache reuse

---

Agent-Specific Context

Different agents receive different context based on their role:

Agent	Background Context	Workflows	Tools
ra-h / ra-h-easy (orchestrators)	✅ Yes	✅ Yes	All
wise-rah (workflow executor)	❌ No	❌ No	Planner tools only
mini-rah (worker)	❌ No	❌ No	Executor tools only

Why orchestrators only: Background context helps with general conversation. Workers execute specific tasks and don't need the full picture.

---

Key Files

File	Purpose
src/services/helpers/contextBuilder.ts	Assembles system prompts with caching
src/services/context/autoContext.ts	Auto-context query and formatting
src/services/settings/autoContextSettings.ts	Settings read/write helpers
src/components/settings/ContextViewer.tsx	Settings UI for auto-context toggle

---

Legacy: Memory System (Removed)

The automatic memory extraction pipeline has been removed. Previously, RA-H would analyze conversations and create "memory" nodes automatically. This system was removed because:

1. Memory nodes cluttered the database
2. Quality was inconsistent
3. Users preferred explicit knowledge capture

Existing memory nodes: Still in the database but excluded from auto-context (filtered by type != 'memory').

Future approach: Store long-term knowledge as regular nodes with explicit dimensions rather than automatic extraction.