update knowledge evolving

content/blog/technical-deep-dive/index.md

@@ -281,6 +281,21 @@ The Web UI now includes an **interactive Knowledge Graph visualization** powered
 
 > **Design insight:** By modeling knowledge with lifecycle states and abstraction levels, Sirchmunk treats its knowledge base as a living organism rather than a dead archive. Knowledge can be born, grow, and eventually retire — mirroring how human expertise evolves.
 
+### The Knowledge Evolver
+
+![Knowledge Evolver Architecture](Knowledge_Evolver_Architecture.png "Fig. 3 — KnowledgeEvolver: four-phase background evolution cycle for knowledge graph maintenance.")
+
+While individual clusters evolve through query-driven reuse, the knowledge graph as a whole is maintained by the `KnowledgeEvolver` — a background orchestrator that runs a four-phase cycle:
+
+1. **Connect & Merge**: When new clusters accumulate in the buffer, pairwise similarity is computed. Clusters with similarity ≥ 0.90 are merged; those with similarity ≥ 0.60 gain inter-cluster edges. This consolidates fragmented knowledge from related queries.
+2. **Refresh Edges**: Existing edges are re-evaluated. Stale or weak connections are pruned, and edge weights are updated based on recent co-query patterns and semantic drift.
+3. **Detect Meta Clusters**: Leiden community detection (via igraph) discovers higher-order structure — groups of clusters that form coherent knowledge communities. These meta-clusters represent emergent domain expertise that no single query could have produced.
+4. **Global Update**: Lifecycle states are synchronized across the graph. Consistently reinforced clusters graduate from Emerging to Stable; orphaned or contradicted clusters move toward Deprecated.
+
+The entire cycle runs asynchronously, triggered by search activity (buffer counts and step intervals), and never blocks the query hot path. Results persist to DuckDB + Parquet with an incremental manifest for crash recovery.
+
+> See the [Knowledge Evolution showcase](/showcase/knowledge-graph/) for a time-lapse video demonstrating clusters evolving across 200 queries.
+
 ## 9. Storage & Persistence Philosophy
 
 Sirchmunk's storage design follows a principle we call **"fast by default, durable when it matters."** The system operates entirely in-memory during runtime for maximum speed, while a background process transparently synchronizes state to disk for durability.

content/blog/technical-deep-dive/index.zh.md

@@ -281,6 +281,21 @@ Web UI 现已包含基于 Cytoscape.js 的**交互式知识图谱可视化**。
 
 > **设计洞察：** 通过使用生命周期状态和抽象级别建模知识，Sirchmunk 将其知识库视为一个活的有机体而非死的档案。知识可以诞生、成长并最终退休 — 映射人类专业知识的演进方式。
 
+### 知识进化器
+
+![知识进化器架构](Knowledge_Evolver_Architecture.png "图 3 — KnowledgeEvolver：知识图谱维护的四阶段后台进化周期")
+
+单个知识簇通过查询驱动的复用不断演化，而整个知识图谱则由 `KnowledgeEvolver` 维护——一个在后台运行四阶段周期的编排器：
+
+1. **连接与合并**：当新知识簇在缓冲区中累积，计算两两相似度。相似度 ≥ 0.90 的被合并；相似度 ≥ 0.60 的建立跨聚类边。这将相关查询的碎片化知识整合为连贯单元。
+2. **边刷新**：重新评估已有边。剪除陈旧或弱连接，根据近期共查询模式和语义漂移更新边权重。
+3. **元聚类发现**：Leiden 社区发现算法（通过 igraph 实现）识别更高阶结构——形成连贯知识社区的聚类群组。这些元聚类代表了单个查询无法独立产生的涌现式领域专长。
+4. **全局更新**：在整个图谱中同步生命周期状态。持续被强化的知识簇从"萍芽"晋升为"稳定"；孤立或被反驳的向"弃用"迁移。
+
+整个周期由搜索活动触发（缓冲计数和步长间隔），异步运行，绝不阻塞查询热路径。结果持久化至 DuckDB + Parquet，通过增量清单实现崩溃恢复。
+
+> 参见[知识进化展示](/zh/showcase/knowledge-graph/)，观看知识聚类在 200 次查询中演化的延时视频。
+
 ## 9. 存储与持久化哲学
 
 Sirchmunk 的存储设计遵循我们称之为**"默认快速，重要时持久"**的原则。系统在运行时完全在内存中操作以获得最高速度，同时后台进程透明地将状态同步到磁盘以确保持久性。

