Sirchmunk: Raw data to self-evolving intelligence, real-time.

📄 Paper · 📖 Documentation

Quick Start · Key Features · MCP Server · Web UI · Docker · How it Works · FAQ

English | 中文

🌰 Why “Sirchmunk”？

Intelligence pipelines built upon vector-based retrieval can be _rigid and brittle_. They rely on static vector embeddings that are expensive to compute, blind to real-time changes, and detached from the raw context. We introduce Sirchmunk to usher in a more agile paradigm, where data is no longer treated as a snapshot, and insights can evolve together with the data.

✨ Key Features

1. EmbeddingDB-Free: Data in its Purest Form

Sirchmunk works directly with raw data -- bypassing the heavy overhead of squeezing your rich files into fixed-dimensional vectors.

• Instant Search: Eliminating complex pre-processing pipelines in hours long indexing; just drop your files and search immediately.
• Full Fidelity: Zero information loss —- stay true to your data without vector approximation.

2. Self-Evolving: A Living Index

Data is a stream, not a snapshot. Sirchmunk is dynamic by design, while vector DB can become obsolete the moment your data changes.

• Context-Aware: Evolves in real-time with your data context.
• LLM-Powered Autonomy: Designed for Agents that perceive data as it lives, utilizing token-efficient reasoning that triggers LLM inference only when necessary to maximize intelligence while minimizing cost.

3. Intelligence at Scale: Real-Time & Massive

Sirchmunk bridges massive local repositories and the web with high-scale throughput and real-time awareness.
It serves as a unified intelligent hub for AI agents, delivering deep insights across vast datasets at the speed of thought.

For more technical details, refer to the Sirchmunk blog

For reproducible experiments, see benchmarks/README.md. It documents the frozen sampled evaluation workflow, dynamic G_n/D_n corpus snapshots, lifecycle-cost accounting, and LENS ablation variants.

Traditional RAG vs. Sirchmunk

Demonstration

| WeChat Group | DingTalk Group | |:--------------:|:----------------:| | | |

🎉 News

• 🚀 Sep 20, 2026: Sirchmunk v0.2.0

• 🚀 Aug 28, 2026: Sirchmunk v0.1.0

• 🚀 Jul 21, 2026: Sirchmunk v0.0.9

🚀 Quick Start

Prerequisites

• Python 3.10+
• LLM API Key (OpenAI-compatible endpoint, local or remote)
• Node.js 18+ (Optional, for web interface)

Installation

# Create virtual environment (recommended)
conda create -n sirchmunk python=3.13 -y && conda activate sirchmunk
pip install sirchmunk
Or via UV:
uv pip install sirchmunk
Alternatively, install from source:
git clone https://github.com/modelscope/sirchmunk.git && cd sirchmunk
pip install -e .

Python SDK Usage

import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat
llm = OpenAIChat(
        api_key="your-api-key",
        base_url="your-base-url",         # e.g., https://api.openai.com/v1
        model="your-model-name",          # e.g., gpt-5.2
        enable_knowledge_evolution=False  # whether to enable runtime knowledge evolution, defaults to False
    )
async def main():
    
    searcher = AgenticSearch(llm=llm)
    
    # DEEP mode (default): rich Markdown report with budgeted evidence exploration
    result: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
        mode="DEEP",
        response_format="rich",
    )
    
    # FAST mode: greedy search, 2 LLM calls, 2-5s
    result_fast: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
        mode="FAST",
    )
    
    print(result)
asyncio.run(main())

⚠️ Notes:

• Upon initialization, AgenticSearch automatically checks if ripgrep-all and ripgrep are installed. If they are missing, it will attempt to install them automatically. If the automatic installation fails, please install them manually.

• Replace "your-api-key", "your-base-url", "your-model-name" and /path/to/documents with your actual values.

from sirchmunk.llm import OpenAIChat
llm = OpenAIChat(
    api_key="your-minimax-api-key",
    base_url="https://api.minimax.io/v1",
    model="MiniMax-M3"             # or "MiniMax-M2.7" / "MiniMax-M2.7-highspeed"
)

Command Line Interface

Sirchmunk provides a powerful CLI for server management and search operations.

Installation

pip install "sirchmunk[web]"
or install via UV
uv pip install "sirchmunk[web]"

Initialize

# Initialize Sirchmunk with default settings (Default work path: ~/.sirchmunk/)
sirchmunk init
Alternatively, initialize with custom work path
sirchmunk init --work-path /path/to/workspace

Start Server

# Start backend API server only
sirchmunk serve
Custom host and port
sirchmunk serve --host 0.0.0.0 --port 8000

Search

