@gettymade/roux 0.1.2 → 0.2.0

package/README.md

@@ -3,24 +3,22 @@ title: Readme
 ---
 # Roux
 
-A **Graph Programming Interface (GPI)** for building and maintaining knowledge graphs. Semantic search, graph traversal, and AI co-authoring through a unified interface—regardless of storage backend.
+A **Graph Programming Interface (GPI)** for markdown knowledge bases. Semantic search, graph traversal, and AI-assisted editing through MCP.
 
 ## What It Does
 
-- **Semantic search** — Find nodes by meaning, not just keywords
-- **Graph traversal** — Follow links, find paths, identify central nodes
-- **CRUD operations** — Create, read, update, delete nodes programmatically
-- **AI co-authoring** — Let AI assistants read and write knowledge alongside humans
+- **Semantic search** — Find notes by meaning, not just keywords
+- **Graph traversal** — Follow wiki-links, find paths, identify hub notes
+- **CRUD operations** — Create, read, update, delete notes programmatically
+- **MCP integration** — Works with Claude Code and other MCP clients
 
-The graph is always the target structure. Data that isn't natively a graph gets transformed during ingestion. The query model stays constant regardless of source or storage.
+Point it at a markdown directory. Query it like a graph database. Edit in Obsidian.
 
 ## Architecture
 
-Roux is a platform of pluggable modules. GraphCore is the coordination hub—it defines provider interfaces but has zero functionality without them.
-
 ```
 ┌─────────────────────────────┐
-│     External Interfaces     │  MCP Server, REST API, CLI
+│        MCP Server           │  Claude Code, other clients
 └──────────────┬──────────────┘
                │
 ┌──────────────▼──────────────┐
@@ -28,26 +26,17 @@ Roux is a platform of pluggable modules. GraphCore is the coordination hub—it
 └──────────────┬──────────────┘
                │
 ┌──────────────▼──────────────┐
-│          Providers          │  Store, Embedding, LLM, ...
+│          Providers          │
+│  DocStore + Transformers.js │
 └─────────────────────────────┘
 ```
 
-**Store backends** span zero infrastructure to enterprise scale:
-- File-based: DocStore (markdown directories)
-- Embedded: SQLite, LevelGraph
-- Standalone: SurrealDB, FalkorDB, Memgraph
-- Enterprise: Neo4j, ArangoDB, Amazon Neptune
-
-**Embedding providers** for semantic search:
-- Local: transformers.js (default, zero config)
-- Self-hosted: Ollama
-- Cloud: OpenAI
-
-Same queries, same results—regardless of what's plugged in.
+**Current implementation:**
+- **DocStore** — Reads markdown directories, parses frontmatter and wiki-links
+- **Transformers.js** — Local embeddings, no external API required
+- **SQLite cache** — Fast queries without re-parsing files
 
-## Current State (v0.1.x)
-
-Roux ships today with **DocStore**: point it at a markdown directory, query via MCP, edit in Obsidian.
+## Quick Start
 
 ```bash
 # Install
@@ -56,15 +45,14 @@ npm install -g @gettymade/roux
 # Initialize on your markdown directory
 cd ~/my-notes
 roux init
-
-# Start the MCP server
-roux serve
 ```
 
-Then ask your AI things like:
-- "Search my notes for distributed systems concepts"
-- "What links to my note on consensus algorithms?"
-- "Create a new note summarizing what I learned today"
+`roux init` creates config files that Claude Code detects automatically. The MCP server starts when you open the project.
+
+Then ask Claude things like:
+- "Search my notes for distributed systems"
+- "What links to my consensus algorithms note?"
+- "Create a new note about today's meeting"
 
 ### Requirements
 - Node.js 20+
@@ -74,7 +62,7 @@ Then ask your AI things like:
 
 ```bash
 roux init [directory]     # Initialize (creates roux.yaml, .roux/, .mcp.json)
-roux serve [directory]    # Start MCP server with file watching
+roux serve [directory]    # Start MCP server manually (for debugging or non-Claude clients)
 roux serve --no-watch     # Start without watching for changes
 roux status [directory]   # Show node/edge/embedding counts
 roux viz [directory]      # Generate interactive graph visualization
@@ -111,26 +99,27 @@ providers:
 
 Embeddings use local transformers.js by default. No external services required.
 
-### MCP Client Integration
+### Non-Claude MCP Clients
 
-`roux init` creates `.mcp.json` in your project directory. MCP clients detect and offer to enable the server automatically.
+`roux init` creates `.mcp.json` which Claude Code reads automatically. Other MCP clients may need manual configuration:
 
-## Roadmap
+```bash
+# Option 1: Run the server manually
+roux serve
+
+# Option 2: Configure your client to spawn it (check your client's docs)
+```
 
-**Near term:**
-- LLMProvider — Text generation for assisted features
-- Structural embeddings — Graph-aware vectors
+## Future
 
-**Medium term:**
-- Neo4jStore — Graph database backend for scale
-- IngestionProvider — Entity extraction, edge inference
-- REST/GraphQL API
+The architecture supports pluggable backends. Currently only DocStore exists—these are planned:
 
-**Future:**
-- Multi-store federation
-- Multi-tenancy and access control
+- **Additional stores** — Neo4j, SQLite-native, SurrealDB
+- **Cloud embeddings** — OpenAI, Ollama for higher-quality vectors
+- **LLM provider** — Text generation for assisted writing
+- **REST API** — For non-MCP integrations
 
-See [implementation-plan.md](docs/implementation-plan.md) for details.
+See `docs/roadmap/` for details.
 
 ## How It Works
 
@@ -140,7 +129,7 @@ See [implementation-plan.md](docs/implementation-plan.md) for details.
 4. **Graph** — Builds in-memory graph from link relationships
 5. **Serving** — Exposes operations via MCP protocol
 
-File changes sync automatically when running `roux serve`.
+File changes sync automatically when the MCP server is running.
 
 ## Documentation