CherryHQ-cherry-studio/docs/references/knowledge/experiment/knowledge-product-spec.md

Cherry Studio Knowledge Base — Product Spec

1. Positioning

A knowledge base is a "managed library of materials that an agent can manage." It moves away from "configure retrieval models first, then upload (RAG)" toward a material space where you "drop materials in, search works by default, and embedding / rerank / file processors make it stronger as you configure them". It is a managed library: every material runs a tracked lifecycle (import → process → embed → fail / retry → delete) that the UI reflects from business state (knowledge_item), not from a live filesystem listing. User-facing copy always says "knowledge base"; internal concepts like File Mode are never exposed.

2. Product principles (four)

1. Low creation barrier — a name is enough to create a base; no vector/RAG knowledge required. (A base created without an embedding model is now supported — it is BM25-only full-text search; an embedding model can be added later from the base settings to enable vector/hybrid retrieval.)
2. Import means copy — uploading creates the base's own stable copy/snapshot; later changes to the external source never rewrite the base's content automatically.
3. Business state is the user-visible truth — the UI reflects each material's tracked lifecycle status from knowledge_item, never a live filesystem read; the per-base folder is internal, Cherry-managed byte storage the user never browses directly. Index/chunk/cache system assets never appear among the materials.
4. The agent is a helper, not unbounded automation — low-risk tidying executes then reports; refresh-overwrite, delete, and overwriting existing files require confirmation.

3. Material behavior at a glance

Material	Core rules
Local file / folder	Copied into the base (one-shot copy), name kept, hierarchy kept; the imported original is never tracked afterward — its later edits or deletion never affect the base copy; deleting the in-base copy never touches the original
URL	A snapshot (fetched as Markdown), not a live reference; refresh = re-fetch and overwrite (confirmation required)
Note	Copied as the base's own snapshot, default name from the source; no auto-sync, refresh-overwrite needs confirmation
PDF processor output	The generated Markdown is an independent, visible file; search indexes/returns the Markdown; deleting the PDF keeps the md (target state / v2.x — in current v2 the md is not a separate item, only the PDF item's indexedRelativePath; deleting the PDF item deletes both md and PDF)
Agent-created material	Writing into the base directory makes an ordinary visible material — no hidden output pool; the user can edit freely

Same-path conflicts offer three choices (overwrite / keep copy _1 / skip); keep-copy auto-renames with a _N suffix and is landed (live upload + v1 migration), while overwrite / skip are still target state. Duplicate content is not blocked (the agent tidies it later).

4. Agent capability boundaries

• list shows all knowledge bases visible to the current user; search must receive an explicit base id and is not limited to candidates; read takes the locator a search returned (never an arbitrary file path); tree is bounded by visibility; manage (add/delete/refresh) requires confirmation for destructive operations.
• Candidate ids are hints, not a permission boundary — agent binding / chat @-mention / detail-page entry only decide the candidates; a single user owns all of their local bases, candidates merely narrow this conversation's search scope, and once personal cloud sources (Feishu / WebDAV) are connected, readability of a given material is additionally bounded by that cloud account's own visibility.

5. Settled product decisions

#	Rule
1	A name alone creates a base
2	User-facing name stays "knowledge base"
3	Internal objects are uniformly Knowledge Material
4	File-manager-style main view (list/grid, no fixed raw/processed tabs)
5	Uploads copy without renaming; folders keep their hierarchy
6	URLs are fetched as Markdown; refresh overwrites and updates the index
7	Cloud documents are stored as local snapshots with manual refresh (later capability)
8	PDF-generated Markdown is an independent visible file; search returns the Markdown; deleting the PDF keeps the md (target state / v2.x — current v2: md is not a separate item, deleting the PDF deletes both)
9	Agent writes go through the create-material API (not a raw file drop into the folder), then are immediately visible
10	Same-path conflicts offer three choices, copies use _1/_2 suffixes (keep-copy / auto-rename _N landed for both live upload and v1 migration; overwrite / skip still target state)
11	Duplicate content is not blocked
12	Imported originals are not tracked — their external edits/deletion never change the base; a base copy is removed only by an explicit in-app delete (missing is a lazy read-time flag, not a watcher signal)
13	list shows all visible bases; search requires an id but is not candidate-limited; candidates ≠ permission boundary
14	Legacy base migration builds a new copy — no in-place conversion, no automatic rewrite of agent bindings; unprovable parts are skipped with diagnostics recorded, never guessed

6. Hard-to-roll-back decisions

1. New knowledge bases default to the folder-backed storage model; 2. the UI is driven by knowledge_item business state, not a live directory read; 3. processor-output Markdown is a visible independent file; 4. candidate bases are not a search allowlist; 5. migration creates a new copy, not an in-place conversion.