# Search in current directory (DEEP mode with rich output by default)
sirchmunk search "How does authentication work?"
Search in specific paths
sirchmunk search "find all API endpoints" ./src ./docs
FAST mode: greedy search with 2 LLM calls
sirchmunk search "database architecture" --mode FAST
Quick filename search
sirchmunk search "config" --mode FILENAME_ONLY
Output as JSON
sirchmunk search "database schema" --output json
Use API server (requires running server)
sirchmunk search "query" --api --api-url http://localhost:8584

Available Commands

| Command | Description | |---------|-------------| | sirchmunk init | Initialize working directory, .env, and MCP config | | sirchmunk serve | Start the backend API server | | sirchmunk search | Perform search queries | | sirchmunk web init | Build WebUI frontend (requires Node.js 18+) | | sirchmunk web serve | Start API + WebUI (single port) | | sirchmunk web serve --dev | Start API + Next.js dev server (hot-reload) | | sirchmunk mcp serve | Start the MCP server (stdio/HTTP) | | sirchmunk mcp version | Show MCP version information | | sirchmunk compile | Compile documents into knowledge indices (Beta) | | sirchmunk version | Show version information |

Knowledge Compile (Beta)

Pre-process document collections into hierarchical tree indices and knowledge clusters to improve retrieval accuracy. This is an optional step — search works without it, but compile artifacts can significantly boost precision for large document sets.

# Compile documents (incremental by default)
sirchmunk compile --paths /path/to/documents
Full recompile (ignore cache)
sirchmunk compile --paths /path/to/documents --full
Shallow mode (skip tree indexing, faster)
sirchmunk compile --paths /path/to/documents --shallow
Check compile status
sirchmunk compile --paths /path/to/documents --status
Run knowledge health checks
sirchmunk compile --lint --work-path ~/.sirchmunk
Auto-fix lint issues
sirchmunk compile --lint --fix --work-path ~/.sirchmunk

Note: This feature is in Beta. The compile artifacts are automatically detected by the search pipeline — no additional configuration is needed after compilation.

🔌 MCP Server

Sirchmunk provides a Model Context Protocol (MCP) server that exposes its intelligent search capabilities as MCP tools. This enables seamless integration with AI assistants like Claude Desktop and Cursor IDE.

Quick Start

# Install with MCP support
pip install sirchmunk[mcp]
Initialize (generates .env and mcp_config.json)
sirchmunk init
Optional: use a custom work path
sirchmunk init --work-path /path/to/your_work_path
Edit ~/.sirchmunk/.env with your LLM API key
Test with MCP Inspector
npx @modelcontextprotocol/inspector sirchmunk mcp serve
Optional: use a custom work path for this MCP run
npx @modelcontextprotocol/inspector sirchmunk mcp serve --work-path /path/to/your_work_path

mcp_config.json Configuration

After running sirchmunk init, a ~/.sirchmunk/mcp_config.json file is generated. Copy it to your MCP client configuration directory.

Example:

{
  "mcpServers": {
    "sirchmunk": {
      "command": "sirchmunk",
      "args": ["mcp", "serve"],
      "env": {
        "SIRCHMUNK_SEARCH_PATHS": "",
        "SIRCHMUNK_WORK_PATH": "/path/to/your_work_path"
      }
    }
  }
}

| Parameter | Description | |---|---| | command | The command to start the MCP server. Use full path (e.g. /path/to/venv/bin/sirchmunk) if running in a virtual environment. | | args | Command arguments. ["mcp", "serve"] starts the MCP server in stdio mode. | | env.SIRCHMUNK_SEARCH_PATHS | Default document search directories (comma-separated). Supports both English , and Chinese ， as delimiters. When set, these paths are used as default if no paths parameter is provided during tool invocation. | | env.SIRCHMUNK_WORK_PATH | Sets the Sirchmunk working directory used by MCP server (.env, cache, knowledge, history). Recommended for persistent MCP clients. |

Tip: MCP Inspector is a great way to test the integration before connecting to your AI assistant.

In MCP Inspector: Connect → Tools → List Tools → sirchmunk_search → Input parameters (query and paths, e.g. ["/path/to/your_docs"]) → Run Tool.

You can override the working directory temporarily with sirchmunk mcp serve --work-path /path/to/your_work_path.

Features

• Multi-Mode Search: DEEP mode (default, comprehensive 10-30s), FAST mode (greedy 2-5s), FILENAME_ONLY for fast file discovery
• Knowledge Cluster Management: Automatic extraction, storage, and reuse of knowledge
• Standard MCP Protocol: Works with stdio and Streamable HTTP transports

🖥️ Web UI

