Sirchmunk

https://modelscope.github.io/sirchmunk-web/docs/
Admin
Sirchmunk is an open-source, embedding-free agentic search engine that transforms raw data into...
Tokens:12,867
Snippets:168
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install and Initialize Sirchmunk

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Install the package and generate the initial configuration file.

```bash
pip install sirchmunk
sirchmunk init          # creates ~/.sirchmunk/.env
```

--------------------------------

### Install OpenClaw Skill

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Install the skill using the ClawHub CLI tool.

```bash
npx clawhub@latest install sirchmunk
```

--------------------------------

### Install SirchMunk CLI

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Install SirchMunk with different feature sets. Use `[web]` for Web UI support and `[mcp]` for MCP support. `[all]` installs all features.

```bash
# Basic installation (search + CLI)
pip install sirchmunk

# With Web UI support
pip install "sirchmunk[web]"

# With MCP support
pip install "sirchmunk[mcp]"

# Everything
pip install "sirchmunk[all]"
```

--------------------------------

### Python SDK Installation

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Install the Sirchmunk Python SDK using pip.

```APIDOC
## Installation

```
pip install sirchmunk
```
```

--------------------------------

### Install Sirchmunk Python SDK

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Install the Sirchmunk Python SDK using pip.

```bash
pip install sirchmunk

```

--------------------------------

### Initialize and Serve Web UI

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/web-ui

Recommended production setup that builds the frontend and serves it alongside the API on a single port.

```bash
# Build WebUI frontend (requires Node.js 18+ at build time)
sirchmunk web init

# Start server with embedded WebUI
sirchmunk web serve
```

--------------------------------

### Start SirchMunk API Server

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Start the backend API server. The default host is `localhost` and the default port is `8584`.

```bash
# Default: localhost:8584
sirchmunk serve

# Custom host and port
sirchmunk serve --host 0.0.0.0 --port 8000
```

--------------------------------

### Start MCP Server in Stdio Mode

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Default command to start the MCP server for local desktop AI tool integration.

```bash
sirchmunk mcp serve
```

--------------------------------

### Start Development Mode

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/web-ui

Enables hot-reload for frontend development, separating the frontend and backend ports.

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

--------------------------------

### Serve SirchMunk WebUI

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Start the API and WebUI from a single port. Use `--dev` for development mode with hot-reloading.

```bash
# Production mode (requires prior `web init`)
sirchmunk web serve

# Development mode with hot-reload
sirchmunk web serve --dev
```

--------------------------------

### Start and Verify Sirchmunk Server

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Launch the API server and verify its status via a curl request.

```bash
sirchmunk serve          # default: http://0.0.0.0:8584
```

```bash
curl http://localhost:8584/api/v1/search/status
```

--------------------------------

### Install Sirchmunk using pip or UV

Source: https://modelscope.github.io/sirchmunk-web/docs/getting-started

Installs Sirchmunk using pip or UV. It's recommended to use a virtual environment.

```bash
# Create virtual environment (recommended)
conda create -n sirchmunk python=3.13 -y && conda activate sirchmunk

# Install from PyPI
pip install sirchmunk

# Or via UV
uv pip install sirchmunk
```

```bash
# Or install from source
git clone https://github.com/modelscope/sirchmunk.git && cd sirchmunk
pip install -e .
```

--------------------------------

### Start SirchMunk MCP Server

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Start the MCP server for AI assistant integration. Supports `stdio` mode for integrations like Claude Desktop and Cursor IDE, and `http` mode.

```bash
# stdio mode (for Claude Desktop, Cursor IDE)
sirchmunk mcp serve

# HTTP mode
sirchmunk mcp serve --transport http --port 3000
```

--------------------------------

### Search API cURL Examples

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Examples of using cURL to perform searches in FAST, DEEP, and FILENAME_ONLY modes.

```bash
# FAST mode (default, greedy search with 2 LLM calls); paths optional
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does authentication work?",
    "mode": "FAST",
    "paths": ["/path/to/project"]
  }'

# DEEP mode (comprehensive analysis with Monte Carlo sampling)
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"
  }'

# 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"
  }'
```

--------------------------------

### Start MCP Server in HTTP Mode

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Command to start the MCP server for remote or networked scenarios using HTTP transport.

