How agents use knowledge

Document version: 1.3 Status: Matches current backend (backend/internal/chatsvc/chat.go, helpdocs, skilldocs) Voice: For product, operations, and integrators — who, which situation, what outcome. Implementation names are in Implementation mapping at the end.

Related:

• Usage: Using the knowledge base
• 产品规格.md §3.2.1 (three layers of knowledge documents)
• 索引式文档与反馈闭环.md (two-layer index method)
• AI重建知识索引规则.md (AI index generation rules)
• help/README.md (maintaining the system knowledge tree)
• 智能体对话编排.md (how this round picks a theme, then reads the body)

1. Up front

Cadau does not dump the entire knowledge tree into the model. Each time the user sends a message, the backend first decides whether this turn needs knowledge retrieval (asking numbers / reports against a data connection usually skips it). The full app operation catalog is injected when the user is currently in that app, or is talking to the workspace app assistant in Messages. Asking numbers against a data connection — even if that database is also HR data — gets a short stub, not Cadau HR’s operation table, and does not expand from words like “employee / department / hired / HR”. When retrieval is needed:

1. Reads the knowledge base’s two-layer index (root and per-theme indexes written by Generate index with AI), picks a theme from this message, then a document, then opens the Markdown body;
2. Matches source archives (Word / PDF, and so on) against extracted text, and brings them into the conversation together with how-to articles;
3. Assembles passages with sources into the conversation; there is still a total length cap (about 6,000–8,000 characters);
4. Places the material in the user message or the system prompt (runtime material) depending on conversation type, then calls the model.

After you edit a how-to article, click Generate index with AI, or later conversations may still pick topics from the old catalog. After a source archive is ingested, extracted text can be hit by keywords; no vectors are generated.

Knowledge-base retrieval does not call an embedding model; rag.enable_vector is off by default. Query rewrite and BM25 weighting apply only when the matching switch is on.

2. Three layers of knowledge documents and who uses them

The same round may also include workspace skills (operation notes from conversation, stored in the database, not under knowledge/) and runtime memory excerpts (MEMORY.md and similar); see §5.

Versus the standards library: Government / industry laws and management policies that have versions and human review live in 规范库.md (product §3.2.2). In the implementation, when a workspace is selected, composeLLMRuntimeContext injects published and in-force standards fragments (workspaceStandardsBlock, matched by title / tags / document number). Do not inject pending drafts or unpublished versions into ordinary members’ Q&A. Workspace knowledge is still for wiki / FAQ; do not mix the two.

3. Fork: help assistant vs workspace agent

flowchart TD
  A[User sends POST /api/v1/chat] --> B{help_mode?}
  B -->|yes| C[Help path]
  B -->|no| D{user_agent_id present and workspace selected?}
  D -->|no| E[Usually no workspace/agent knowledge injected]
  D -->|yes| F[Workspace agent path]
  C --> C1[helpdocs.AssemblePrompt builds the user message]
  C1 --> C2[System role + help document passages + user question]
  F --> F1[composeLLMRuntimeContext builds runtime material]
  F1 --> F2[system prompt + history + user original]

3.1 Help assistant (help_mode: true)

• Front end: Sends only the user question; does not send the full knowledge tree.
• Back end: First retrieves help-document slices (helpdocs.AssemblePrompt); if the store is empty, falls back to helpdocs.BuildPrompt (segment after a two-level index hit). Passages, fixed notes, and action-link templates replace this round’s user-side content sent to the model, truncated to about 8,000 characters.
• Failure: If the index or files cannot be read, the API returns “Help documents are not ready” (help_docs_unavailable).

The help assistant does not also inject workspace knowledge or agent knowledge (composeLLMRuntimeContext skips knowledge blocks in help_mode).

3.2 User agent in a workspace (help_mode: false and user_agent_id present)

• User message: Keeps the user’s original text (attachments and similar are out of scope here).
• System prompt: Assembled by buildAgentToolSystemPrompt / prepareLLMConversationWithRollingContext. Runtime material comes from agentRuntimeContext → composeLLMRuntimeContext:

1. Workspace knowledge (if workspace_id is present) 2. Agent knowledge (if user_agent_id is present) 3. Workspace skills (skills from conversation, matched to the question; see chat_workspace_skills.go) 4. Recent conversation memory excerpt (tail of runtime MEMORY, at most about 2,000 characters)

Priority (written in the system prompt): If workspace knowledge and agent knowledge conflict, explicit overrides in agent knowledge win; otherwise workspace knowledge wins; if neither covers it, say you do not know.

