{"id":40715887,"url":"https://github.com/jagjeevanak/mem-oracle","last_synced_at":"2026-01-27T00:05:57.178Z","repository":{"id":333647875,"uuid":"1138111267","full_name":"JagjeevanAK/mem-oracle","owner":"JagjeevanAK","description":"A locally-running documentation oracle that indexes web docs and injects relevant snippets into Claude Code context.","archived":false,"fork":false,"pushed_at":"2026-01-24T07:26:58.000Z","size":572,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T09:23:40.044Z","etag":null,"topics":["ai","claude-code","coding-agent","cursor","opencode","plugin"],"latest_commit_sha":null,"homepage":"https://mem-oracle.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JagjeevanAK.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T08:59:59.000Z","updated_at":"2026-01-24T07:27:01.000Z","dependencies_parsed_at":"2026-01-20T21:04:55.112Z","dependency_job_id":"17ab2564-c2ba-4271-ac50-6aef3858f91d","html_url":"https://github.com/JagjeevanAK/mem-oracle","commit_stats":null,"previous_names":["jagjeevanak/mem-oracle"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/JagjeevanAK/mem-oracle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JagjeevanAK%2Fmem-oracle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JagjeevanAK%2Fmem-oracle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JagjeevanAK%2Fmem-oracle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JagjeevanAK%2Fmem-oracle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JagjeevanAK","download_url":"https://codeload.github.com/JagjeevanAK/mem-oracle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JagjeevanAK%2Fmem-oracle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28737797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T21:19:41.845Z","status":"ssl_error","status_checked_at":"2026-01-24T21:13:38.675Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","coding-agent","cursor","opencode","plugin"],"created_at":"2026-01-21T13:11:45.466Z","updated_at":"2026-01-24T22:00:47.800Z","avatar_url":"https://github.com/JagjeevanAK.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mem-oracle\n\nA locally-running documentation oracle that indexes web docs and injects relevant snippets into Claude Code context.\n\n## Features\n\n- **Seed-first indexing**: Index the seed page immediately, then continue background crawling\n- **Local storage**: SQLite metadata + disk-based vector store (no external dependencies)\n- **Pluggable embeddings**: Local TF-IDF fallback, or use OpenAI/Voyage/Cohere APIs\n- **Claude Code plugin**: Hook scripts that auto-inject relevant docs into prompts\n- **Optional MCP server**: Explicit tool calls for search/index operations\n\n## Quick Start\n\n### Claude Code Plugin (Recommended)\n\n```bash\n# In Claude Code terminal:\n/plugin add jagjeevanak/mem-oracle\n```\n\nThat's it! The plugin will:\n- Auto-install dependencies\n- Auto-start the worker service in the background\n- Auto-inject relevant documentation into your prompts\n\n### Manual Installation\n\n```bash\n# Clone and install\ngit clone https://github.com/jagjeevanak/mem-oracle.git\ncd mem-oracle\nbun install\n\n# Start the worker service\nbun run worker\n\n# In another terminal, index some docs\nbun run src/index.ts index https://nextjs.org/docs/getting-started\n\n# Search indexed docs\nbun run src/index.ts search \"how to use server components\"\n```\n\n## Usage\n\n### CLI Commands\n\n```bash\n# Start the worker HTTP service (default: http://127.0.0.1:7432)\nbun run src/index.ts worker\n\n# Start the MCP server (stdio)\nbun run src/index.ts mcp\n\n# Index a documentation URL\nbun run src/index.ts index \u003curl\u003e\n\n# Search indexed documentation\nbun run src/index.ts search \u003cquery\u003e\n\n# Show indexing status\nbun run src/index.ts status\n```\n\n### Worker API\n\nThe worker service exposes these HTTP endpoints:\n\n```\nPOST /index     - Index a documentation site\nPOST /retrieve  - Search for relevant snippets\nGET  /status    - Get indexing status\nDELETE /docset/:id - Delete a docset\nGET  /health    - Health check\n```\n\n#### Index Request\n\n```json\n{\n  \"baseUrl\": \"https://nextjs.org\",\n  \"seedSlug\": \"/docs/getting-started\",\n  \"name\": \"Next.js Docs\",\n  \"waitForSeed\": true\n}\n```\n\n#### Retrieve Request\n\n```json\n{\n  \"query\": \"how to use server components\",\n  \"topK\": 5\n}\n```\n\n### MCP Tools\n\nWhen running as an MCP server, these tools are available:\n\n- `search_docs` - Search indexed documentation\n- `get_snippets` - Get specific documentation chunks\n- `index_docs` - Index a documentation website\n- `index_status` - Get indexing status\n\n## Configuration\n\nConfiguration is stored in `~/.mem-oracle/config.json`:\n\n```json\n{\n  \"dataDir\": \"~/.mem-oracle\",\n  \"embedding\": {\n    \"provider\": \"local\",\n    \"model\": \"all-MiniLM-L6-v2\",\n    \"batchSize\": 32\n  },\n  \"vectorStore\": {\n    \"provider\": \"local\"\n  },\n  \"worker\": {\n    \"port\": 7432,\n    \"host\": \"127.0.0.1\"\n  },\n  \"crawler\": {\n    \"concurrency\": 3,\n    \"requestDelay\": 500,\n    \"timeout\": 30000,\n    \"maxPages\": 1000\n  }\n}\n```\n\n### Using API Embeddings\n\nTo use OpenAI embeddings:\n\n```json\n{\n  \"embedding\": {\n    \"provider\": \"openai\",\n    \"model\": \"text-embedding-3-small\",\n    \"apiKey\": \"sk-...\"\n  }\n}\n```\n\nOr Voyage AI:\n\n```json\n{\n  \"embedding\": {\n    \"provider\": \"voyage\",\n    \"model\": \"voyage-2\",\n    \"apiKey\": \"...\"\n  }\n}\n```\n\n## Claude Code Integration\n\n### Install as Plugin\n\n```bash\n# In Claude Code terminal\n\u003e /plugin add jagjeevanak/mem-oracle\n\u003e /plugin install mem-oracle\n```\n\nThen restart Claude Code. The plugin will automatically:\n- Check if the worker service is running on session start\n- Retrieve relevant docs when you submit prompts\n- Auto-index documentation URLs detected in your prompts\n\n### Manual Setup\n\n1. Start the worker service:\n```bash\nbun run worker\n```\n\n2. The plugin hooks in `.claude-plugin/hooks/` handle lifecycle events\n\n### As MCP Server\n\nAdd to your Claude Code MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mem-oracle\": {\n      \"command\": \"bun\",\n      \"args\": [\"run\", \"/path/to/mem-oracle/src/index.ts\", \"mcp\"]\n    }\n  }\n}\n```\n\n## Architecture\n\n### System Overview\n\n```mermaid\nflowchart TB\n    subgraph Client[\"Client Layer\"]\n        CC[Claude Code]\n        CLI[CLI]\n    end\n\n    subgraph Integration[\"Integration Layer\"]\n        PH[Plugin Hooks]\n        MCP[MCP Server]\n    end\n\n    subgraph Service[\"Service Layer\"]\n        WS[Worker Service\u003cbr/\u003e:7432]\n        OR[Orchestrator]\n    end\n\n    subgraph Processing[\"Processing Pipeline\"]\n        FE[Fetcher]\n        EX[Extractor]\n        CH[Chunker]\n        CR[Crawler]\n    end\n\n    subgraph Embedding[\"Embedding Layer\"]\n        direction LR\n        LE[Local TF-IDF]\n        OE[OpenAI]\n        VE[Voyage]\n        CE[Cohere]\n    end\n\n    subgraph Storage[\"Storage Layer\"]\n        SQL[(SQLite\u003cbr/\u003eMetadata)]\n        VS[(Vector Store)]\n        CA[(Content Cache)]\n    end\n\n    CC --\u003e PH\n    CC -.-\u003e MCP\n    CLI --\u003e WS\n    PH --\u003e WS\n    MCP --\u003e OR\n    WS --\u003e OR\n    OR --\u003e FE\n    OR --\u003e EX\n    OR --\u003e CH\n    OR --\u003e CR\n    FE --\u003e CA\n    CR --\u003e FE\n    EX --\u003e CH\n    CH --\u003e LE \u0026 OE \u0026 VE \u0026 CE\n    LE \u0026 OE \u0026 VE \u0026 CE --\u003e VS\n    OR --\u003e SQL\n    OR --\u003e VS\n```\n\n### Indexing Flow\n\n```mermaid\nsequenceDiagram\n    participant U as User/Claude\n    participant W as Worker\n    participant O as Orchestrator\n    participant F as Fetcher\n    participant E as Extractor\n    participant C as Chunker\n    participant EM as Embedder\n    participant DB as SQLite\n    participant VS as VectorStore\n\n    U-\u003e\u003eW: POST /index {baseUrl, seedSlug}\n    W-\u003e\u003eO: indexDocset(input)\n    O-\u003e\u003eDB: createDocset()\n    O-\u003e\u003eDB: createPage(seedUrl)\n    \n    Note over O,VS: Seed Page Indexing (Synchronous)\n    O-\u003e\u003eF: fetch(seedUrl)\n    F--\u003e\u003eO: HTML/MD content\n    O-\u003e\u003eE: extract(content)\n    E--\u003e\u003eO: {title, text, links}\n    O-\u003e\u003eC: chunk(extractedContent)\n    C--\u003e\u003eO: chunks[]\n    O-\u003e\u003eEM: embed(chunks)\n    EM--\u003e\u003eO: vectors[]\n    O-\u003e\u003eVS: upsert(vectors)\n    O-\u003e\u003eDB: updatePage(indexed)\n\n    O--\u003e\u003eW: docset\n    W--\u003e\u003eU: {docsetId, status}\n\n    Note over O,VS: Background Crawling (Async)\n    loop For each discovered link\n        O-\u003e\u003eDB: getNextPendingPage()\n        O-\u003e\u003eF: fetch(pageUrl)\n        O-\u003e\u003eE: extract()\n        O-\u003e\u003eC: chunk()\n        O-\u003e\u003eEM: embed()\n        O-\u003e\u003eVS: upsert()\n        O-\u003e\u003eDB: updatePage(indexed)\n    end\n```\n\n### Retrieval Flow\n\n```mermaid\nsequenceDiagram\n    participant U as User/Claude\n    participant W as Worker\n    participant O as Orchestrator\n    participant EM as Embedder\n    participant VS as VectorStore\n    participant DB as SQLite\n\n    U-\u003e\u003eW: POST /retrieve {query}\n    W-\u003e\u003eO: search(query)\n    O-\u003e\u003eEM: embedSingle(query)\n    EM--\u003e\u003eO: queryVector\n    \n    O-\u003e\u003eDB: listDocsets()\n    DB--\u003e\u003eO: docsets[]\n    \n    loop For each docset\n        O-\u003e\u003eVS: search(namespace, queryVector, topK)\n        VS--\u003e\u003eO: results[]\n    end\n    \n    O-\u003e\u003eO: sort \u0026 merge results\n    O--\u003e\u003eW: SearchResult[]\n    W--\u003e\u003eU: {results, query}\n```\n\n### Data Flow\n\n```mermaid\nflowchart LR\n    subgraph Input\n        URL[Doc URL]\n    end\n\n    subgraph Fetch\n        HTTP[HTTP Request]\n        CACHE[Cache Check]\n    end\n\n    subgraph Extract\n        HTML[HTML Parser]\n        MD[MD Parser]\n        READ[Readability]\n    end\n\n    subgraph Process\n        CHUNK[Chunker]\n        EMBED[Embedder]\n    end\n\n    subgraph Store\n        META[Metadata\u003cbr/\u003eSQLite]\n        VEC[Vectors\u003cbr/\u003eJSON]\n        CONT[Content\u003cbr/\u003eCache]\n    end\n\n    URL --\u003e CACHE\n    CACHE --\u003e|miss| HTTP\n    CACHE --\u003e|hit| Extract\n    HTTP --\u003e CONT\n    HTTP --\u003e Extract\n    HTML --\u003e READ\n    MD --\u003e Extract\n    READ --\u003e CHUNK\n    CHUNK --\u003e EMBED\n    EMBED --\u003e VEC\n    CHUNK --\u003e META\n```\n\n## Development\n\n```bash\n# Run with hot reload\nbun run dev\n\n# Type check\nbun run typecheck\n\n# Run tests\nbun test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjagjeevanak%2Fmem-oracle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjagjeevanak%2Fmem-oracle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjagjeevanak%2Fmem-oracle/lists"}