```bash
sirchmunk mcp serve --transport http --port 3000
```

--------------------------------

### Execute Legacy Web Scripts

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/web-ui

Alternative method for starting and stopping the web services using Python scripts.

```bash
# Start frontend and backend
python scripts/start_web.py

# Stop all services
python scripts/stop_web.py
```

--------------------------------

### Initialize Sirchmunk MCP

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Commands to install the package with MCP support, initialize the configuration, and test the server using the MCP Inspector.

```bash
# Install with MCP support
pip install "sirchmunk[mcp]"

# Initialize (generates .env and mcp_config.json)
sirchmunk init

# Edit ~/.sirchmunk/.env with your LLM API key

# Test with MCP Inspector
npx @modelcontextprotocol/inspector sirchmunk mcp serve
```

--------------------------------

### Basic Sirchmunk Search (FAST Mode)

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Perform a basic search using the AgenticSearch class. The `paths` parameter is optional and defaults to environment variables or the current directory if omitted. Initialization automatically checks for and attempts to install ripgrep and ripgrep-all if missing.

```python
import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat

# Initialize the LLM interface
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-4o
)

async def main():
    searcher = AgenticSearch(llm=llm)

    # FAST mode (default): greedy search, 2 LLM calls, 2-5s
    result: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
    )

    # DEEP mode: comprehensive analysis with Monte Carlo sampling, 10-30s
    result_deep: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
        mode="DEEP",
    )

    print(result)

asyncio.run(main())

```

--------------------------------

### Pull and Run SirchMunk Docker Image

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/docker

Pull the specified Docker image and start the SirchMunk service with custom configurations for CPU, memory, ports, and environment variables. Mount local directories for persistent storage and documents.

```bash
# Pull the image
docker pull modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/sirchmunk:ubuntu22.04-py312-0.0.6

# 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.6

```

--------------------------------

### GET /api/v1/search/status

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Checks the server's health, LLM configuration, and concurrency limits.

```APIDOC
## GET /api/v1/search/status

### Description
Check server health, LLM configuration, and concurrency limits.

### Method
GET

### Endpoint
/api/v1/search/status

### Response
#### Success Response (200)
- **status** (string) - Server status, e.g., "ok".
- **llm_configured** (bool) - Indicates if the LLM is configured.
- **version** (string) - The SirchMunk version.
- **max_concurrent_searches** (int) - The maximum number of concurrent searches allowed.

#### Response Example
```json
{
  "status": "ok",
  "llm_configured": true,
  "version": "0.0.6post1",
  "max_concurrent_searches": 4
}
```
```

--------------------------------

### Search API Request Body

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Example JSON payload for the POST /api/v1/search endpoint.

```json
{
  "query": "How does authentication work?",
  "mode": "FAST",
  "paths": ["/path/to/project"],
  "max_depth": 10,
  "top_k_files": 20,
  "enable_dir_scan": true,
  "max_loops": 8,
  "max_token_budget": 131072,
  "include_patterns": ["*.py", "*.java"],
  "exclude_patterns": ["*test*", "*__pycache__*"],
  "return_context": false
}
```

--------------------------------

### LLM Provider Compatibility

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Information on compatible LLM providers and examples of how to configure Sirchmunk to use them, including local models and custom endpoints.

```APIDOC
## LLM Provider Compatibility

Sirchmunk works with any OpenAI-compatible API endpoint:
  * **OpenAI** — GPT-4, GPT-4o, GPT-3.5
  * **Local models** — Ollama, llama.cpp, vLLM, SGLang
  * **Claude** — Via API proxy
  * **Any OpenAI-compatible endpoint**

```python
# Example: Using a local Ollama model
llm = OpenAIChat(
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    model="llama3"
)

# Example: Using a custom endpoint
llm = OpenAIChat(
    api_key="your-key",
    base_url="https://your-custom-endpoint.com/v1",
    model="your-model"
)
```
```

--------------------------------

### Status API Response

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

JSON response for the GET /api/v1/search/status endpoint indicating server health.

```json
{
  "status": "ok",
  "llm_configured": true,
  "version": "0.0.6post1",
  "max_concurrent_searches": 4
}
```

--------------------------------

### Monitor LLM Token Usage via API

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/i18n

