RA-H OS provides a local, privacy-first knowledge management system designed for users who want to store notes, bookmarks, and research securely on their own machines. It offers a web-based UI for browsing and organizing information and exposes an MCP (Meta Communication Protocol) server, enabling AI coding agents like Claude Code, Cursor, and Codex to interact with and augment this local knowledge graph. The primary benefit is maintaining full control over personal data while integrating AI capabilities.

How It Works

The system stores all knowledge in a local SQLite database. It features a browser-based UI accessible at localhost:3000 for direct user interaction. An MCP server component allows AI agents to query, create, and update nodes within the graph. Node quality is determined by explicit fields like title, description, source, metadata, and defined edges. The architecture prioritizes direct node lookup for specific intents and uses getContext for orientation and retrieveQueryContext for grounding AI responses within the user's knowledge base. The application manages the chunking of source material and the generation of embeddings, ensuring data remains local unless explicitly configured otherwise.

Quick Start & Requirements

• Primary Install:
  • MCP-only quick install (for AI agents): npx -y ra-h-mcp-server@latest setup --client <client_name> --yes
  • Full local app (UI + MCP): git clone https://github.com/bradwmorris/ra-h_os.git, cd ra-h_os, npm install, npm run setup:local, npm run dev.
• Prerequisites: Node.js 20.18.1+. macOS works out-of-the-box. Windows and Linux require manual setup for semantic/vector search using sqlite-vec or Qdrant. An OpenAI API key is optional but recommended for features like auto-generated descriptions and semantic search.
• Links: Node.js: nodejs.org, Docs: docs/README.md, OpenAI API Keys: platform.openai.com/api-keys.

Highlighted Details

• Data Privacy: All user data is stored locally on the machine; no data is transmitted externally without explicit API key configuration.
• AI Agent Integration: Seamlessly connects with AI coding agents via the MCP server, allowing them to leverage and contribute to the local knowledge graph.
• Direct Database Access: The underlying SQLite database file (rah.sqlite) can be directly accessed and queried using standard SQL tools for backup or custom analysis.
• Node-Centric Knowledge: Organizes information into discrete nodes with defined relationships, emphasizing quality derived from explicit metadata and connections.

Maintenance & Community

• Community: Discord server available at discord.gg/3cpQj6Jtc9.
• Issues: Tracked via GitHub Issues at github.com/bradwmorris/ra-h_os/issues.
• Documentation: Located within the docs/ directory, starting with docs/README.md.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The MIT license is permissive, generally allowing for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

Core application functionality on Windows and Linux is still undergoing validation, with semantic and vector search capabilities dependent on manual installation of sqlite-vec or alternative solutions like Qdrant for specific environments (e.g., Alpine/musl Linux). Without these vector search components, the application will still function for node management and keyword search but will report vector search as unavailable.