Memory
# IntelligentRAG — Complete Architecture Plan ## Overview An MCP server for other agents to use as an intelligent document store and search capability. The agent acts as a "librarian" — curating, organizing, and retrieving knowledge from a graph database. Not a user-facing app — purely an MCP server consumed by other agents (Claude, Cursor, custom CF agents). ## Stack | Component | Deployment | Purpose | |---|---|---| | IntelligentRAG Agent | McpAgent (Durable Object) | Orchestrator, MCP server | | SurrealDB | Cloudflare Container | Graph + vector + document store | | xberg-wasm | In Worker (WASM) | Document extraction (97 formats) | | crawlberg-wasm | In Worker (WASM) | Web crawling + HTML→Markdown | | Browser Run | Cloudflare service (CDP) | JS-heavy page rendering fallback | | Workers AI | Cloudflare binding | Embeddings + chat/generation | | Qwen3-Embedding | @cf/qwen/qwen3-embedding-0.6b | 1024-dim embeddings | | Qwen3-30B-A3B | @cf/qwen/qwen3-30b-a3b-fp8 (default) | Chat, generation, entity extraction | ## Key Design Decisions ### 1. MCP Server Primary Interface - McpAgent base class (not AIChatAgent) - No web UI — pure MCP server - Per-user isolation via URL: /mcp/{user-id} - No auth for dev mode ### 2. Spectron-Inspired Memory Model - Supersede, never delete (valid_from/valid_until on every fact) - Provenance as data on every entity, attribute, relation - Three clocks: system_time, known_time, valid_time - Content-addressed documents (hash-based dedup) - Same reconciler for all write paths - Traces are memory (first-class graph nodes) - Uncertainty is explicit (emit uncertainty rows when confidence low) ### 3. Six Memory Categories - Episodic (raw conversation turns) - Identity (durable facts about user) - Knowledge (things learned from documents) - Context (current working set) - Instructions (behavioral rules) - Uncertainty (explicit gaps) ### 4. Graph-Stored Schema + Procedures - Schema is data in the graph (self-describing system) - Procedures are graph nodes with edges for branching - System prompt is lean (compact schema map + principles) - Agent queries graph for full schema and procedure details - 3 core procedures: ingest, retrieve, reconcile ### 5. Collections as Isolated Workspaces - User-managed + agent-managed (hybrid) - Each collection is an isolated retrieval scope - NotebookLM-style generation (summary, outline, FAQ, comparisons) - Auto-generation on ingest + on-demand generation - Flat collections (no nesting for now) ### 6. Fully Autonomous Librarian Agent - Agent decides how to organize, link, and curate - Proactively reviews graph for new connections after ingestion - Continuously evolving graph (re-links, merges entities) - Weighted edges (0-1 confidence scores) ### 7. Tiered Hybrid Retrieval - Tier 1: Direct lookup (entity by key, sub-ms) - Tier 2: Response reuse (cached, invalidation on supersede) - Tier 3: Hybrid (vector + BM25 + graph + keywords) - Tier 4: Full-context fallback (broader sweep) - Five coherence dimensions: semantic, lexical, relational, temporal, keyword ### 8. Configurable Chat Model - Default: @cf/qwen/qwen3-30b-a3b-fp8 - Per-request override via model param - Model recommendations by task (entity extraction, summary, code analysis) - Config stored in agent DO SQLite ### 9. Crawling with Progressive Enhancement - crawlberg-wasm first (fast HTTP fetch) - Browser Run CDP fallback for JS-heavy SPAs - Auto-detection of when browser is needed ## Graph Schema (Core Tables) ### Nodes - document (title, source_type, source_url, content_hash, mime_type, metadata, trust, created_at) - chunk (document, content, embedding[1024], byte_start, byte_end, position, keywords) - entity (name, type, description, embedding[1024], attributes) - topic (name, description, embedding[1024]) - category (name) - keyword (term, frequency) - collection (name, description, settings) - trace (kind, query, tier, candidates, results, reasoning) - uncertainty (question, context, confidence, source) - procedure (name, step_id, step_number, description, action, tool, params, conditions, is_entry, is_terminal) - schema_version (active schema metadata) ### Edges - contains (document → chunk, position) - mentions (chunk → entity, confidence, byte_span) - about (document → topic, confidence) - part_of (topic → category) - related_entity (entity ↔ entity, kind, weight, valid_from, valid_until, source, supersedes) - related_doc (document ↔ document, kind, weight) - has_keyword (chunk ↔ keyword, pmi_score) - entity_keyword (entity ↔ keyword, pmi_score) - in_collection (document ↔ collection, added_at, added_by) - collection_topic (collection ↔ topic) - next_step (procedure → procedure, condition, label) - supersedes (entity → entity, reason, confidence) - traced_from (chunk/entity/document → trace) - traced_to (trace → chunk/entity/document) ### Vector Indexes (1024-dim, cosine) - chunk_embedding ON chunk - entity_embedding ON entity - topic_embedding ON topic ### Full-text Index (BM25) - chunk_text ON chunk FIELDS content ## MCP Tools Exposed | Tool | Description | |------|-------------| | ingest_document | Extract file via xberg-wasm, chunk, embed, store | | ingest_url | Crawl via crawlberg + browser fallback, extract, store | | crawl_site | Deep crawl with JS fallback | | browse_page | Explicit browser render for SPAs | | search | Tiered hybrid retrieval | | graph_query | Raw SurrealQL | | create_collection | New isolated workspace | | list_collections | List workspaces | | generate | NotebookLM-style output (summary, outline, FAQ) | | reflect | On-demand synthesis | | elaborate | Find implicit connections | | get_schema | Introspect graph schema | | get_procedure | View procedure graph | | trace | Audit retrieval | | forget | Explicit removal | | set_config | Set model preferences | ## File Structure ``` C:\CoderFiles\IntelligentRAG\ ├── package.json ├── wrangler.jsonc ├── tsconfig.json ├── env.d.ts ├── .gitignore ├── containers/ │ └── surrealdb/ │ └── Dockerfile └── src/ ├── server.ts ├── types.ts ├── tools/ │ ├── ingest.ts │ ├── search.ts │ ├── graph.ts │ ├── collections.ts │ ├── generate.ts │ ├── reflect.ts │ ├── schema.ts │ ├── config.ts │ └── trace.ts ├── engine/ │ ├── procedure-engine.ts │ ├── reconciliation.ts │ ├── retrieval.ts │ ├── embeddings.ts │ ├── xberg-extract.ts │ ├── crawlberg-crawl.ts │ └── browser-fallback.ts └── db/ ├── surrealdb-client.ts ├── graph-schema.ts ├── schema-seed.ts └── procedure-seed.ts ``` ## Implementation Phases ### Phase 1: Scaffold + SurrealDB Container - package.json, wrangler.jsonc, tsconfig, env.d.ts, .gitignore - containers/surrealdb/Dockerfile - src/server.ts (minimal fetch handler) - src/db/surrealdb-client.ts (HTTP client) - Test: Worker deploys, SurrealDB boots, can query ### Phase 2: Graph Schema + Seed Data - src/db/graph-schema.ts (full SurrealQL DDL) - src/db/schema-seed.ts - src/db/procedure-seed.ts (3 core procedures) - Test: Schema created, procedures seeded, vector indexes exist ### Phase 3: Document Extraction (xberg WASM) - src/engine/xberg-extract.ts - src/types.ts - Test: Extract from PDF, DOCX, plain text ### Phase 4: Embeddings + Basic Storage - src/engine/embeddings.ts (Qwen3-Embedding-0.6B, 1024-dim) - Test: Embeddings returned, document + chunks stored in SurrealDB ### Phase 5: Agent + MCP Tools (Core) ← FIRST MILESTONE - src/server.ts (full McpAgent) - src/tools/ingest.ts, search.ts, graph.ts, schema.ts - Test: MCP server responds, ingest_document end-to-end, search works ### Phase 6: Entity Extraction + Graph Building - src/engine/reconciliation.ts - Test: LLM extracts entities, graph edges created, supersession works ### Phase 7: Tiered Retrieval - src/engine/retrieval.ts - Test: Tier 1/3/4 work, graph traversal enriches results ### Phase 8: Collections - src/tools/collections.ts - Test: Create collection, assign docs, scoped search ### Phase 9: Generation (NotebookLM-style) - src/tools/generate.ts - Test: Summary, outline, FAQ with citations ### Phase 10: Web Crawling (crawlberg + browser) - src/engine/crawlberg-crawl.ts - src/engine/browser-fallback.ts - Update src/tools/ingest.ts - Test: Crawl static page, crawl with JS fallback ### Phase 11: Procedure Engine - src/engine/procedure-engine.ts - Test: Follows ingest procedure graph ### Phase 12: Reflect + Elaborate + Traces - src/tools/reflect.ts, trace.ts - Test: Reflect synthesizes, elaborate finds connections ## Dependencies ```json { "@cloudflare/ai-chat": "*", "@cloudflare/containers": "*", "@xberg-io/xberg-wasm": "latest", "@xberg-io/crawlberg-wasm": "latest", "agents": "*", "ai": "^6.0.202", "workers-ai-provider": "^3.3.0", "zod": "^4.4.3" } ``` ## wrangler.jsonc Key Config - compatibility_flags: ["nodejs_compat", "enable_weak_ref"] - SurrealDB container binding - AI binding (remote: true) - Browser binding for Browser Run CDP - Worker Loader binding ## Open Items / Notes - WASM verification gate in Phase 1 (check bundle size + memory) - Per-user isolation: separate SurrealDB containers per user - Graph schema refinement (user has specific structure to discuss) - Edge weights: 0-1 confidence scores on all relations - Agent proactivity: after ingestion, review existing graph for connections
Tags: architecture, plan, agents-sdk, surrealdb, xberg, crawlberg, mcp, spectron, rag, project:intelligentrag, kind:semantic — Source: claude — 2026-07-16 18:10:20 UTC