content/blog/v0.2.0/index.md

@@ -69,6 +69,12 @@ Every replacement behavior is gated behind an environment switch, defaults to th
 
 The Web UI now includes an **interactive knowledge graph** powered by Cytoscape.js. The graph visualizes self-evolving knowledge clusters and their semantic relationships, including lifecycle states (Emerging, Stable, Meta) and edge weights. Users can explore, filter, and drill down into the cluster topology to understand how the system's knowledge evolves with use.
 
+Behind the visualization, the `KnowledgeEvolver` orchestrates a four-phase background evolution cycle — Connect & Merge, Refresh Edges, Detect Meta Clusters (via Leiden community detection), and Global Update — that continuously maintains and consolidates the knowledge graph without blocking queries.
+
+![Knowledge Evolver Architecture](Knowledge_Evolver_Architecture.png "KnowledgeEvolver — Four-phase evolution cycle for knowledge graph maintenance")
+
+The design philosophy is observation-driven: evolution is triggered by actual search patterns rather than pre-defined rules, and source fidelity is always preserved — the system changes how it navigates to evidence, never the evidence itself. For a full animated demonstration, see the [Knowledge Evolution showcase](/showcase/knowledge-graph/).
+
 ## Other Improvements
 
 - **Broader format coverage**: Native exact-match fallback for LOG, PPTX, and XLSX files, plus heuristic document tree v2 (including DOCX/RST) with structure anchors guiding evidence extraction.

content/blog/v0.2.0/index.zh.md

@@ -69,6 +69,12 @@ v0.2.0 对基准特定硬规则采取了原则性立场。硬编码的实体模
 
 Web UI 新增基于 Cytoscape.js 的**交互式知识图谱**。图谱可视化自进化知识聚类及其语义关系，包括生命周期状态（Emerging、Stable、Meta）和边权重。用户可以探索、过滤和深入聚类拓扑，直观了解系统知识随使用的演化过程。
 
+可视化背后，`KnowledgeEvolver` 编排了四阶段后台进化周期——连接与合并、边刷新、元聚类发现（基于 Leiden 社区发现算法）和全局更新——持续维护和整合知识图谱，且不阻塞查询。
+
+![知识进化器架构](Knowledge_Evolver_Architecture.png "KnowledgeEvolver — 知识图谱维护的四阶段进化周期")
+
+设计理念是观测驱动的：进化由实际搜索模式触发，而非预定义规则；源头保真始终被保护——系统改变的是寻找证据的导航路径，而非证据本身。完整动画演示请参见[知识进化展示](/zh/showcase/knowledge-graph/)。
+
 ## 其他改进
 
 - **更广格式覆盖**：LOG、PPTX、XLSX 文件原生精确匹配回退，启发式文档树 v2（含 DOCX/RST）并以结构锚点引导证据抽取。

content/docs/guide/architecture.md

@@ -35,6 +35,8 @@ The **Knowledge Graph** provides an interactive visualization of self-evolving k
 
 Users can explore, filter, and drill into clusters directly from the Web UI.
 
+See the [Knowledge Evolution showcase](/showcase/knowledge-graph/) for an animated demonstration of how clusters evolve over time.
+
 ## Core Components
 
 | Component             | Description                                                              |
@@ -190,6 +192,19 @@ A KnowledgeCluster is a richly annotated object that captures the full cognitive
 - **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.
 