The web UI is built for fast, transparent workflows: chat, knowledge analytics, and system monitoring in one place.

_{Home — Chat with streaming logs, file-based RAG, and session management.}

_{Monitor — System health, chat activity, knowledge analytics, and LLM usage.}

_{Knowledge Graph — Interactive visualization of knowledge clusters with lifecycle stages.}

Option 1: Single-Port Mode (Recommended)

Build the frontend once, then serve everything from a single port — no Node.js needed at runtime.

# Build WebUI frontend (requires Node.js 18+ at build time)
sirchmunk web init
Start server with embedded WebUI
sirchmunk web serve

Access: http://localhost:8584 (API + WebUI on the same port)

Option 2: Development Mode

For frontend development with hot-reload:

# Start backend + Next.js dev server
sirchmunk web serve --dev

Access: - Frontend (hot-reload): http://localhost:8585 - Backend APIs: http://localhost:8584/docs

Option 3: Legacy Script

# Start frontend and backend via script
python scripts/start_web.py
Stop all services
python scripts/stop_web.py

Configuration:

• Access Settings → Envrionment Variables to configure LLM API, and other parameters.

🐳 Docker Deployment

Pre-built Docker images are available on Alibaba Cloud Container Registry:

| Region | Image | |---|---------------------------------------------------------------------------------------------------------| | US West | modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7 | | China Beijing | modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7 |

# Pull the image
docker pull modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7
Start the service
docker run -d \
  --name sirchmunk \
  --cpus="4" \
  --memory="2g" \
  -p 8584:8584 \
  -e LLM_API_KEY="your-api-key-here" \
  -e LLM_BASE_URL="https://api.openai.com/v1" \
  -e LLM_MODEL_NAME="gpt-5.2" \
  -e LLM_TIMEOUT=60.0 \
  -e UI_THEME=light \
  -e UI_LANGUAGE=en \
  -e SIRCHMUNK_VERBOSE=false \
  -e SIRCHMUNK_ENABLE_CLUSTER_REUSE=false \
  -e SIRCHMUNK_SEARCH_PATHS=/mnt/docs \
  -v /path/to/your_work_path:/data/sirchmunk \
  -v /path/to/your/docs:/mnt/docs:ro \
  modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.7
  
Stop and remove the service
docker stop sirchmunk && docker rm sirchmunk

Open http://localhost:8584 to access the WebUI, or call the API directly:

import requests
response = requests.post(
    "http://localhost:8584/api/v1/search",
    json={
        "query": "your search question here",
        "paths": ["/mnt/docs"],
    },
)
print(response.json())

📖 For full Docker parameters and usage, see docker/README.md.

🏗️ How it Works

LENS Framework

_{LENS reframes in-context search as budgeted evidence exploration over a latent evidence space induced by dynamic raw documents.}

For the full technical treatment of Sirchmunk and LENS, see the Sirchmunk main paper.

Core Components

| Component | Description | |:----------------------|:-------------------------------------------------------------------------| | AgenticSearch | Search orchestrator with FAST / DEEP / FILENAME_ONLY modes and budget-aware evidence localization | | KnowledgeBase | Persists source-grounded evidence clusters as reusable warm priors for later queries | | EvidenceProcessor | Consolidates candidate regions into compact, traceable evidence units | | GrepRetriever | High-performance _indexless_ file search with parallel processing | | OpenAIChat | Unified LLM interface supporting streaming and usage tracking | | MonitorTracker | Real-time system and application metrics collection |

Budgeted Evidence Exploration

Traditional retrieval systems read entire documents or rely on fixed-size chunks, leading to either wasted tokens or lost context. LENS instead treats the relevant evidence as latent and query-conditioned: the system first forms a low-cost prior over likely evidence regions, then spends LLM calls only where observations are most useful.

The workflow has three layers:

1. Low-cost prior: lexical anchors, document-path structure, compiled summaries, historical source-grounded evidence, and lightweight corpus scans narrow the candidate subspace before expensive oracle calls.

1. Budget-constrained sequential inference: candidate regions are proposed, observed by an LLM relevance oracle, and used to update the belief state until the budget-aware stopping rule says the evidence is sufficient.

1. Consolidation and synthesis: selected regions are merged into a compact source-grounded evidence set, synthesized into an answer, and optionally persisted as reusable knowledge for follow-up queries.

• Index-free over raw documents: Search can run directly over dynamic files without pre-materializing a persistent embedding or chunk index.
• Source-grounded: The final answer is paired with traceable evidence regions instead of opaque vector hits.
• Budget-aware: LLM calls are spent adaptively on uncertain or high-value evidence regions, with explicit telemetry for cost and latency.

