# modelscope/sirchmunk architecture

> Architecture diagram of the GitHub repository modelscope/sirchmunk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelscope/sirchmunk
- Repository: https://github.com/modelscope/sirchmunk

## Overview

Sirchmunk is an embedding-free, agentic search and evolving-knowledge product for local files and web sources. The main workflow is to submit a query through an API, MCP tool, or web interface; search raw data; and return an answer with evidence. Knowledge clusters capture and persist reusable knowledge, while the learning modules support evolution. The tree and excerpts establish the service-to-searcher MCP path and storage roles; detailed wiring among retrieval, reasoning, and learning modules was not sampled, so those links are omitted.

Main entry points: [`src/sirchmunk/search.py`](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/search.py) (Agentic search), [`web/app/page.tsx`](https://github.com/modelscope/sirchmunk/blob/main/web/app/page.tsx) (Web UI), [`src/sirchmunk/api/main.py`](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/main.py) (FastAPI app), [`src/sirchmunk_mcp/server.py`](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk_mcp/server.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web UI<br/>[page.tsx]"]
  node_api["FastAPI app<br/>[main.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcpservice["MCP service<br/>[service.py]"]
end

subgraph group_search["Search and answers"]
  node_agenticsearch["Agentic search<br/>[search.py]"]
  node_queryintelligence["Query analysis"]
  node_retrieval["Raw retrieval<br/>[text_retriever.py]"]
  node_scanning["Source scanning"]
  node_agent["Search agent<br/>[react_agent.py]"]
  node_answer["Answer policy<br/>[answer_policy.py]"]
  node_renderer["Search renderer<br/>[search_response.py]"]
end

subgraph group_knowledge["Knowledge evolution"]
  node_learning["Learning modules"]
end

subgraph group_state["Persistent state"]
  node_clusters[("Knowledge clusters")]
  node_history[("Chat history<br/>[history_storage.py]")]
  node_files[("Uploaded files<br/>[file_service.py]")]
end

subgraph group_integrations["External integrations"]
  node_openai["OpenAI-compatible LLM<br/>[openai_chat.py]"]
  node_corpus[("Local and web sources")]
end

node_user(("User"))
node_mcpclient(("MCP client"))

node_user -->|"asks"| node_web
node_web -->|"sends requests"| node_api
node_user -->|"submits queries"| node_api
node_mcpclient -->|"invokes tools"| node_mcp
node_mcp -->|"dispatches"| node_mcpservice
node_mcpservice -->|"calls search"| node_agenticsearch
node_agenticsearch -->|"reads and writes"| node_clusters
node_agenticsearch -->|"retrieves text"| node_retrieval
node_agenticsearch -->|"scans sources"| node_scanning
node_agenticsearch -->|"analyzes queries"| node_queryintelligence
node_agenticsearch -->|"coordinates reasoning"| node_agent
node_agenticsearch -->|"applies policy"| node_answer
node_agenticsearch -->|"formats results"| node_renderer
node_agenticsearch -.->|"uses LLM"| node_openai
node_retrieval -->|"searches raw data"| node_corpus
node_scanning -->|"reads sources"| node_corpus
node_learning -->|"evolves knowledge"| node_clusters
node_web -->|"stores conversations"| node_history
node_api -->|"manages uploads"| node_files

click node_web "https://github.com/modelscope/sirchmunk/blob/main/web/app/page.tsx"
click node_api "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/main.py"
click node_mcp "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk_mcp/server.py"
click node_mcpservice "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk_mcp/service.py"
click node_agenticsearch "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/search.py"
click node_queryintelligence "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/schema/query_intelligence.py"
click node_retrieval "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/retrieve/text_retriever.py"
click node_scanning "https://github.com/modelscope/sirchmunk/tree/main/src/sirchmunk/scan"
click node_agent "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/agentic/react_agent.py"
click node_answer "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/answer_policy.py"
click node_renderer "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/renderers/search_response.py"
click node_learning "https://github.com/modelscope/sirchmunk/tree/main/src/sirchmunk/learnings"
click node_clusters "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/storage/knowledge_storage.py"
click node_history "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/components/history_storage.py"
click node_files "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/file_service.py"
click node_openai "https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/llm/openai_chat.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_api,node_mcp,node_mcpservice,node_user,node_mcpclient toneBlue
class node_agenticsearch,node_queryintelligence,node_retrieval,node_scanning,node_agent,node_answer,node_renderer toneAmber
class node_learning toneMint
class node_clusters,node_history,node_files toneRose
class node_openai,node_corpus toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/modelscope/sirchmunk/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [FastAPI app](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/main.py): `src/sirchmunk/api/main.py`
- [MCP server](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk_mcp/server.py): `src/sirchmunk_mcp/server.py`
- [MCP service](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk_mcp/service.py): `src/sirchmunk_mcp/service.py`

### Search and answers

- [Agentic search](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/search.py): `src/sirchmunk/search.py`
- [Query analysis](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/schema/query_intelligence.py): `src/sirchmunk/schema/query_intelligence.py`
- [Raw retrieval](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/retrieve/text_retriever.py): `src/sirchmunk/retrieve/text_retriever.py`
- [Source scanning](https://github.com/modelscope/sirchmunk/tree/main/src/sirchmunk/scan): `src/sirchmunk/scan`
- [Search agent](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/agentic/react_agent.py): `src/sirchmunk/agentic/react_agent.py`
- [Answer policy](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/answer_policy.py): `src/sirchmunk/answer_policy.py`
- [Search renderer](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/renderers/search_response.py): `src/sirchmunk/renderers/search_response.py`

### Knowledge evolution

- [Learning modules](https://github.com/modelscope/sirchmunk/tree/main/src/sirchmunk/learnings): `src/sirchmunk/learnings`

### Persistent state

- [Knowledge clusters](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/storage/knowledge_storage.py): `src/sirchmunk/storage/knowledge_storage.py`
- [Chat history](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/components/history_storage.py): `src/sirchmunk/api/components/history_storage.py`
- [Uploaded files](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/api/file_service.py): `src/sirchmunk/api/file_service.py`

### External integrations

- [OpenAI-compatible LLM](https://github.com/modelscope/sirchmunk/blob/main/src/sirchmunk/llm/openai_chat.py): `src/sirchmunk/llm/openai_chat.py`
- **Local and web sources**

### Other components

- **User**
- **MCP client**

## Connections

- User → Web UI: asks
- Web UI → FastAPI app: sends requests
- User → FastAPI app: submits queries
- MCP client → MCP server: invokes tools
- MCP server → MCP service: dispatches
- MCP service → Agentic search: calls search
- Agentic search → Knowledge clusters: reads and writes
- Agentic search → Raw retrieval: retrieves text
- Agentic search → Source scanning: scans sources
- Agentic search → Query analysis: analyzes queries
- Agentic search → Search agent: coordinates reasoning
- Agentic search → Answer policy: applies policy
- Agentic search → Search renderer: formats results
- Agentic search → OpenAI-compatible LLM: uses LLM
- Raw retrieval → Local and web sources: searches raw data
- Source scanning → Local and web sources: reads sources
- Learning modules → Knowledge clusters: evolves knowledge
- Web UI → Chat history: stores conversations
- FastAPI app → Uploaded files: manages uploads