+#### Knowledge Evolver
+
+![Knowledge Evolver Architecture](Knowledge_Evolver_Architecture.png "KnowledgeEvolver — Four-phase evolution cycle")
+
+Beyond per-query cluster creation and reuse, the `KnowledgeEvolver` runs a four-phase background cycle that maintains the knowledge graph as a whole:
+
+1. **Connect & Merge** — Computes pairwise similarity among buffered clusters. Clusters with similarity ≥ 0.90 are merged; those with similarity ≥ 0.60 gain inter-cluster edges, consolidating fragmented knowledge from related queries.
+2. **Refresh Edges** — Re-evaluates existing edges, pruning stale connections and updating weights based on recent co-query patterns and semantic drift.
+3. **Detect Meta Clusters** — Leiden community detection (via igraph) discovers higher-order structure — groups of clusters that form coherent knowledge communities representing emergent domain expertise.
+4. **Global Update** — Synchronizes lifecycle states across the graph: consistently reinforced clusters graduate from Emerging to Stable; orphaned or contradicted clusters move toward Deprecated.
+
+The entire cycle runs asynchronously, triggered by search activity (buffer counts and step intervals). Results persist to DuckDB + Parquet with an incremental manifest for crash recovery. The evolver never blocks the query hot path.
+
 ## Data Storage
 
 All persistent data is stored in the configured `SIRCHMUNK_WORK_PATH` (default: `~/.sirchmunk/`):

content/docs/guide/architecture.zh.md

@@ -35,6 +35,8 @@ Sirchmunk 采用清晰分离的层次化架构，遵循**关注点分离**原则
 
 用户可以直接在 Web UI 中探索、筛选和深入查看知识簇。
 
+参见[知识进化展示](/zh/showcase/knowledge-graph/)，了解知识聚类如何随时间演化的动画演示。
+
 ## 核心组件
 
 | 组件                    | 说明                                                                   |
@@ -190,6 +192,19 @@ KnowledgeCluster 是一个丰富标注的对象，完整记录了单次搜索周
 - **语义拓展：** 随着多样化查询复用同一知识簇，其嵌入会漂移以覆盖更广的语义邻域，自然提升相关未来查询的召回率。
 - **轻量级持久化：** DuckDB 内存存储 + Parquet 磁盘持久化——无需外部数据库基础设施。后台守护线程同步，可配置刷写间隔，开销极小。
 
+#### 知识进化器
+
+![知识进化器架构](Knowledge_Evolver_Architecture.png "KnowledgeEvolver — 四阶段进化周期")
+
+除了每次查询的知识簇创建和复用之外，`KnowledgeEvolver` 还会在后台运行四阶段周期，对整个知识图谱进行维护：
+
+1. **连接与合并** — 计算缓冲区中知识簇的两两相似度。相似度 ≥ 0.90 的知识簇被合并；相似度 ≥ 0.60 的建立跨聚类边，将相关查询的碎片化知识整合为一体。
+2. **边刷新** — 重新评估已有边，剪除陈旧连接，根据近期共查询模式和语义漂移更新权重。
+3. **元聚类发现** — Leiden 社区发现算法（通过 igraph 实现）识别更高阶结构——形成连贯知识社区的聚类群组，代表涌现式领域专长。
+4. **全局更新** — 在整个图谱中同步生命周期状态：持续被强化的知识簇从"萍芽"晋升为"稳定"；孤立或被反驳的向"弃用"迁移。
+
+整个周期由搜索活动触发（缓冲计数和步长间隔），异步运行。结果持久化至 DuckDB + Parquet，通过增量清单实现崩溃恢复。进化器绝不阻塞查询热路径。
+
 ## 数据存储
 
 所有持久化数据存储在配置的 `SIRCHMUNK_WORK_PATH`（默认：`~/.sirchmunk/`）：

content/showcase/knowledge-graph/index.md

@@ -7,8 +7,62 @@ image:
   caption: "Sirchmunk Knowledge Graph"
 ---
 
-Sirchmunk's Web UI includes an interactive knowledge graph that visualizes the self-evolving knowledge clusters built incrementally from search interactions. Powered by [Cytoscape.js](https://js.cytoscape.org/), the graph presents semantic relationships between clusters and their lifecycle states — from **Emerging** to **Stable** — giving you a live view of how the system's intelligence grows over time.
+Sirchmunk's knowledge system is not static — it evolves. Every search interaction produces reusable knowledge clusters that merge, broaden, and form meta-communities over time. This page showcases the self-evolving knowledge architecture and its interactive visualization.
 
