Architecture

Current runtime, retrieval, and graph contract

Overview

RA-H uses one local graph plus two main interaction surfaces:

  • the app UI
  • MCP for external agents

The graph is built around:

  • nodes - durable artifacts like sources, ideas, people, projects, and decisions
  • edges - explicit reasons two nodes are connected
  • chunks - readable slices of long source text
  • full-text indexes - exact or near-literal lookup
  • node-level embeddings - semantic lookup over whole nodes
  • chunk-level embeddings - semantic lookup over source passages

Current Doctrine

  • dimensions are retired from the live runtime contract
  • contexts and the old context capsule are removed from the live runtime contract
  • node quality comes from title, description, source, metadata, and explicit edges
  • direct lookup comes before broader retrieval when the user is clearly trying to find a specific node
  • durable writeback and edge changes are confirmation-gated where the tool contract says they are

App Runtime

The app gives you:

  • feed, map, table, skills, and focused-node work
  • right-edge chat inside the active workspace
  • app-owned chunking and embedding from nodes.source

External Agents Via MCP

External agents connect to the same graph through MCP.

Expected behavior:

  1. use queryNodes for direct existing-node lookup
  2. use retrieveQueryContext when broader graph context would help
  3. use getContext only for orientation
  4. search before creating
  5. propose durable writeback and edges selectively, with confirmation where required

Search And Indexing

RA-H stores source text in SQLite and builds retrieval surfaces around it:

source text
  |
  +--> nodes_fts for exact node lookup
  +--> chunks for readable source slices
          |
          +--> chunks_fts for exact passage lookup
          +--> vec_chunks for semantic passage lookup

nodes.embedding_text --> vec_nodes for whole-node semantic lookup

This lets RA-H retrieve a focused slice of the graph instead of asking an agent to scan a folder of markdown files every turn.

The distinction matters:

  • vec_nodes helps find the right saved object.
  • vec_chunks helps find the right excerpt inside that object.
  • nodes.embedding_text is the readable input used for the whole-node embedding.
  • chunks.text is the readable input used for passage-level embeddings.

Graph Quality

RA-H gets stronger from:

  • clear titles
  • grounded descriptions
  • preserved source text
  • explicit edge explanations

It does not get stronger from reviving a retired taxonomy system.