Self-Evolving Knowledge Clusters

Sirchmunk does not discard search results after answering a query. Instead, every search produces a KnowledgeCluster — a structured, reusable knowledge unit that grows smarter over time. This is what makes the system _self-evolving_.

What is a KnowledgeCluster?

A KnowledgeCluster is a richly annotated object that captures the full cognitive output of a single search cycle:

| Field | Purpose | |:------|:--------| | Evidences | Source-linked evidence regions localized by LENS, each with file path, summary, and raw text | | Content | LLM-synthesized markdown with structured analysis and references | | Patterns | 3–5 distilled design principles or mechanisms identified from the evidence | | Confidence | A consensus score \[0, 1\] indicating the reliability of the cluster | | Queries | Historical queries that contributed to or reused this cluster (FIFO, max 5) | | Hotness | Activity score reflecting query frequency and recency | | Embedding | 384-dim vector derived from accumulated queries, enabling semantic retrieval |

Lifecycle: From Creation to Evolution

┌─────── New Query ───────┐
 │                          ▼
 │     ┌──────────────────────────────┐
 │     │  Phase 0: Semantic Reuse     │──── Match found ──→ Return cached cluster
 │     │  (cosine similarity ≥ 0.85)  │                     + update hotness/queries/embedding
 │     └──────────┬───────────────────┘
 │           No match
 │                ▼
 │     ┌──────────────────────────────┐
 │     │  Phase 1–3: Full Search      │
 │     │  (keywords → retrieval →     │
 │     │   evidence localization →   │
 │     └──────────┬───────────────────┘
 │                ▼
 │     ┌──────────────────────────────┐
 │     │  Build New Cluster           │
 │     │  Deterministic ID: C{sha256} │
 │     └──────────┬───────────────────┘
 │                ▼
 │     ┌──────────────────────────────┐
 │     │  Phase 5: Persist            │
 │     │  Embed queries → DuckDB →    │
 │     │  Parquet (atomic sync)       │
 └─────└──────────────────────────────┘

1. Reuse Check (Phase 0): Before any retrieval, the query is embedded and compared against all stored clusters via cosine similarity. If a high-confidence match is found, the existing cluster is returned instantly — saving LLM tokens and search time entirely.

1. Creation (Phase 1–3): When no reuse match is found, the full pipeline runs: keyword extraction, file retrieval, budgeted evidence localization, and LLM synthesis produce a new KnowledgeCluster.

1. Persistence (Phase 5): The cluster is stored in an in-memory DuckDB table and periodically flushed to Parquet files. Atomic writes and mtime-based reload ensure multi-process safety.

1. Evolution on Reuse: Each time a cluster is reused, the system:

1. Runtime Periodic Evolution: As retrieval continues, the system periodically reshapes the cluster topology — evolving scattered, isolated points into a locally connected semantic graph.

Knowledge Evolver Architecture

The four-phase evolution cycle is orchestrated by the KnowledgeEvolver, running asynchronously in the background:

• Top layer: Event loop monitors search activity and triggers evolution phases based on buffer counts and step intervals.
• Middle layer: The four phases execute sequentially — Connect & Merge consolidates related clusters (similarity ≥ 0.90 merges, ≥ 0.60 creates edges), Refresh Edges updates inter-cluster relationships, Detect Meta Clusters applies Leiden community detection to discover higher-order structure, and Global Update synchronizes lifecycle states.
• Bottom layer: Results persist to DuckDB + Parquet, with an incremental manifest ensuring crash recovery.

Watch how knowledge clusters emerge, merge, and form meta-communities over a series of search interactions:

Key Properties

• Zero-cost acceleration: Repeated or semantically similar queries are answered from cached clusters without any LLM inference, making subsequent searches near-instantaneous.
• Query-driven embeddings: Cluster embeddings are derived from _queries_ rather than content, ensuring that retrieval aligns with how users actually ask questions — not how documents are written.
• Semantic broadening: As diverse queries reuse the same cluster, its embedding drifts to cover a wider semantic neighborhood, naturally improving recall for related future queries.
• Lightweight persistence: DuckDB in-memory + Parquet on disk — no external database infrastructure required. Background daemon sync with configurable flush intervals keeps overhead minimal.

Data Storage

All persistent data is stored in the configured SIRCHMUNK_WORK_PATH (default: ~/.sirchmunk/):

{SIRCHMUNK_WORK_PATH}/
  ├── .cache/
    ├── history/              # Chat session history (DuckDB)
    │   └── chat_history.db
    └── knowledge/            # Knowledge clusters (Parquet)
        └── knowledge_clusters.parquet

🔗 HTTP Client Access (Search API)

When the server is running (sirchmunk serve or sirchmunk web serve), the Search API is accessible via any HTTP client.

# DEEP mode (default rich report with budgeted evidence exploration)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does authentication work?",
    "paths": ["/path/to/project"],
    "mode": "DEEP",
    "response_format": "rich"
  }'
