SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: sync open-source context and capsule removal

Browse Source 
- remove legacy contexts surfaces from the app, MCP bridge, standalone server, and docs
- keep getContext and retrieveQueryContext while aligning the simplified graph-only contract
- harden dev startup migration behavior and disable the accidental chat surface in open source

Generated with Codex
This commit is contained in:
“BeeRad”
2026-04-17 12:34:51 +10:00
parent 97eeb0789f
commit 07754f5030
87 changed files with 2688 additions and 4861 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0_overview.md
+41 -48
View File
@@ -1,78 +1,71 @@
# RA-H OS Overview
# RA-H Overview
## What is RA-OS?
## What is RA-H?
RA-H OS is the open-source local graph surface of RA-H. It gives you the graph, UI, and MCP path without the private Mac-app-only packaging and subscription surfaces.
RA-H is a local-first knowledge graph for durable thinking. It captures sources, ideas, people, decisions, and conversations into one graph on your machine, then lets you retrieve and extend that graph through the app and MCP.
**Website:** [ra-h.app](https://ra-h.app)
**Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
**New here?** Open chat and say `let's get started` to run the onboarding skill.
## Design Philosophy
**Local-first** — Your knowledge network belongs to you. Everything runs locally in a SQLite database you control.
RA-H is built on the idea that capture quality matters more than taxonomy.
**External-agent friendly** — The open-source path is designed to work well with external MCP clients. The graph contract should not depend on prompt hacks or old taxonomy assumptions.
**Non-prescriptive** — RA-H does not require folders or dimensions. It pushes clearer nodes and clearer edges instead of category maintenance.
**Simple & focused** — The open-source surface keeps the graph, UI, and MCP contract. It does not try to mirror every private-app surface.
**Everything is connected** — Every piece of knowledge can potentially connect to any other. Connections aren't just links — they carry context, explanation, and meaning.
**Local-first** — Your knowledge network belongs to you, not a platform. Your thinking, research, and connections all belong to you in a portable format you control.
**Human + AI** — You guide, AI assists. Skills and graph quality shape behavior; the graph is not supposed to silently self-organize into truth without you.
## Tech Stack
- **Frontend:** Next.js 15, TypeScript, Tailwind CSS
- **Database:** SQLite + sqlite-vec (vector search)
- **Embeddings:** OpenAI (BYO API key)
- **AI Models:** Anthropic Claude + OpenAI GPT via Vercel AI SDK
- **Desktop:** Tauri (Mac app)
- **MCP Server:** Local connector for Claude Code and external agents
## What's Included
## Current Status
- Multi-pane UI for feed, contexts, map, table, node focus, and skills
- Node/Edge CRUD with optional contexts
- Full-text and semantic search
- MCP server with graph and skill tools
- Skills system (shared instructions for internal + external agents)
- PDF extraction
- Graph visualization (Map view)
- BYO API keys
- **Version:** current internal product contract as of April 2026
- **Platforms:**
- Mac app (download at [ra-h.app/download](https://ra-h.app/download))
- Open source self-hosted (BYO API keys)
- **License:** MIT (open source version)
## What's NOT Included
## Two Ways to Use RA-H
- Private-app-only built-in assistant experience
- Voice features
- Auth/subscription system
- Desktop packaging
| Version | Best For | Get It |
|---------|----------|--------|
| **Mac App** | Most users. One-click install, auto-updates, optional subscription features | [ra-h.app/download](https://ra-h.app/download) |
| **Open Source** | Developers, self-hosters, contributors. BYO API keys, full control | [GitHub](https://github.com/bradwmorris/ra-h_os) |
## Current Doctrine
Both versions follow the same core graph contract. The Mac app adds packaging, auth, voice, and subscription surfaces. `ra-h_os` keeps the local graph, UI, and MCP path.
- no runtime `dimensions`
- optional `contexts`
- node quality driven by `title`, `description`, `source`, `metadata`, and `edges`
- direct lookup first, broader retrieval when useful
- app-owned chunking and embeddings from `nodes.source`
## Key Features
## MCP Integration
RA-OS is designed to be the knowledge backend for your AI workflows:
```json
{
"mcpServers": {
"ra-h": {
"command": "npx",
"args": ["--yes", "ra-h-mcp-server@2.1.2"]
}
}
}
```
Add this to `~/.claude.json` and restart Claude. Run RA-H once first so the database exists. The standalone MCP server can write nodes without the app running, but the app owns chunking and embedding from node source. If you publish a newer MCP release and need clients to pick it up immediately, bump the pinned version here and restart the client.
Core tools include: `queryNodes`, `retrieveQueryContext`, `createNode`, `writeContext`, `updateNode`, `getNodesById`, `createEdge`, `updateEdge`, `queryEdge`, `queryContexts`, `listSkills`, `readSkill`
- **Source-first graph:** node quality comes from title, description, source, metadata, and edges
- **Graph-first capture:** durable structure comes from nodes and edges, not category maintenance
- **Flexible pane system:** explicit `1 / 2 / 3` pane workspace with right-edge chat
- **Single assistant:** one built-in RA-H runtime grounded in your graph and skills
- **Retrieval split:** direct lookup for specific nodes, broader retrieval when the turn actually needs graph context
- **MCP server:** connect Claude Code and other external agents to the same graph
- **Skills:** markdown procedures that shape graph work and agent behavior
- **Extraction tools:** website, YouTube, and PDF ingestion paths
## Documentation
| Doc | Description |
|-----|-------------|
| [Architecture](./1_architecture.md) | Single-agent runtime, tools, and system design |
| [Schema](./2_schema.md) | Database schema, node/edge structure |
| [Tools & Skills](./4_tools-and-guides.md) | Available MCP tools, skill system |
| [Context](./3_context.md) | How context flows through the system |
| [Tools & Skills](./4_tools-and-guides.md) | Available tools, skill system |
| [UI](./6_ui.md) | Component structure, panels, views |
| [Voice](./7_voice.md) | Voice interface (STT/TTS) |
| [MCP](./8_mcp.md) | External agent connector setup |
| [Full Local](./10_full-local.md) | Supported local path and community patterns |
| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
| [Open Source](./9_open-source.md) | Contributor and sync guide |
docs/2_schema.md
+16 -28
View File
@@ -11,15 +11,6 @@
- `metadata`
- `chunk_status`
- `event_date`
- `context_id` nullable FK to `contexts.id`
- `created_at`
- `updated_at`
### `contexts`
- `id`
- `name`
- `description`
- `icon`
- `created_at`
- `updated_at`
@@ -51,38 +42,35 @@
- `chunks_fts` indexes chunk text.
- `vec_nodes` stores node-level vectors.
- `vec_chunks` stores chunk-level vectors.
Full-text search and vector search are separate surfaces:
- FTS uses `nodes_fts` / `chunks_fts`
- semantic/vector retrieval uses `vec_nodes` / `vec_chunks`
- retrieval may combine them, but docs should not blur them into one surface
- Full-text search and vector search are separate surfaces:
- FTS uses `nodes_fts` / `chunks_fts`
- semantic/vector retrieval uses `vec_nodes` / `vec_chunks`
- retrieval can combine them, but they should not be described as the same thing
## Embedding Lifecycle
- `nodes.source` is the canonical long-form field for chunking and chunk embeddings.
- changing `nodes.source` should return the node to the app-owned chunk pipeline
- standalone MCP can write `nodes.source`, but it does not directly create chunks or vector rows
- node-level embeddings and chunk embeddings are separate runtime surfaces
- integrity/degraded-mode behavior matters enough that docs should describe these surfaces honestly
- Creating or changing `nodes.source` must put the node back through the app-owned chunk pipeline so the `chunks` rows, `chunks_fts`, and `vec_chunks` state reflect the latest source.
- Standalone MCP can write `nodes.source`, but it does not directly create `chunks` or vector rows. The app later processes those pending nodes.
- Deleting a node must remove dependent chunk rows and must not leave stale node/chunk search or vector state behind.
- Node-level embeddings are a separate surface from chunk embeddings. The contract for what feeds the node-level embedding must be explicit, and updates to those fields must trigger a fresh node-level embedding run.
- Integrity and degraded-mode checks must cover both search surfaces and embedding-related write surfaces, not just top-level node reads.
## Edge Contract
- `edges.explanation` is now a top-level field and should be treated as the human-readable reason the connection exists.
- `edges.context` still exists as structured JSON for inferred type, confidence, and creation metadata.
- docs should not describe edge context JSON as if it is the only user-facing explanation surface.
## Important Constraints
- `dimensions` and `node_dimensions` are no longer canonical tables.
- New installs should never create them.
- Existing installs migrate by snapshotting old dimension data, then dropping the legacy tables.
- `contexts` are optional. `nodes.context_id` must allow `NULL`.
- FTS repair and integrity handling are now operational concerns. Do not describe automatic live rebuild behavior as normal product behavior.
## Common Queries
Nodes in a context:
```sql
SELECT *
FROM nodes
WHERE context_id = ?
ORDER BY updated_at DESC;
```
Most connected nodes:
```sql
docs/4_tools-and-guides.md
+53 -44
View File
@@ -1,56 +1,65 @@
# Tools & Skills
MCP tools are the graph contract. Skills are the reusable procedural layer that teaches agents how to use that contract well.
What actions agents can take, and how skills provide procedural guidance.
## Live MCP Tools
## Tool Groups
| Group | Purpose | Examples |
|-------|---------|----------|
| Read | Find, inspect, and ground graph context | `queryNodes`, `retrieveQueryContext`, `getNodesById` |
| Write | Create or update graph structure | `createNode`, `updateNode`, `createEdge` |
| Extraction | Ingest external content into the graph | `websiteExtract`, `youtubeExtract`, `paperExtract` |
| Utility | Deep inspection or external support | `sqliteQuery`, `webSearch`, `think` |
| Skills | Procedural guidance | `listSkills`, `readSkill`, `writeSkill`, `deleteSkill` |
## Live Tool Surface
### Read
| Tool | Description |
|------|-------------|
| `getContext` | Graph overview for orientation |
| `queryNodes` | Direct node lookup by title, description, or source |
| `retrieveQueryContext` | Broader current-turn retrieval when graph grounding helps |
| `getNodesById` | Fetch full nodes by ID |
| `queryEdge` | Inspect existing edges |
| `queryContexts` | List/search contexts |
| `searchContentEmbeddings` | Search source chunks/transcripts |
| `sqliteQuery` | Read-only SQL (`SELECT`, `WITH`, `PRAGMA`) |
- `getContext`
- `queryNodes`
- `retrieveQueryContext`
- `getNodesById`
- `queryEdge`
- `searchContentEmbeddings`
- `sqliteQuery`
- `webSearch`
- `think`
### Write
| Tool | Description |
|------|-------------|
| `createNode` | Create a node after duplicate/update checks |
| `updateNode` | Update a node while preserving context by default |
| `writeContext` | Save one confirmed durable context node |
| `createEdge` | Create a confirmed edge |
| `updateEdge` | Correct an edge after explicit confirmation |
- `createNode`
- `updateNode`
- `deleteNode`
- `createEdge`
- `updateEdge`
### Skills
- `listSkills`
- `readSkill`
- `writeSkill`
- `deleteSkill`
| Tool | Description |
|------|-------------|
| `listSkills` | List available skills |
| `readSkill` | Read one skill |
| `writeSkill` | Create or update a skill |
| `deleteSkill` | Delete a skill |
### Extraction
- `websiteExtract`
- `youtubeExtract`
- `paperExtract`
## Behavior Rules
## Important Behavior Rules
- search before creating
- use `queryNodes` first for specific-node intent
- use `retrieveQueryContext` only when broader grounding would help
- leave context blank by default
- if context is intentionally provided, prefer `context_name`
- `writeContext`, `createEdge`, and `updateEdge` are confirmation-gated
- judge graph quality by node quality and explicit edges, not taxonomy completeness
- Search before creating.
- Use `queryNodes` first when the user is clearly looking for a specific existing node.
- Use `retrieveQueryContext` when the current turn would benefit from broader graph grounding.
- `createEdge` and `updateEdge` are confirmation-gated.
- node creation quality should come from `title`, `description`, `source`, `metadata`, and explicit edges, not taxonomy.
## Skills
Metadata note for `createNode` / `updateNode`:
- prefer canonical keys: `type`, `state`, `captured_method`, `captured_by`, `source_metadata`
- `updateNode.metadata` merges into the existing object rather than replacing the whole blob
Skills are markdown instructions stored locally and shared across internal and external agents.
## Skills System
Default seeded skills:
Skills are markdown instruction documents shared by internal and external agents.
Seeded defaults:
- `db-operations`
- `create-skill`
- `audit`
@@ -64,21 +73,21 @@ Storage:
- live skills: `~/Library/Application Support/RA-H/skills/`
- bundled defaults: `src/config/skills/`
## API Routes
## API Surfaces
| Route | Method | Purpose |
|-------|--------|---------|
| `/api/skills` | GET | List skills |
| `/api/skills/[name]` | GET/PUT/DELETE | Skill CRUD |
| `/api/guides` | GET | Compatibility alias to skills |
| `/api/guides/[name]` | GET/PUT/DELETE | Compatibility alias to skills |
| `/api/guides` | GET | Legacy compatibility alias to skills |
| `/api/guides/[name]` | GET/PUT/DELETE | Legacy compatibility alias to skills |
## Key Files
| File | Purpose |
|------|---------|
| `apps/mcp-server-standalone/` | Standalone MCP server |
| `src/tools/infrastructure/registry.ts` | Live tool registry |
| `src/services/skills/skillService.ts` | Skills runtime service |
| `src/services/skills/skillService.ts` | App skill service |
| `apps/mcp-server-standalone/services/skillService.js` | Standalone MCP skill service |
| `src/config/skills/*.md` | Bundled default skills |
| `src/components/panes/SkillsPane.tsx` | Skills pane UI |
| `apps/mcp-server-standalone/skills/*.md` | MCP bundled default skills |
docs/6_ui.md
+4 -5
View File
@@ -11,7 +11,6 @@ RA-H OS follows the current pane model:
## Main Views
- `Feed` for recent and sortable node browsing
- `Contexts` for optional context browsing
- `Map` for graph structure
- `Table` for dense inspection
- `Skills` for editable agent instructions
@@ -21,11 +20,11 @@ RA-H OS follows the current pane model:
- The app no longer exposes a dimensions pane.
- Feed and table filtering are not dimension-based.
- Persisted pane layout should only hydrate valid pane types: `views`, `node`, `contexts`, `map`, `table`, `skills`.
- Contexts are shown as a secondary organizational aid, not as a hard requirement for capture.
- Persisted pane layout should only hydrate valid pane types: `views`, `node`, `map`, `table`, `skills`.
- The app does not expose a separate organizing pane or category filter surface.
## Focus And Capture
- Capture must succeed when context is omitted.
- Capture must succeed without any category or context assignment.
- Focus surfaces should emphasize title, description, source, metadata, and edges.
- Node cards may show context when present, but should not depend on it for meaning.
- Node cards and focus views should not depend on category labels for meaning.
docs/8_mcp.md
+39 -150
View File
@@ -1,116 +1,41 @@
# MCP Surface
This is the full practical setup page for the standalone open-source MCP path.
RA-H exposes MCP tools for direct graph work against the local database or app API.
## 1. What MCP Gives You In RA-H OS
Important runtime distinction:
MCP lets an external agent:
- search your existing graph
- ground a broader task in relevant graph context
- create or update nodes
- propose and confirm edges
- read and write shared skills
The graph contract is:
- no runtime `dimensions`
- optional `contexts`
- direct lookup first
- broader retrieval only when useful
- confirmation-gated durable writeback and edge changes
## 2. Choose Your Assistant / Client
Best-supported path:
- Claude Code
- Claude Desktop
Also reasonable:
- Cursor and similar MCP-capable coding assistants
Prefer a client that:
- supports local stdio MCP servers well
- reliably restarts after config changes
- lets you pin one package version in config
## 3. Install The Standalone MCP Server
Requirements:
- Node.js 18-22 LTS recommended
- existing RA-H DB created by running the app once
- pinned package version in client config
Package:
```bash
npx --yes ra-h-mcp-server@2.1.2
```
If `better-sqlite3` fails to load:
- use Node 18-22 LTS
- rebuild native modules if you are developing locally
## 4. Configure The Assistant With A Pinned Version
Claude config example:
```json
{
"mcpServers": {
"ra-h": {
"command": "npx",
"args": ["--yes", "ra-h-mcp-server@2.1.2"]
}
}
}
```
Contributor local-path example:
```json
{
"mcpServers": {
"ra-h": {
"command": "node",
"args": ["/absolute/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
}
}
}
```
## 5. Restart And Verify The Tools Are Available
After editing config:
- fully restart the client
- do not trust a soft window close
- ask the assistant whether RA-H tools are available
Healthy verification usually means you can see tools like:
- `queryNodes`
- `retrieveQueryContext`
- `createNode`
- `readSkill`
- the app MCP surface talks to the running app/API
- the standalone MCP surface talks directly to an existing SQLite DB file
- standalone MCP can read and write nodes/edges without the app running, but it does not own chunking or embedding
- if standalone MCP writes `nodes.source` while the app is closed, the app later processes that node through startup recovery
## Core MCP Contract
- `queryNodes` is the primary tool for direct node retrieval when the user is trying to find a specific existing node.
- `retrieveQueryContext` is the primary retrieval entrypoint for substantive current-turn work when the agent needs graph context to support a broader answer.
- `getContext` returns graph orientation: stats, contexts, hubs, and skills.
- `createNode`, `updateNode`, and `queryNodes` leave context blank by default.
- If context is intentionally provided, prefer `context_name`.
- `context_id` is an internal implementation detail, not the normal agent-facing field.
- `writeContext` writes one confirmed durable context node and must never be called before explicit user approval.
- `createEdge` is a post-confirmation execution tool.
- `updateEdge` is also post-confirmation only.
- `queryNodes` searches title, description, and source, with optional context filters.
- `getContext` returns graph orientation: stats, hubs, and skills.
- `createEdge` is a post-confirmation execution tool. Agents should propose likely edges first and only write them after the user explicitly confirms.
- `queryNodes` searches title, description, and source.
- `dimensions` are removed from the MCP contract.
## Behavior Split
Internal app MCP surfaces:
- talk to the running app/API
- can participate in the live app runtime and UI refresh model
Standalone MCP:
- talks directly to an existing SQLite DB
- can read and write nodes, edges, and skills without the app running
- does not own chunking, vector generation, or schema migration on a live existing DB
- relies on the app to process pending `nodes.source` work later
## Main Tools
Read:
- `retrieveQueryContext`
- `getContext`
- `queryNodes`
- `queryContexts`
- `getNodesById`
- `queryEdge`
- `listSkills`
@@ -119,7 +44,6 @@ Read:
- `sqliteQuery`
Write:
- `writeContext`
- `createNode`
- `updateNode`
- `createEdge`
@@ -127,61 +51,26 @@ Write:
- `writeSkill`
- `deleteSkill`
## 6. How The Agent Should Behave With RA-H
## Tool Behavior
- always search before creating
- use `queryNodes` first for specific-node intent
- use `retrieveQueryContext` when broader graph grounding would help
- keep context optional by default
- use `context_name` only when context is intentionally provided
- do not assume the server will infer a best-fit context
- if the user explicitly asked to save or update something and the target artifact is clear, the agent can write after duplicate/update checks
- if the agent is only suggesting a save, it should propose the node first and wait for confirmation
- when obvious relationships appear, propose candidate edges briefly rather than writing them automatically
- keep writeback prompts terse and selective
- Always search before creating.
- If the user is trying to find a specific existing node, use `queryNodes` first.
- If the user is asking a broader question that would benefit from graph context, use `retrieveQueryContext`.
- Optional user memory reinforcement can help, but the MCP tools, instructions, skills, and docs should be enough for the core retrieval and writeback contract to work.
- If the user explicitly asked to save or update something and the target artifact is clear, the agent can write after duplicate/update checks.
- If the agent is only suggesting a save, it should propose the node first and wait for confirmation.
- When obvious relationships appear, propose candidate edges briefly rather than writing them automatically.
- Judge graph quality by node quality and edges, not taxonomy completeness.
- Keep writeback prompts terse and selective. The goal is not to ask constantly whether every useful sentence should be saved.
- Do not assume MCP node creation immediately produces chunks or embeddings. The canonical contract is:
- write node data first
- app-owned pipeline later creates chunks, FTS rows, and vectors
Do not assume MCP node creation immediately produces chunks or embeddings. The canonical contract is:
- write node data first
- app-owned pipeline later creates chunks, FTS rows, and vectors
## Memory-File Rule
## 7. Optional Memory-File Reinforcement
Optional assistant memory files can reinforce good behavior, but they are not supposed to be the hidden dependency that makes RA-H work.
Important distinction:
- `CLAUDE.md` is an assistant-native memory/instruction file for Claude Code
- `AGENTS.md` is a repo-local instruction file many teams already use
- other clients may have their own memory or instruction surfaces
Rules:
- the MCP/tool/docs contract should work without user prompt surgery
Current rule:
- MCP tools, server instructions, skills, and docs should be enough for the base contract
- optional reinforcement can still improve consistency
- do not create contradictory instruction files
Short recommended reinforcement pattern:
```md
Retrieve relevant RA-H context before substantive work, search before creating, and keep durable writeback prompts brief and confirmation-gated.
```
## 8. Troubleshooting And Common Failure Cases
`Tools not found`
- fully restart the client
- verify the config path is the one your client actually uses
- run the pinned package manually once
`Database not found`
- run the RA-H app once first so the DB exists
- confirm `RAH_DB_PATH` if using a custom path
`Node writes land but embeddings/chunks are missing`
- this is usually expected when the app is closed
- standalone MCP writes node data first
- the app later processes pending `nodes.source` work
`Native module load failure`
- use Node 18-22 LTS
- rebuild `better-sqlite3` if needed for local development
`Version drift`
- pin the package version in client config
- bump the pinned version intentionally when testing a new release
- avoid contradictory instruction files across `CLAUDE.md`, `AGENTS.md`, and other client-specific memory surfaces
docs/9_open-source.md
+17 -34
View File
@@ -1,47 +1,22 @@
# Open Source Surface
The open-source RA-H surface should match the main app contract where product behavior is shared:
`ra-h_os` should match the main app contract wherever the underlying product behavior is shared.
That means the open-source docs should reflect:
- no runtime `dimensions` model,
- optional soft `contexts`,
- no automatic context assignment on write,
- node quality driven by title, description, source, metadata, and edges.
## What RA-H OS Includes
- local SQLite graph
- local UI
- standalone MCP server
- shared skills system
- BYO API key path
## What RA-H OS Does Not Promise
- every private-app surface
- private subscription/auth behavior
- official support for every local model stack or vector backend someone can wire up
- a guarantee that every community setup is first-class supported
## Support Boundary
Supported core path:
- RA-H OS app
- local SQLite
- standard standalone MCP server
- documented repo install flow
Reasonable community pattern:
- local model or alternate MCP-capable chat surface layered on top of the documented contract
Experimental / user-owned:
- custom vector backends
- unsupported deployment targets
- aggressive local-model substitutions that degrade tool quality
It should also explain the open-source-specific reality clearly:
- no private-app-only promises
- a practical standalone MCP install path
- pinned package versions for external-agent setup
- clear verification and troubleshooting steps
- honest support boundaries for fully local or community setups
## Important App Routes
- `app/api/nodes/`
- `app/api/contexts/`
- `app/api/edges/`
- `app/api/rah/chat/`
- extraction routes
@@ -52,3 +27,11 @@ Experimental / user-owned:
Main `ra-h` ships first.
`ra-h_os` is a required follow-up port of the same contract, not a place to preserve older taxonomy behavior.
## Required Docs Surfaces In `ra-h_os`
- `README.md` for terse install + MCP quickstart
- `docs/README.md` for the start-here path
- `docs/8_mcp.md` for the full MCP setup, verification, memory-file guidance, and troubleshooting path
- `docs/10_full-local.md` for clearly caveated local/community patterns
- `apps/mcp-server-standalone/README.md` for package-level install details that match the repo docs