Retrieve LLM usage metrics by making a GET request to the /api/v1/monitor/llm endpoint.

```http
GET /api/v1/monitor/llm
```

--------------------------------

### Basic Usage

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Demonstrates how to initialize the LLM and perform a basic search using the AgenticSearch class.

```APIDOC
## Basic Usage

```python
import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat

# Initialize the LLM interface
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-4o
)

async def main():
    searcher = AgenticSearch(llm=llm)

    # FAST mode (default): greedy search, 2 LLM calls, 2-5s
    result: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
    )

    # DEEP mode: comprehensive analysis with Monte Carlo sampling, 10-30s
    result_deep: str = await searcher.search(
        query="How does transformer attention work?",
        paths=["/path/to/documents"],
        mode="DEEP",
    )

    print(result)

asyncio.run(main())
```

Note
The `paths` parameter is optional. When omitted, search roots fall back to the `SIRCHMUNK_SEARCH_PATHS` environment variable, then the current working directory.
```

--------------------------------

### Initialize SirchMunk Workspace

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Initialize the working directory, `.env` configuration, and MCP config. The default work path is `~/.sirchmunk/`.

```bash
# Default work path: ~/.sirchmunk/
sirchmunk init

# Custom work path
sirchmunk init --work-path /path/to/workspace
```

--------------------------------

### View File Structure

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Overview of the directory layout for the OpenClaw skill.

```text
recipes/openclaw_skills/
├── README.md
├── assets/
│   ├── example1.png                # Chinese usage screenshot
│   └── example2.png                # English usage screenshot
└── sirchmunk/
    ├── SKILL.md                    # OpenClaw skill manifest
    └── scripts/
        └── sirchmunk_search.sh     # Wrapper script invoked by the agent
```

--------------------------------

### Build SirchMunk WebUI Frontend

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Build the WebUI frontend. Requires Node.js 18+ at build time.

```bash
sirchmunk web init
```

--------------------------------

### Initialize Sirchmunk

Source: https://modelscope.github.io/sirchmunk-web/docs/getting-started

Initializes Sirchmunk with default settings or a custom workspace path.

```bash
# Initialize with default settings (work path: ~/.sirchmunk/)
sirchmunk init
```

```bash
# Or with a custom work path
sirchmunk init --work-path /path/to/workspace
```

--------------------------------

### View Repository Layout

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/project-structure

Displays the directory structure of the Sirchmunk project, highlighting core packages and the frontend.

```text
sirchmunk/
├── src/
│   ├── sirchmunk/              # Core Python package
│   │   ├── agentic/            # ReAct agent, tools, prompts
│   │   ├── api/                # FastAPI REST endpoints
│   │   │   └── components/     # History, monitor, settings storage
│   │   ├── cli/                # CLI entry point and web launcher
│   │   ├── insight/            # Text insight extraction
│   │   ├── learnings/          # Evidence processing, knowledge base
│   │   ├── llm/                # LLM interface (OpenAI-compatible)
│   │   ├── retrieve/           # Indexless retrieval engine
│   │   ├── scan/               # Directory and file scanners
│   │   ├── schema/             # Data models (knowledge, context, etc.)
│   │   ├── storage/            # DuckDB + Parquet persistence
│   │   ├── utils/              # Utilities (embedding, tokenizer, etc.)
│   │   ├── search.py           # Main search orchestrator
│   │   └── base.py             # Base classes and abstractions
│   └── sirchmunk_mcp/          # MCP server package
│       ├── server.py           # MCP server implementation
│       ├── service.py          # Search service layer
│       └── tools.py            # MCP tool definitions
├── web/                # Next.js 14 frontend
│   ├── app/                    # Pages (home, history, knowledge, monitor, settings)
│   ├── components/             # React components
│   ├── hooks/                  # Custom React hooks
│   └── lib/                    # Utilities (API, i18n, theme)
├── config/                     # Configuration templates
├── scripts/                    # Helper scripts
└── requirements/               # Dependency files by feature
```

--------------------------------

### Configure Sirchmunk Environment

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Set the required LLM API credentials and optional search paths in the configuration file.

```text
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1   # or any OpenAI-compatible endpoint
LLM_MODEL_NAME=gpt-4o

# Optional: default search directories (comma-separated)
SIRCHMUNK_SEARCH_PATHS=/path/to/your/docs,/another/path
```