Single path as a string (equivalent to a one-element list)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does authentication work?",
    "paths": "/path/to/project"
  }'
Omit paths — use SIRCHMUNK_SEARCH_PATHS from ~/.sirchmunk/.env on the server
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "How does authentication work?"}'
DEEP mode (comprehensive analysis with budgeted evidence exploration)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database connection pooling",
    "paths": ["/path/to/project/src"],
    "mode": "DEEP",
    "response_format": "rich"
  }'
Filename search (no LLM required)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "config",
    "paths": ["/path/to/project"],
    "mode": "FILENAME_ONLY"
  }'
Full parameters (see Request Parameters table)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database connection pooling",
    "paths": ["/path/to/project/src"],
    "mode": "DEEP",
    "max_depth": 10,
    "top_k_files": 20,
    "max_loops": 10,
    "include_patterns": [".py", ".java"],
    "exclude_patterns": ["test", "__pycache__"],
    "response_format": "rich"
  }'
Check server status
curl http://localhost:8584/api/v1/search/status

import requests
response = requests.post(
    "http://localhost:8584/api/v1/search",
    json={
        "query": "How does authentication work?",
        "paths": ["/path/to/project"],
    },
    timeout=60
)
data = response.json()
if data["success"]:
    payload = data.get("data") or {}
    # API returns type "summary" | "files" | "context".
    # For summary responses, format is "rich" (default) or "minimal".
    print(payload.get("summary", payload))

import httpx
import asyncio
async def search():
    async with httpx.AsyncClient(timeout=300) as client:
        resp = await client.post(
            "http://localhost:8584/api/v1/search",
            json={
                "query": "find all API endpoints",
                # Optional: omit "paths" to use server SIRCHMUNK_SEARCH_PATHS
                "paths": ["/path/to/project"],
            }
        )
        data = resp.json()
        if data.get("success"):
            p = data.get("data") or {}
            print(p.get("summary", p))
asyncio.run(search())

const response = await fetch("http://localhost:8584/api/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "How does authentication work?",
    paths: ["/path/to/project"],
  })
});
const data = await response.json();
if (data.success) {
  const p = data.data || {};
  console.log(p.summary ?? p);
}

curl -N -X POST "http://localhost:8584/api/v1/search/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "query": "How does authentication work?",
    "paths": ["/path/to/project"],
    "mode": "DEEP",
    "response_format": "rich"
  }'

import json
import requests
url = "http://localhost:8584/api/v1/search/stream"
payload = {
    "query": "How does authentication work?",
    "paths": ["/path/to/project"],
    "mode": "DEEP",
    "response_format": "rich",
}
event_type = ""
with requests.post(
    url, json=payload, stream=True, timeout=(10, 600),
    headers={"Accept": "text/event-stream"},
) as resp:
    resp.raise_for_status()
    for raw in resp.iter_lines(decode_unicode=True):
        if raw is None or raw == "":
            continue
        if raw.startswith(":"):
            continue
        if raw.startswith("event: "):
            event_type = raw[7:].strip()
            continue
        if raw.startswith("data: "):
            obj = json.loads(raw[6:])
            if event_type == "log":
                print(f"[{obj.get('level', 'info')}] {obj.get('message', '')}")
            elif event_type == "result":
                print("DONE:", json.dumps(obj, indent=2, ensure_ascii=False))
            elif event_type == "error":
                print("ERROR:", obj.get("error"))
            event_type = ""

import json
import httpx
url = "http://localhost:8584/api/v1/search/stream"
payload = {"query": "find API routes", "paths": ["/path/to/project"], "mode": "DEEP"}
event_type = ""
with httpx.Client(timeout=httpx.Timeout(600.0, connect=10.0)) as client:
    with client.stream(
        "POST",
        url,
        json=payload,
        headers={"Accept": "text/event-stream"},
    ) as resp:
        resp.raise_for_status()
        for line in resp.iter_lines():
            if not line or line.startswith(":"):
                continue
            if line.startswith("event: "):
                event_type = line[7:].strip()
                continue
            if line.startswith("data: "):
                obj = json.loads(line[6:])
                if event_type == "log":
                    print(obj.get("message", ""))
                elif event_type == "result":
                    data = obj.get("data", {})
                    print(data.get("summary") or data)
                event_type = ""