3.3 Special case: built-in system agents (is_system)

If the request does not set help_mode, but the current agent is built-in (user_agents.is_system) and a workspace is selected, injectHelpDocsForChat is true and the user message uses the same helpdocs.BuildPrompt as the help assistant (the system knowledge tree). Typical scene: the help entry with no workspace selected; product routing is authoritative.

4. Two-layer index retrieval (shared by workspace / agent / system knowledge)

Implementation packages: skilldocs (workspace and agent knowledge), helpdocs (system knowledge, same logic).

4.1 Directory convention

knowledge-root/
  index.json          ← first layer: themes + documents at the root
  a-theme/
    index.json        ← second layer: documents under that theme
    a-how-to.md

4.2 Retrieval steps (once per user question)

1. Read the root index.json.
2. First layer: Score themes[] title / summary / tags with words from the question; take the top 2 themes; if none hit, fall back to the first 2 themes.
3. Second layer: For each hit theme, read {dir}/index.json, score documents[], at most 2 articles per theme (on workspace/agent paths BuildContext(..., top=3) also caps the total article count; see below).
4. Take passages: After the index picks articles, open the Markdown body. Source archives separately match keywords on extracted text. Segmentation: if the whole article is under about 5,000 characters, treat it as one passage (good for “one table, one data dictionary”); longer articles merge by heading to about 1,200 characters then split, avoiding cuts in the middle of a table.
5. Truncate:

- Workspace knowledge block cap about 6,000 characters (runes); - Agent / help knowledge block cap about 8,000 characters (runes); - If over the cap, the tail is marked “excerpt truncated”.

By default only current effect is searched; questions about before / old notices / archive include archived items. The knowledge base does not generate or use vectors; how-to articles pick topics via the two-layer index, source archives via extracted text. When the user is looking up past conversation text (what was discussed recently, which words were asked), skip knowledge-document retrieval so unrelated policy text is not stuffed into the prompt.

Titles / summaries / tags in index.json still help pick articles and boost scores; paths conditional loading still applies.

4.2.1 Optional conditional load (paths)

documents[] / themes[] may include an optional paths string array (globs, e.g. ["**/*.tsx"]):

• Empty: Same as before — participate in matching by question keywords.
• Filled: The entry is a candidate only if a path fragment in the user message or an attachment filename matches one glob; with no path context it is not injected, so long “front-end only” docs do not spend tokens.
• Maintenance: When generating the index with AI, the model may suggest paths; admins may edit index.json by hand. User notes: help/admin-ops/system-knowledge-index.md, help/knowledge-layers/three-layers.md.

4.3 Versus workspace skills and the Skills center

Skill logic contract and trigger notes: 技能组成规范.md.

5. Full context structure for one conversation (workspace agent)

┌─────────────────────────────────────────┐
│ system (single message)                 │
│  - Fixed notes: role, tools, honesty, probing │
│  - 【Workspace knowledge…】              │
│  - 【Agent knowledge base…】             │
│  - 【Skill notes related to this workspace】 │
│  - 【Recent conversation memory excerpt】│
├─────────────────────────────────────────┤
│ History user / assistant (rolling summary keeps size in check) │
├─────────────────────────────────────────┤
│ user: this round’s original text         │
└─────────────────────────────────────────┘

Streaming and non-streaming APIs (POST /chat, POST /chat/stream) share this assembly.

When HTTP tools are on (AGENT_HTTP_TOOL_ENABLED and not help mode), system still carries runtime material; the model may call http_request across rounds, together with knowledge passages.

6. What maintainers do

1. Write Markdown: Put steps and edge cases in the body; the index only has searchable titles, summaries, and tags.
2. Generate the index: After adding a theme folder or changing many titles, run Rebuild index with AI at the matching maintenance entry (rules: AI重建知识索引规则.md). Only on rules tied to file type/path, add paths on index entries (conditional load, §4.2.1).
3. System knowledge: Admin console → System knowledge documents (help/); workspace knowledge: Workspace collaboration; agent knowledge: My agents → knowledge documents.
4. Verify: Ask in natural language close to the document tags and check that the answer cites the right passages; for help, test with no workspace selected.

7. Implementation mapping

8. Later evolution (not implemented, or config-only)

• RAG_ENABLE_VECTOR, RAG_ENABLE_BM25, and similar: config keys exist; they do not currently participate in §4 file-level index injection.
• Block-level vectors and query rewrite: if they land, treat them as an enhancement layer that does not break the existing two-layer index.json and path contract (see AI重建知识索引规则.md mechanism goals).