-Knowledge clusters are persisted in **DuckDB + Parquet** and evolve through a four-phase runtime cycle: connect & merge, edge refresh, meta-cluster discovery (via the Leiden community detection algorithm), and global recalibration. The graph UI lets you explore these communities interactively, filter by lifecycle stage, and trace how queries contribute to cluster formation.
+## Knowledge Graph Visualization
 
 ![Sirchmunk Knowledge Graph](Sirchmunk_Knowledge_Graph.png "Knowledge Graph — Interactive visualization of knowledge clusters with lifecycle stages")
+
+Powered by [Cytoscape.js](https://js.cytoscape.org/), the Web UI's Knowledge Graph page renders clusters as nodes, similarity edges and co-query edges as links, with lifecycle states color-coded:
+
+- **Emerging** — Newly formed clusters with limited validation
+- **Stable** — Clusters consistently reinforced across multiple queries
+- **Meta** — Higher-order communities discovered through community detection
+- **Deprecated** — Clusters whose underlying evidence is no longer supported
+- **Contested** — Clusters with conflicting or contradictory evidence
+
+Users can explore cluster details, trace evidence back to source documents, and observe how the knowledge topology evolves across search sessions.
+
+## Knowledge Evolver Architecture
+
+![Knowledge Evolver Architecture](Knowledge_Evolver_Architecture.png "KnowledgeEvolver — Four-phase evolution cycle for knowledge graph maintenance")
+
+The `KnowledgeEvolver` orchestrates a four-phase evolution cycle that runs asynchronously in the background, triggered by search activity:
+
+### Phase 1 — Connect & Merge
+
+When new clusters accumulate in the buffer, the evolver computes pairwise similarity. Clusters with similarity ≥ 0.90 are merged; those with similarity ≥ 0.60 gain inter-cluster edges. This consolidates fragmented knowledge from related queries into coherent units.
+
+### Phase 2 — Refresh Edges
+
+Existing edges are re-evaluated. Stale or weak connections are pruned, and edge weights are updated based on recent co-query patterns and semantic drift. This keeps the graph topology aligned with actual usage patterns rather than historical artifacts.
+
+### Phase 3 — Detect Meta Clusters
+
+Leiden community detection (via igraph) discovers higher-order structure — groups of clusters that form coherent knowledge communities. These meta-clusters represent emergent domain expertise that no single query could have produced.
+
+### Phase 4 — Global Update
+
+Lifecycle states are synchronized across the graph. Clusters that have been consistently reinforced graduate from Emerging to Stable; orphaned or contradicted clusters move toward Deprecated. Version numbers and timestamps are updated to maintain audit trails.
+
+The entire cycle runs under budget constraints (LLM concurrency semaphore, buffer thresholds) and never blocks the query hot path. Results persist to DuckDB + Parquet with an incremental manifest for crash recovery.
+
+## Knowledge Evolution in Action
+
+<video controls width="100%" poster="Sirchmunk_Knowledge_Graph.png">
+  <source src="knowledge_evolving.mp4" type="video/mp4">
+</video>
+
+This time-lapse replay demonstrates knowledge clusters evolving across 200 queries over 4 documents. Watch as isolated clusters emerge, connect through shared evidence, merge into consolidated knowledge units, and eventually form meta-communities — all without manual curation.
+
+## Design Principles
+
+- **Observation-driven, not rule-driven**: Evolution is triggered by actual search patterns, not pre-defined rules. The system learns what knowledge is worth preserving by observing which clusters get reused.
+- **Source fidelity preserved**: Knowledge evolution changes navigation efficiency — the paths the system takes to find evidence — but never alters the source documents. Every fact remains traceable to its original location.
+- **Bounded cost**: Evolution runs under budget constraints (LLM concurrency semaphore, buffer thresholds). It never blocks the query hot path.
+
+## Usage
+
+Knowledge evolution is enabled by default. You can configure it via environment variables or the SDK parameter `enable_knowledge_evolution`.
+
+The Knowledge Graph is accessible from the Web UI sidebar navigation under **"Knowledge"**. Clusters and their relationships can also be queried programmatically through the Python SDK.