--------------------------------

### Configure LLM Provider

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/customization

Set these environment variables in your .env file to connect to an OpenAI-compatible API.

```text
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://your-provider.com/v1
LLM_MODEL=your-model-name
```

--------------------------------

### Run Sirchmunk Search via Python SDK

Source: https://modelscope.github.io/sirchmunk-web/docs/getting-started

Executes a search query using the Sirchmunk Python SDK. Requires LLM configuration and asyncio.

```python
import asyncio
from sirchmunk import AgenticSearch
from sirchmunk.llm import OpenAIChat

llm = OpenAIChat(api_key='your-key', base_url='your-url', model='your-model')

async def main():
    searcher = AgenticSearch(llm=llm)
    # paths is optional: SIRCHMUNK_SEARCH_PATHS env, else current working directory
    result = await searcher.search(query='How does authentication work?')
    print(result)

asyncio.run(main())
```

--------------------------------

### Configure MCP Server

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

JSON configuration structure for the MCP client, including command, arguments, and environment variables for search paths.

```json
{
  "mcpServers": {
    "sirchmunk": {
      "command": "sirchmunk",
      "args": ["mcp", "serve"],
      "env": {
        "SIRCHMUNK_SEARCH_PATHS": "/path/to/your_docs,/another/path"
      }
    }
  }
}
```

--------------------------------

### Search API Call with Python Requests

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/docker

Demonstrates how to make a search API call to the running SirchMunk service using the Python requests library. Ensure the service is accessible at http://localhost:8584.

```python
import requests

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

```

--------------------------------

### Define Skill Manifest

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

The SKILL.md file defines the tool capabilities for the OpenClaw runtime.

```markdown
---
name: sirchmunk
description: Local file search using sirchmunk API. Use when you need to search for files or content by asking natural language questions.
---
```

--------------------------------

### Perform Manual API Search

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Send a POST request to the local server to perform a search operation.

```bash
curl -s -X POST "http://localhost:8584/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "your question",
    "mode": "FAST"
  }'
```

--------------------------------

### Sirchmunk Search Parameters

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Configure search behavior with various parameters including mode, depth, file patterns, and context return.

```python
result = await searcher.search(
    query="database connection pooling",        # Required: search question
    paths=["/path/to/project/src"],             # Optional: directories (env, then cwd)
    mode="FAST",                                # FAST (default), DEEP, or FILENAME_ONLY
    max_depth=10,                               # Max directory depth
    top_k_files=20,                             # Number of top files
    max_loops=10,                               # Max search loops
    include_patterns=["*.py", "*.java"],
    exclude_patterns=["*test*", "*__pycache__*"], # Patterns to exclude
    return_context=True,                        # Return full SearchContext
)

```

--------------------------------

### Tracking LLM Usage

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Iterate through `searcher.llm_usages` after search completion to access prompt tokens, completion tokens, and total tokens.

```python
# After search completion
for usage in searcher.llm_usages:
    print(f"Prompt tokens: {usage.prompt_tokens}")
    print(f"Completion tokens: {usage.completion_tokens}")
    print(f"Total tokens: {usage.total_tokens}")

```

--------------------------------

### Perform SirchMunk Search Queries

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Perform search queries directly from the terminal. Supports FAST mode (default), DEEP mode for comprehensive analysis, FILENAME_ONLY for quick filename searches, JSON output, and API server integration.

```bash
# Search in current directory (FAST mode by default)
sirchmunk search "How does authentication work?"

# Search in specific paths
sirchmunk search "find all API endpoints" ./src ./docs

# DEEP mode: comprehensive analysis with Monte Carlo sampling
sirchmunk search "database architecture" --mode DEEP

# Quick filename search (no LLM required)
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
```

--------------------------------

### Accessing Basic Search Results

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Retrieve and print the search results as a formatted markdown string.

```python
# The result is a formatted markdown string
result = await searcher.search(query="...", paths=["..."])
print(result)

```

--------------------------------

### Configure LLM Settings

Source: https://modelscope.github.io/sirchmunk-web/docs/getting-started

Edits the .env file to set your LLM API key, base URL, and model.

```dotenv
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o
```

--------------------------------

