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

feat: finalize local OpenAI key flow and MCP docs

Browse Source 
- add server-side .env.local OpenAI key management for the open-source app
- route AI features through the preferred local key path and lazy-load embed recovery
- rewrite README and docs for current MCP setup, schema, and fully-local guidance

Generated with Claude Code
This commit is contained in:
“BeeRad”
2026-04-16 14:08:37 +10:00
parent c2f880d957
commit 97eeb0789f
28 changed files with 891 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0_overview.md
+13 -19
View File
@@ -1,8 +1,8 @@
# RA-OS Overview
# RA-H OS Overview
## What is RA-OS?
RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a local-first knowledge management system designed to be extended by external AI agents via the Model Context Protocol.
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.
**Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
@@ -10,9 +10,9 @@ RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a
**Local-first** — Your knowledge network belongs to you. Everything runs locally in a SQLite database you control.
**Agent-agnostic** — No built-in AI chat. Instead, RA-OS exposes an MCP server that any AI agent (Claude Code, custom agents) can connect to.
**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.
**Simple & focused** — A compact multi-pane UI for browsing and editing your knowledge graph. No bloat.
**Simple & focused** — The open-source surface keeps the graph, UI, and MCP contract. It does not try to mirror every private-app surface.
## Tech Stack
@@ -23,7 +23,7 @@ RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a
## What's Included
- Multi-pane UI for nodes, contexts, map, table, and focus work
- 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
@@ -34,25 +34,18 @@ RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a
## What's NOT Included
- Chat interface (use external agents via MCP)
- Private-app-only built-in assistant experience
- Voice features
- Built-in AI agents
- Auth/subscription system
- Desktop packaging
## Two-Panel Layout
## Current Doctrine
```
┌─────────────┬─────────────────────────┐
│ NODES │ FOCUS │
│ Panel │ Panel │
│ │ │
│ • Search │ • Node content │
│ • Filters │ • Connections │
│ • List │ • Context + metadata │
│ │ │
└─────────────┴─────────────────────────┘
```
- 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`
## MCP Integration
@@ -81,4 +74,5 @@ Core tools include: `queryNodes`, `retrieveQueryContext`, `createNode`, `writeCo
| [Tools & Skills](./4_tools-and-guides.md) | Available MCP tools, skill system |
| [UI](./6_ui.md) | Component structure, panels, views |
| [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 |
docs/10_full-local.md
+102
View File
@@ -0,0 +1,102 @@
# Fully Local / Community Patterns
This page is for users who want to stay as local as possible without pretending every local-first stack is equally supported.
## 1. What "Fully Local" Means In RA-H Terms
In RA-H terms, "fully local" usually means:
- your graph lives in local SQLite
- the UI runs locally
- your MCP server runs locally
- you avoid shipping graph data to hosted backends where possible
That does not automatically mean every part of the stack is equally local. Model choice, embeddings, and alternate vector backends change that.
## 2. The Supported Baseline Local Stack
Supported core path:
- RA-H OS app
- local SQLite DB
- standard standalone MCP server
- documented repo install flow
- hosted model APIs if you choose them
This is the path the core docs and troubleshooting are written for.
## 3. Where Local-First Starts Getting Experimental
Local-first gets more experimental when you change:
- model provider
- embedding provider
- vector backend
- deployment target
- chat/agent client beyond the documented MCP path
That does not make those setups bad. It just changes the support boundary.
## 4. Community Pattern: Local Models + RA-H MCP
Reasonable community pattern:
- keep RA-H OS local
- keep SQLite local
- connect a local-model-capable client to RA-H through MCP
Honest caveat:
- tool-calling quality depends heavily on the model/runtime
- smaller local models may perform materially worse than stronger hosted tool-use models
- "fully local" can reduce privacy concerns and improve offline control, but it can also degrade reliability
## 5. Community Pattern: AnythingLLM As Alternate Local Chat / Agent Surface
Based on current public docs:
- AnythingLLM has MCP compatibility
- AnythingLLM supports local-model paths
- Intelligent Tool Selection exists and may matter for local-model performance
This makes it a plausible alternate local chat/agent surface for RA-H MCP.
Caveat:
- MCP support alone does not guarantee strong tool use
- weaker local models can still underperform badly even with a solid MCP integration
References:
- https://docs.anythingllm.com/mcp-compatibility/overview
- https://docs.anythingllm.com/agent/intelligent-tool-selection
## 6. Community Pattern: Qdrant Add-On For Vector-Heavy Or `sqlite-vec`-Hostile Environments
Qdrant is a plausible local or self-hosted vector backend when:
- `sqlite-vec` is weak on the target platform
- storage/runtime constraints make the default vector path awkward
- you are intentionally running a more custom environment
Important boundary:
- this is not a bundled official RA-H core dependency
- the Nathan Maine repo is a community add-on example, not the default install story
References:
- https://qdrant.tech/documentation/quickstart/
- https://github.com/NathanMaine/rah-qdrant-integration
## 7. Honest Tradeoffs
- more local privacy can be better
- offline control can be better
- maintenance burden is usually higher
- tool quality can get worse fast with weaker local models
- troubleshooting becomes more user-owned as you move away from the baseline path
## 8. Support Boundary
Supported core path:
- repo install flow
- SQLite
- documented standalone MCP setup
Reasonable community pattern:
- alternate local-model or alternate local chat surface that still respects the MCP contract
Experimental / user-owned:
- custom vector backend swaps
- unsupported runtime targets
- heavily modified inference stacks
docs/2_schema.md
+15 -1
View File
@@ -49,7 +49,21 @@
- `nodes_fts` indexes title, description, and source for full-text lookup.
- `chunks_fts` indexes chunk text.
- Vector tables store node and chunk embeddings.
- `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
## 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
## Important Constraints
docs/4_tools-and-guides.md
+38 -36
View File
@@ -1,50 +1,56 @@
# Tools & Skills
> MCP tools for graph operations and skills for procedural guidance.
MCP tools are the graph contract. Skills are the reusable procedural layer that teaches agents how to use that contract well.
**How it works:** External agents call MCP tools to read and write your graph. Contexts are optional soft organization only; node quality should come from clear nodes and explicit edges.
## Live MCP Tools
---
## MCP Tools
RA-OS exposes these core standalone MCP tools:
### Context + Graph
### Read
| Tool | Description |
|------|-------------|
| `getContext` | Graph overview: stats, contexts, hub nodes, recent activity, skills |
| `retrieveQueryContext` | Pull relevant graph context for a broader current-turn task |
| `queryNodes` | Find specific existing nodes by title, description, or source |
| `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 |
| `createNode` | Create a node |
| `writeContext` | Save one confirmed durable context node after explicit user approval |
| `updateNode` | Update a node while preserving context by default |
| `createEdge` | Create a confirmed edge between nodes |
| `queryEdge` | Query edges |
| `updateEdge` | Update an edge explanation after explicit confirmation |
| `queryContexts` | List contexts and optional attached nodes |
| `queryEdge` | Inspect existing edges |
| `queryContexts` | List/search contexts |
| `searchContentEmbeddings` | Search source chunks/transcripts |
| `sqliteQuery` | Read-only SQL (`SELECT`, `WITH`, `PRAGMA`) |
### Skills + Search
### 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 |
### Skills
| Tool | Description |
|------|-------------|
| `listSkills` | List available skills |
| `readSkill` | Read one skill |
| `writeSkill` | Create/update a skill |
| `writeSkill` | Create or update a skill |
| `deleteSkill` | Delete a skill |
| `searchContentEmbeddings` | Search source chunks/transcripts |
| `sqliteQuery` | Read-only SQL (`SELECT`, `WITH`, `PRAGMA`) |
---
## 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
## Skills
Skills are markdown instructions stored locally and shared across internal + external agents.
### Default seeded skills
Skills are markdown instructions stored locally and shared across internal and external agents.
Default seeded skills:
- `db-operations`
- `create-skill`
- `audit`
@@ -54,12 +60,9 @@ Skills are markdown instructions stored locally and shared across internal + ext
- `calibration`
- `connect`
### Storage
- Live skills: `~/Library/Application Support/RA-H/skills/`
- Bundled defaults: `src/config/skills/`
---
Storage:
- live skills: `~/Library/Application Support/RA-H/skills/`
- bundled defaults: `src/config/skills/`
## API Routes
@@ -70,13 +73,12 @@ Skills are markdown instructions stored locally and shared across internal + ext
| `/api/guides` | GET | Compatibility alias to skills |
| `/api/guides/[name]` | GET/PUT/DELETE | Compatibility alias to skills |
---
## Key Files
| File | Purpose |
|------|---------|
| `apps/mcp-server-standalone/` | Standalone MCP server (recommended) |
| `apps/mcp-server-standalone/` | Standalone MCP server |
| `src/tools/infrastructure/registry.ts` | Live tool registry |
| `src/services/skills/skillService.ts` | Skills runtime service |
| `src/config/skills/*.md` | Bundled default skills |
| `src/components/panes/SkillsPane.tsx` | Skills pane UI |
docs/5_logging-and-evals.md
+5 -3
View File
@@ -108,9 +108,11 @@ LIMIT 100
- Stored in `chats.metadata.cost` (USD)
- Aggregated in Settings → Analytics
**Model pricing (as of v1.0):**
- GPT-5 Mini: $0.10/1M input, $0.40/1M output
- GPT-5: $2.50/1M input, $10.00/1M output
**Model pricing (current defaults):**
- GPT-5.4 Mini: $0.75/1M input, $0.075/1M cached input, $4.50/1M output
- GPT-5.4: $2.50/1M input, $0.25/1M cached input, $15.00/1M output
- GPT-5 Mini: $0.25/1M input, $0.025/1M cached input, $2.00/1M output
- GPT-5: $1.25/1M input, $0.125/1M cached input, $10.00/1M output
- GPT-4o Mini: $0.15/1M input, $0.60/1M output
- Claude Sonnet 4.5: $3.00/1M input, $15.00/1M output
docs/6_ui.md
+10 -2
View File
@@ -1,5 +1,13 @@
# UI Surfaces
## Workspace Model
RA-H OS follows the current pane model:
- explicit `1 / 2 / 3` visible panes
- chat anchored to the right edge of the active workspace
- node tabs only in node panes
- singleton non-node panes
## Main Views
- `Feed` for recent and sortable node browsing
@@ -12,12 +20,12 @@
## UI Contract After The Migration
- The app no longer exposes a dimensions pane.
- Feed and table filtering are context-aware and no longer dimension-based.
- 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.
## Focus And Capture
- Capture must succeed when both context and dimensions are omitted.
- Capture must succeed when context is omitted.
- 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.
docs/8_mcp.md
+148 -17
View File
@@ -1,6 +1,94 @@
# MCP Surface
RA-H exposes MCP tools for direct graph work against the local database or app API.
This is the full practical setup page for the standalone open-source MCP path.
## 1. What MCP Gives You In RA-H OS
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`
## Core MCP Contract
@@ -11,8 +99,8 @@ RA-H exposes MCP tools for direct graph work against the local database or app A
- 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. Agents should propose likely edges first and only write them after the user explicitly confirms.
- `updateEdge` is also a post-confirmation execution tool. Agents should only correct an edge after the user explicitly confirms the corrected relationship.
- `createEdge` is a post-confirmation execution tool.
- `updateEdge` is also post-confirmation only.
- `queryNodes` searches title, description, and source, with optional context filters.
- `dimensions` are removed from the MCP contract.
@@ -39,18 +127,61 @@ Write:
- `writeSkill`
- `deleteSkill`
## Tool Behavior
## 6. How The Agent Should Behave With RA-H
- 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.
- Prefer explicit context assignment only when the user clearly wants it and a real context is already known.
- Use `context_name` when context is intentionally provided.
- Do not assume the agent needs to think about context during normal node creation, lookup, or update flows.
- 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.
- 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.
- 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
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
## 7. Optional Memory-File Reinforcement
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
- 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
docs/9_open-source.md
+32 -1
View File
@@ -1,12 +1,43 @@
# Open Source Surface
The open-source RA-H surface should match the main app contract:
The open-source RA-H surface should match the main app contract where product behavior is shared:
- 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
## Important App Routes
- `app/api/nodes/`
docs/README.md
+20 -17
View File
@@ -1,4 +1,4 @@
# RA-OS Documentation
# RA-H OS Documentation
```
██████╗ █████╗ ██╗ ██╗
@@ -13,28 +13,31 @@
| Doc | Description |
|-----|-------------|
| [Overview](./0_overview.md) | What is RA-OS, design philosophy |
| [Schema](./2_schema.md) | Database schema, node/edge structure |
| [Tools & Skills](./4_tools-and-guides.md) | MCP tools, skill system |
| [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
| [UI](./6_ui.md) | 2-panel layout, components, views |
| [MCP](./8_mcp.md) | Connect Claude Code and external agents |
| [About](./9_open-source.md) | What's included, contributing |
| [Overview](./0_overview.md) | What RA-H OS is and what contract it shares with the main app |
| [Schema](./2_schema.md) | Current SQLite contract |
| [Tools & Skills](./4_tools-and-guides.md) | MCP tools and skill system |
| [Logging & Evals](./5_logging-and-evals.md) | Logs, evals, and debugging surfaces |
| [UI](./6_ui.md) | Current pane and focus model |
| [MCP](./8_mcp.md) | Full standalone MCP install and behavior guide |
| [Open Source](./9_open-source.md) | Scope, support boundary, contributor reality |
| [Full Local](./10_full-local.md) | Supported local path vs community patterns |
| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
| [Development](./development/process.md) | Dev workflow and PR checklist |
| [Docs Process](./development/docs-process.md) | How to maintain docs |
## Getting Started
## Start Here
If you just want RA-H OS working:
1. Read [../README.md](../README.md)
2. Follow [MCP](./8_mcp.md) if you want external-agent access
3. Read [Full Local](./10_full-local.md) if you want a more local-first or community setup
## Local App Quick Start
```bash
# Clone
git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
# Install
npm install
# Run
npm rebuild better-sqlite3
npm run bootstrap:local
npm run dev
```
@@ -57,7 +60,7 @@ Add to your `~/.claude.json`:
If you publish a newer MCP release and need clients to use it immediately, bump the pinned version here and restart the client. Do not assume plain `npx ra-h-mcp-server` always refreshes instantly.
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. See [MCP docs](./8_mcp.md) for alternatives.
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. See [MCP docs](./8_mcp.md) for the full install, verify, memory-file, and troubleshooting path.
## Questions?