### Using Custom OpenAI-Compatible Endpoint

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Configure the OpenAIChat interface to connect to a custom OpenAI-compatible API endpoint by specifying the `base_url` and `model`.

```python
# Example: Using a custom endpoint
llm = OpenAIChat(
    api_key="your-key",
    base_url="https://your-custom-endpoint.com/v1",
    model="your-model"
)

```

--------------------------------

### POST /api/v1/search/stream

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Accepts the same JSON body as `POST /api/v1/search`. The connection remains open, emitting Server-Sent Events (SSE) for progress logs and a final event with the result or error.

```APIDOC
## POST /api/v1/search/stream

### Description
Same JSON body as `POST /api/v1/search`. The connection stays open and emits Server-Sent Events: progress logs during execution, then a final event with the completed result or an error payload.

### Method
POST

### Endpoint
/api/v1/search/stream

### Parameters
#### Request Body
(Same as `POST /api/v1/search`)

### Response
Server-Sent Events stream including logs and a final result or error event.
```

--------------------------------

### Using Local Ollama Model with Sirchmunk

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Configure the OpenAIChat interface to use a local Ollama model by setting the appropriate `base_url` and `api_key`.

```python
# Example: Using a local Ollama model
llm = OpenAIChat(
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    model="llama3"
)

```

--------------------------------

### Access Knowledge Clusters

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/customization

Locate and query knowledge cluster files stored in the cache directory.

```python
# Knowledge clusters are stored at:
# {SIRCHMUNK_WORK_PATH}/.cache/knowledge/knowledge_clusters.parquet

# Query using DuckDB or the KnowledgeManager API
```

--------------------------------

### Run Sirchmunk Search via CLI

Source: https://modelscope.github.io/sirchmunk-web/docs/getting-started

Performs a search query within a specified directory using the Sirchmunk command-line interface.

```bash
# Search in a directory
sirchmunk search "How does authentication work?" ./src
```

--------------------------------

### Display SirchMunk Version Information

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/cli

Display version information for SirchMunk and its MCP component.

```bash
sirchmunk version
sirchmunk mcp version
```

--------------------------------

### MCP Tool: sirchmunk_list_clusters

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Lists all stored knowledge clusters available in the system.

```APIDOC
## sirchmunk_list_clusters

### Description
List all stored knowledge clusters.
```

--------------------------------

### Add Documents for Search in Sirchmunk

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/i18n

Specify the path to folders or files directly in your search query. No pre-processing or indexing is required before adding documents.

```python
result = await searcher.search(
    query="Your question",
    paths=["/path/to/folder", "/path/to/file.pdf"]
)

```

--------------------------------

### Search API Async Python Request

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Asynchronous search request using the httpx library.

```python
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",
                "paths": ["/path/to/project"],
            }
        )
        data = resp.json()
        print(data.get("data", {}).get("summary", data))

asyncio.run(search())
```

--------------------------------

### Invoke Sirchmunk Search

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/recipes/openclaw

Execute the search script directly with a query and optional path overrides.

```bash
# Use default SIRCHMUNK_SEARCH_PATHS from the server environment
~/.openclaw/skills/sirchmunk/scripts/sirchmunk_search.sh "What is the reward function?"

# Override with an explicit path
~/.openclaw/skills/sirchmunk/scripts/sirchmunk_search.sh "auth flow" "/path/to/project"
```

--------------------------------

### View Sirchmunk Data Storage Layout

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/configuration

The directory structure under the configured SIRCHMUNK_WORK_PATH, containing cache, history, and configuration files.

```text
{SIRCHMUNK_WORK_PATH}/
  ├── .cache/
  │   ├── history/              # Chat session history (DuckDB)
  │   │   └── chat_history.db
  │   ├── knowledge/            # Knowledge clusters (Parquet)
  │   │   └── knowledge_clusters.parquet
  │   └── settings/             # User settings (DuckDB)
  │       └── settings.db
  ├── .env                      # Environment configuration
  └── mcp_config.json           # MCP server configuration
```

--------------------------------

### MCP Tool: sirchmunk_search

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Executes an intelligent search query across specified directories using different analysis modes.

```APIDOC
## sirchmunk_search

### Description
Executes an intelligent search query.

### Parameters
#### Request Body
- **query** (string) - Required - The search question
- **paths** (string[]) - Optional - Directories to search; falls back to SIRCHMUNK_SEARCH_PATHS or current working directory
- **mode** (string) - Optional - FAST (default), DEEP, or FILENAME_ONLY
```

--------------------------------

### Accessing Results

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

How to access and interpret the search results, both as a basic markdown string and as a detailed SearchContext object.

```APIDOC
## Accessing Results

### Basic Result

```python
# The result is a formatted markdown string
result = await searcher.search(query="...", paths=["..."])
print(result)
```

### With SearchContext

```python
# Get the full SearchContext object
result = await searcher.search(
    query="...",
    paths=["..."],
    return_context=True,
)

# Access context metadata
print(result.cluster_id)
print(result.confidence)
print(result.lifecycle_state)
print(result.evidence_units)
```
```

--------------------------------

### Search Parameters

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Details on the various parameters available for the `search` method, including query, paths, mode, and more.

```APIDOC
## Search Parameters

```python
result = await searcher.search(
    query="database connection pooling",        # Required: search question
    paths=["/path/to/project/src"],             # Optional: directories (env, then cwd)
    mode="FAST",                                # FAST (default), DEEP, or FILENAME_ONLY
    max_depth=10,                               # Max directory depth
    top_k_files=20,                             # Number of top files
    max_loops=10,                               # Max search loops
    include_patterns=["*.py", "*.java"],        # File patterns to include
    exclude_patterns=["*test*", "*__pycache__*"], # Patterns to exclude
    return_context=True,                        # Return full SearchContext
)
```
```

--------------------------------

### POST /api/v1/search/stream

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Performs a streaming search query and returns results as a server-sent event stream.

```APIDOC
## POST /api/v1/search/stream

### Description
This endpoint allows for performing search queries that return results in a streaming format, suitable for real-time updates.

### Method
POST

### Endpoint
/api/v1/search/stream

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **mode** (string) - Optional - The search mode (e.g., "FAST").

### Request Example
```json
{
  "query": "How does authentication work?",
  "mode": "FAST"
}
```

### Response
#### Success Response (200)
- **event-stream** (string) - Server-sent events containing search results.

#### Response Example
```
data: {"result": "Authentication is handled via JWT tokens."}

```
```

--------------------------------

### Stream Search Results with Python (httpx)

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

This Python script uses the httpx library to stream search results from the API. It handles the POST request, JSON payload, and iterates over the event stream, printing each line. Set timeout to None for potentially long-running streams.

```python
import httpx

url = "http://localhost:8584/api/v1/search/stream"
payload = {"query": "How does authentication work?", "mode": "FAST"}

with httpx.Client(timeout=None) as client:
    with client.stream(
        "POST",
        url,
        json=payload,
        headers={"Accept": "text/event-stream"},
    ) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if line:
                print(line)
```

--------------------------------

### Accessing SearchContext Metadata

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

Retrieve the full SearchContext object when `return_context` is set to True, and access its metadata like cluster ID, confidence, and evidence units.

```python
# Get the full SearchContext object
result = await searcher.search(
    query="...",
    paths=["..."],
    return_context=True,
)

# Access context metadata
print(result.cluster_id)
print(result.confidence)
print(result.lifecycle_state)
print(result.evidence_units)

```

--------------------------------

### LLM Usage Tracking

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/python-sdk

How to track and view the token usage for LLM calls made during the search process.

```APIDOC
### LLM Usage Tracking

```python
# After search completion
for usage in searcher.llm_usages:
    print(f"Prompt tokens: {usage.prompt_tokens}")
    print(f"Completion tokens: {usage.completion_tokens}")
    print(f"Total tokens: {usage.total_tokens}")
```
```

--------------------------------

### POST /api/v1/search

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Executes an intelligent search query and returns a JSON response once the search is complete.

```APIDOC
## POST /api/v1/search

### Description
Execute an intelligent search query. The handler returns JSON after the search finishes.

### Method
POST

### Endpoint
/api/v1/search

### Parameters
#### Request Body
- **query** (string) - Required - Natural-language search question.
- **paths** (string | string[]) - Optional - Root path(s) to search. If omitted, the server uses `SIRCHMUNK_SEARCH_PATHS` (if set), otherwise the process current working directory.
- **mode** (string) - Optional - Search mode, e.g. `FAST` (default), `DEEP`, `FILENAME_ONLY`.
- **max_depth** (int) - Optional - Maximum directory depth.
- **top_k_files** (int) - Optional - Cap on files considered.
- **enable_dir_scan** (bool) - Optional - Whether to scan directories for candidates; default `true`.
- **max_loops** (int) - Optional - **DEEP mode:** maximum agent / reasoning loops.
- **max_token_budget** (int) - Optional - **DEEP mode:** token budget for the run; default **128K** (131072).
- **include_patterns** (string[]) - Optional - Glob patterns to include.
- **exclude_patterns** (string[]) - Optional - Glob patterns to exclude.
- **return_context** (bool) - Optional - When true, include extra context in the response (replaces legacy `return_cluster`).

### Request Example
```json
{
  "query": "How does authentication work?",
  "mode": "FAST",
  "paths": ["/path/to/project"],
  "max_depth": 10,
  "top_k_files": 20,
  "enable_dir_scan": true,
  "max_loops": 8,
  "max_token_budget": 131072,
  "include_patterns": ["*.py", "*.java"],
  "exclude_patterns": ["*test*", "*__pycache__*"],
  "return_context": false
}
```

### Response
#### Success Response (200)
- **success** (bool) - Indicates if the search was successful.
- **data** (object) - Contains the search results.
  - **summary** (string) - Markdown-formatted search result.
  - **context** (any) - Additional context, can be null.

#### Response Example
```json
{
  "success": true,
  "data": {
    "summary": "Markdown-formatted search result...",
    "context": null
  }
}
```
```

--------------------------------

### Stream Search Results with cURL

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Use this cURL command to send a POST request to the search stream endpoint. Ensure the server is running locally on port 8584. The 'FAST' mode is used for quicker results.

```bash
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?","mode":"FAST"}'
```

--------------------------------

### Sirchmunk Knowledge Cluster Storage Path

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/i18n

Knowledge clusters are stored in Parquet format at this location. You can query them using DuckDB or the KnowledgeManager API.

```bash
{SIRCHMUNK_WORK_PATH}/.cache/knowledge/knowledge_clusters.parquet

```

--------------------------------

### Search API JavaScript Request

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Search request using the native fetch API.

```javascript
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) {
  console.log(data.data?.summary ?? data);
}
```

--------------------------------

### Tune Search Depth

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/customization

Adjust performance and iteration limits for search operations.

```javascript
result = await searcher.search(
    query="authentication flow",
    paths=["./src"],
    max_depth=5,           # Limit directory traversal
    top_k_files=10,        # Analyze fewer files for speed
    max_loops=5,           # Limit ReAct iterations (DEEP mode)
)
```

--------------------------------

### MCP Tool: sirchmunk_get_cluster

Source: https://modelscope.github.io/sirchmunk-web/docs/guide/mcp

Retrieves a specific knowledge cluster by its unique identifier.

```APIDOC
## sirchmunk_get_cluster

### Description
Retrieve a specific knowledge cluster by ID.

### Parameters
#### Request Body
- **cluster_id** (string) - Required - The cluster identifier
```

--------------------------------

### Filter Search Files

Source: https://modelscope.github.io/sirchmunk-web/docs/reference/customization

Use include and exclude patterns to restrict the search scope to specific file types or directories.

```javascript
result = await searcher.search(
    query="database queries",
    paths=["./src"],
    include_patterns=["*.py", "*.sql"],
    exclude_patterns=["*test*", "*migration*"],
)
```

--------------------------------

### Search API Python Request

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Synchronous search request using the requests library.

```python
import requests

response = requests.post(
    "http://localhost:8584/api/v1/search",
    json={
        "query": "How does authentication work?",
        "paths": ["/path/to/project"],
    },
    timeout=300
)

data = response.json()
if data.get("success"):
    print(data.get("data", {}).get("summary", data))
```

--------------------------------

### Search API Response

Source: https://modelscope.github.io/sirchmunk-web/docs/reference

Standard JSON response structure for a successful search request.

```json
{
  "success": true,
  "data": {
    "summary": "Markdown-formatted search result...",
    "context": null
  }
}
```
Tokens:
Raw