@swarmclawai/swarmclaw 1.3.4 → 1.3.5

package/src/components/memory/memory-card.tsx

@@ -19,6 +19,8 @@ export function MemoryCard({ entry, active, agentName, agentAvatarSeed, agentAva
   const [now] = useState(() => Date.now())
   const scope = deriveMemoryScope(entry)
   const tier = getMemoryTier(entry)
+  const isDreamOrigin = entry.category === 'dream_reflection'
+    || (entry.metadata as Record<string, unknown> | undefined)?.origin === 'dream'
 
   return (
     <div
@@ -36,6 +38,11 @@ export function MemoryCard({ entry, active, agentName, agentAvatarSeed, agentAva
         <span className="shrink-0 text-[9px] font-700 uppercase tracking-wider text-accent-bright/70 bg-accent-soft px-1.5 py-0.5 rounded-[5px]">
           {entry.category || 'note'}
         </span>
+        {isDreamOrigin && (
+          <span className="shrink-0 text-[9px] font-700 uppercase tracking-wider text-violet-300/70 bg-violet-400/10 px-1.5 py-0.5 rounded-[5px]">
+            dream
+          </span>
+        )}
         {entry.pinned && (
           <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" className="shrink-0 text-amber-400/80">
             <path d="M16 2l-4 4-4-4-2 2 4 4-5 5v1h1l5-5 4 4 2-2-4-4 4-4z" transform="rotate(45 12 12)" />

package/src/components/memory/memory-detail.tsx

@@ -175,6 +175,19 @@ export function MemoryDetail() {
   const inputClass = "w-full px-4 py-3 rounded-[12px] border border-white/[0.06] bg-white/[0.02] text-text outline-none transition-all duration-200 placeholder:text-text-3/70 focus:border-accent-bright/20 focus:bg-white/[0.03]"
   const refs = entry.references || []
   const showRefsCollapse = refs.length > 3
+  const entryMeta = entry.metadata && typeof entry.metadata === 'object'
+    ? entry.metadata as Record<string, unknown>
+    : {}
+  const knowledgeSourceId = typeof entryMeta.sourceId === 'string' ? entryMeta.sourceId : null
+  const knowledgeSourceTitle = typeof entryMeta.sourceTitle === 'string' ? entryMeta.sourceTitle : null
+  const knowledgeSourceKind = typeof entryMeta.sourceKind === 'string' ? entryMeta.sourceKind : null
+  const knowledgeSourceLabel = typeof entryMeta.sourceLabel === 'string' ? entryMeta.sourceLabel : null
+  const knowledgeSourceUrl = typeof entryMeta.sourceUrl === 'string' ? entryMeta.sourceUrl : null
+  const knowledgeChunkIndex = typeof entryMeta.chunkIndex === 'number' ? entryMeta.chunkIndex : null
+  const knowledgeChunkCount = typeof entryMeta.chunkCount === 'number' ? entryMeta.chunkCount : null
+  const knowledgeSectionLabel = typeof entryMeta.sectionLabel === 'string' ? entryMeta.sectionLabel : null
+  const knowledgeCharStart = typeof entryMeta.charStart === 'number' ? entryMeta.charStart : null
+  const knowledgeCharEnd = typeof entryMeta.charEnd === 'number' ? entryMeta.charEnd : null
 
   return (
     <div className="flex-1 flex flex-col h-full min-h-0">
@@ -438,6 +451,33 @@ export function MemoryDetail() {
                 {entry.content || '(empty)'}
               </div>
 
+              {knowledgeSourceId && (
+                <div className="rounded-[14px] border border-white/[0.06] bg-white/[0.02] px-4 py-3">
+                  <label className="block text-[11px] font-600 text-text-3/60 uppercase tracking-[0.06em] mb-2">Source</label>
+                  <div className="space-y-1.5">
+                    <p className="text-[13px] text-text-2">
+                      {knowledgeSourceTitle || entry.title}
+                      {knowledgeSourceKind ? ` • ${knowledgeSourceKind}` : ''}
+                    </p>
+                    {knowledgeSourceLabel && (
+                      <p className="text-[12px] text-text-3/65">{knowledgeSourceLabel}</p>
+                    )}
+                    {knowledgeSourceUrl && (
+                      <a href={knowledgeSourceUrl} target="_blank" rel="noreferrer" className="text-[12px] text-accent-bright hover:underline break-all">
+                        {knowledgeSourceUrl}
+                      </a>
+                    )}
+                    <p className="text-[11px] text-text-3/55">
+                      {knowledgeChunkIndex != null && knowledgeChunkCount != null
+                        ? `Chunk ${knowledgeChunkIndex + 1} of ${knowledgeChunkCount}`
+                        : 'Source-backed knowledge'}
+                      {knowledgeSectionLabel ? ` • ${knowledgeSectionLabel}` : ''}
+                      {knowledgeCharStart != null && knowledgeCharEnd != null ? ` • chars ${knowledgeCharStart}-${knowledgeCharEnd}` : ''}
+                    </p>
+                  </div>
+                </div>
+              )}
+
               {/* Shared with (read mode) */}
               {entry.sharedWith && entry.sharedWith.length > 0 && (
                 <div>
@@ -575,6 +615,12 @@ export function MemoryDetail() {
                     <span className="text-text-3/70 block mb-1">Tier</span>
                     <span className="text-text-3/60 font-mono">{tier}</span>
                   </div>
+                  {knowledgeSourceId && (
+                    <div>
+                      <span className="text-text-3/70 block mb-1">Knowledge Source</span>
+                      <span className="text-text-3/60 font-mono">{knowledgeSourceId}</span>
+                    </div>
+                  )}
                   {entry.sessionId && (
                     <div>
                       <span className="text-text-3/70 block mb-1">Chat</span>

package/src/components/runs/run-list.tsx

@@ -8,6 +8,7 @@ import { BottomSheet } from '@/components/shared/bottom-sheet'
 import type { RunEventRecord, SessionRunRecord, SessionRunStatus } from '@/types'
 import { PageLoader } from '@/components/ui/page-loader'
 import { formatElapsed } from '@/lib/format-display'
+import { GroundingPanel } from '@/components/knowledge/grounding-panel'
 
 const STATUS_COLORS: Record<SessionRunStatus, { bg: string; text: string }> = {
   queued: { bg: 'bg-yellow-500/10', text: 'text-yellow-400' },
@@ -84,6 +85,10 @@ export function RunList() {
   }, [])
 
   const filtered = statusFilter ? runs.filter((r) => r.status === statusFilter) : runs
+  const selectedResultGrounding = selectedEvents
+    .slice()
+    .reverse()
+    .find((event) => event.phase === 'status' && ((event.citations?.length || 0) > 0 || event.retrievalTrace?.hits?.length))
 
   if (loading) {
     return <PageLoader label="Loading runs..." />
@@ -240,6 +245,15 @@ export function RunList() {
                 <pre className="text-[11px] text-text-3/80 font-mono whitespace-pre-wrap break-all bg-white/[0.02] rounded-[12px] p-4 max-h-[200px] overflow-auto border border-white/[0.04]">
                   {selected.resultPreview}
                 </pre>
+                {selectedResultGrounding && (
+                  <div className="mt-3">
+                    <GroundingPanel
+                      citations={selectedResultGrounding.citations}
+                      retrievalTrace={selectedResultGrounding.retrievalTrace}
+                      compact
+                    />
+                  </div>
+                )}
               </div>
             )}
 
@@ -262,6 +276,15 @@ export function RunList() {
                         <div className="text-[11px] text-text-2 whitespace-pre-wrap break-words">
                           {event.summary || event.event.text || event.event.toolOutput || event.event.toolName || event.event.t}
                         </div>
+                        {(event.citations?.length || event.retrievalTrace?.hits?.length) ? (
+                          <div className="mt-2">
+                            <GroundingPanel
+                              citations={event.citations}
+                              retrievalTrace={event.retrievalTrace}
+                              compact
+                            />
+                          </div>
+                        ) : null}
                       </div>
                     ))}
                   </div>

package/src/lib/server/api-routes.test.ts

@@ -78,9 +78,16 @@ function parseKnowledgeQueryParams(url: string) {
   const q = searchParams.get('q')
   const tagsParam = searchParams.get('tags')
   const limitParam = searchParams.get('limit')
+  const includeArchivedParam = searchParams.get('includeArchived')
   const tags = tagsParam ? tagsParam.split(',').map((t) => t.trim()).filter(Boolean) : undefined
   const limit = limitParam ? Math.max(1, Math.min(500, Number.parseInt(limitParam, 10) || 50)) : undefined
-  return { q, tags, limit }
+  const normalizedIncludeArchived = typeof includeArchivedParam === 'string'
+    ? includeArchivedParam.trim().toLowerCase()
+    : ''
+  const includeArchived = normalizedIncludeArchived === '1'
+    || normalizedIncludeArchived === 'true'
+    || normalizedIncludeArchived === 'yes'
+  return { q, tags, limit, includeArchived }
 }
 
 // ---------------------------------------------------------------------------
@@ -91,7 +98,12 @@ const thisFile = new URL(import.meta.url).pathname
 const routeDir = path.resolve(path.dirname(thisFile), '../../app/api')
 
 function readRoute(...segments: string[]): string {
-  return fs.readFileSync(path.join(routeDir, ...segments), 'utf-8')
+  const direct = path.join(routeDir, ...segments)
+  if (fs.existsSync(direct)) {
+    return fs.readFileSync(direct, 'utf-8')
+  }
+  const withTs = direct.endsWith('.ts') ? direct : `${direct}.ts`
+  return fs.readFileSync(withTs, 'utf-8')
 }
 
 // ===========================================================================
@@ -225,6 +237,12 @@ describe('Knowledge API contract', () => {
     it('returns undefined limit when param is absent', () => {
       assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge').limit, undefined)
     })
+
+    it('parses includeArchived as a boolean flag', () => {
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=true').includeArchived, true)
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=1').includeArchived, true)
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=no').includeArchived, false)
+    })
   })
 
   // --- Route file structure -----------------------------------------------
@@ -241,6 +259,29 @@ describe('Knowledge API contract', () => {
       assert.match(src, /export\s+async\s+function\s+PUT/)
       assert.match(src, /export\s+async\s+function\s+DELETE/)
     })
+
+    it('knowledge/hygiene/route.ts exports GET and POST', () => {
+      const src = readRoute('knowledge', 'hygiene', 'route.ts')
+      assert.match(src, /export\s+async\s+function\s+GET/)
+      assert.match(src, /export\s+async\s+function\s+POST/)
+    })
+
+    it('knowledge/sources/route.ts re-exports GET and POST', () => {
+      const src = readRoute('knowledge', 'sources', 'route.ts')
+      assert.match(src, /export\s+\{\s*GET,\s*POST\s*\}/)
+    })
+
+    it('knowledge/sources/[id]/route.ts re-exports GET, PUT, DELETE', () => {
+      const src = readRoute('knowledge', 'sources', '[id]', 'route.ts')
+      assert.match(src, /export\s+\{\s*GET,\s*PUT,\s*DELETE\s*\}/)
+    })
+
+    it('knowledge source action routes export POST', () => {
+      for (const route of ['archive', 'restore', 'supersede', 'sync']) {
+        const src = readRoute('knowledge', 'sources', '[id]', route, 'route.ts')
+        assert.match(src, /export\s+async\s+function\s+POST/)
+      }
+    })
   })
 })
 

package/src/lib/server/chat-execution/chat-execution-grounding.test.ts

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import test from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-grounding-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+test('executeSessionChatTurn persists citations and retrieval traces on grounded assistant messages', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('@/lib/server/storage')
+    const providersMod = await import('@/lib/providers/index')
+    const threadMod = await import('@/lib/server/agents/agent-thread-session')
+    const execMod = await import('@/lib/server/chat-execution/chat-execution')
+    const messageRepoMod = await import('@/lib/server/messages/message-repository')
+    const knowledgeMod = await import('@/lib/server/knowledge-sources')
+
+    const storage = storageMod.default || storageMod['module.exports'] || storageMod
+    const ensureAgentThreadSession = threadMod.ensureAgentThreadSession
+      || threadMod.default?.ensureAgentThreadSession
+      || threadMod['module.exports']?.ensureAgentThreadSession
+    const executeSessionChatTurn = execMod.executeSessionChatTurn
+      || execMod.default?.executeSessionChatTurn
+      || execMod['module.exports']?.executeSessionChatTurn
+    const getMessages = messageRepoMod.getMessages
+      || messageRepoMod.default?.getMessages
+      || messageRepoMod['module.exports']?.getMessages
+    const knowledge = knowledgeMod.default || knowledgeMod
+    const providers = providersMod.PROVIDERS
+      || providersMod.default?.PROVIDERS
+      || providersMod['module.exports']?.PROVIDERS
+
+    providers['test-provider'] = {
+      id: 'test-provider',
+      name: 'Test Provider',
+      models: ['unit'],
+      requiresApiKey: false,
+      requiresEndpoint: false,
+      handler: {
+        async streamChat() {
+          return 'Use blue green deployment for the gateway migration so rollback stays simple.'
+        },
+      },
+    }
+
+    const now = Date.now()
+    storage.saveAgents({
+      molly: {
+        id: 'molly',
+        name: 'Molly',
+        description: 'Grounding test',
+        provider: 'test-provider',
+        model: 'unit',
+        credentialId: null,
+        apiEndpoint: null,
+        fallbackCredentialIds: [],
+        disabled: false,
+        proactiveMemory: true,
+        extensions: ['memory'],
+        createdAt: now,
+        updatedAt: now,
+      },
+    })
+
+    await knowledge.createKnowledgeSource({
+      kind: 'manual',
+      title: 'Gateway Migration Runbook',
+      content: 'Use blue green deployment for gateway migrations so rollback stays simple and downtime stays low.',
+      tags: ['deploy'],
+    })
+
+    const session = ensureAgentThreadSession('molly')
+    const result = await executeSessionChatTurn({
+      sessionId: session.id,
+      message: 'gateway blue green rollback',
+      runId: 'run-grounding-chat',
+    })
+
+    const messages = getMessages(session.id)
+    const lastMessage = messages[messages.length - 1]
+
+    console.log(JSON.stringify({
+      persisted: result.persisted || false,
+      resultCitationCount: Array.isArray(result.citations) ? result.citations.length : 0,
+      resultSelectorStatus: result.retrievalTrace?.selectorStatus || null,
+      messageCitationCount: Array.isArray(lastMessage?.citations) ? lastMessage.citations.length : 0,
+      messageTraceHitCount: Array.isArray(lastMessage?.retrievalTrace?.hits) ? lastMessage.retrievalTrace.hits.length : 0,
+      messageSelectorStatus: lastMessage?.retrievalTrace?.selectorStatus || null,
+      messageSourceTitle: lastMessage?.citations?.[0]?.sourceTitle || null,
+    }))
+  `)
+
+  assert.equal(output.persisted, true)
+  assert.equal(output.resultCitationCount >= 1, true)
+  assert.equal(output.resultSelectorStatus, 'selected')
+  assert.equal(output.messageCitationCount >= 1, true)
+  assert.equal(output.messageTraceHitCount >= 1, true)
+  assert.equal(output.messageSelectorStatus, 'selected')
+  assert.equal(output.messageSourceTitle, 'Gateway Migration Runbook')
+})

package/src/lib/server/chat-execution/chat-execution-types.ts

@@ -1,4 +1,9 @@
-import type { MessageToolEvent, SSEEvent } from '@/types'
+import type {
+  KnowledgeCitation,
+  KnowledgeRetrievalTrace,
+  MessageToolEvent,
+  SSEEvent,
+} from '@/types'
 
 export interface ExecuteChatTurnInput {
   sessionId: string
@@ -33,4 +38,6 @@ export interface ExecuteChatTurnResult {
   inputTokens?: number
   outputTokens?: number
   estimatedCost?: number
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
 }

package/src/lib/server/chat-execution/chat-execution.ts

@@ -112,6 +112,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     responseCacheHit: streamResult.responseCacheHit,
     directUsage: streamResult.directUsage,
     durationMs: streamResult.durationMs,
+    knowledgeRetrievalTrace: streamResult.knowledgeRetrievalTrace || null,
     emit: partialPersistence.emit,
   })
 

package/src/lib/server/chat-execution/chat-turn-finalization.ts

@@ -1,4 +1,11 @@
-import type { Message, MessageToolEvent, SSEEvent, Session, UsageRecord } from '@/types'
+import type {
+  KnowledgeRetrievalTrace,
+  Message,
+  MessageToolEvent,
+  SSEEvent,
+  Session,
+  UsageRecord,
+} from '@/types'
 import { sendConnectorMessage } from '../connectors/manager'
 import { applyExactOutputContract, classifyExactOutputContract, type ExactOutputContract } from '@/lib/server/chat-execution/exact-output-contract'
 import { stripMainLoopMetaForPersistence } from '@/lib/server/agents/main-agent-loop'
@@ -43,6 +50,7 @@ import {
 import { appendUsage } from '@/lib/server/usage/usage-repository'
 import { synchronizeWorkingStateForTurn } from '@/lib/server/working-state/service'
 import { notify } from '@/lib/server/ws-hub'
+import { selectKnowledgeCitations } from '@/lib/server/knowledge-sources'
 
 import type { ExecuteChatTurnInput, ExecuteChatTurnResult } from './chat-execution-types'
 import type { PartialAssistantPersistence } from '@/lib/server/chat-execution/chat-turn-partial-persistence'
@@ -154,6 +162,7 @@ export async function finalizeChatTurn(params: {
     received: boolean
   }
   durationMs: number
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
   emit: (event: SSEEvent) => void
 }): Promise<ExecuteChatTurnResult> {
   const {
@@ -164,6 +173,7 @@ export async function finalizeChatTurn(params: {
     responseCacheHit,
     directUsage,
     durationMs,
+    knowledgeRetrievalTrace,
     emit,
   } = params
   let { fullResponse, errorMessage } = params
@@ -313,6 +323,12 @@ export async function finalizeChatTurn(params: {
   const hiddenControlOnly = shouldSuppressHiddenControlText(rawTextForPersistence)
   const textForPersistence = stripHiddenControlTokens(rawTextForPersistence)
   const persistedText = getPersistedAssistantText(textForPersistence, persistedToolEvents)
+  const grounding = hiddenControlOnly
+    ? { citations: [], retrievalTrace: knowledgeRetrievalTrace || null }
+    : selectKnowledgeCitations({
+        responseText: persistedText,
+        retrievalTrace: knowledgeRetrievalTrace || null,
+      })
   let persistedResponseForHooks = textForPersistence
 
   if (isHeartbeatRun && rawTextForPersistence) {
@@ -413,6 +429,8 @@ export async function finalizeChatTurn(params: {
           thinking: thinkingText || undefined,
           toolEvents: persistedToolEvents.length ? persistedToolEvents : undefined,
           kind: persistedKind,
+          citations: grounding.citations.length > 0 ? grounding.citations : undefined,
+          retrievalTrace: grounding.retrievalTrace || undefined,
         },
         enabledIds: extensionsForRun,
         phase: isHeartbeatRun ? 'heartbeat' : 'assistant_final',
@@ -643,5 +661,7 @@ export async function finalizeChatTurn(params: {
     inputTokens: accumulatedUsage.inputTokens || undefined,
     outputTokens: accumulatedUsage.outputTokens || undefined,
     estimatedCost: accumulatedUsage.estimatedCost || undefined,
+    citations: grounding.citations.length > 0 ? grounding.citations : undefined,
+    retrievalTrace: grounding.retrievalTrace || undefined,
   }
 }

package/src/lib/server/chat-execution/chat-turn-stream-execution.ts

@@ -1,5 +1,5 @@
 import { CONTEXT_OVERFLOW_RE } from '@/lib/providers/error-classification'
-import type { ProviderType } from '@/types'
+import type { KnowledgeRetrievalTrace, ProviderType } from '@/types'
 import { getEnabledCapabilityIds } from '@/lib/capability-selection'
 import { isLocalOpenClawEndpoint } from '@/lib/openclaw/openclaw-endpoint'
 import { streamAgentChat } from '@/lib/server/chat-execution/stream-agent-chat'
@@ -42,6 +42,7 @@ export interface ExecutedPreparedChatTurn {
     outputTokens: number
     received: boolean
   }
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function executePreparedChatTurn(params: {
@@ -90,6 +91,7 @@ export async function executePreparedChatTurn(params: {
   let responseCacheHit = false
   let responseCacheInput: LlmResponseCacheKeyInput | null = null
   let durationMs = 0
+  let knowledgeRetrievalTrace: KnowledgeRetrievalTrace | null = null
   const startTs = Date.now()
   const endLlmPerf = perf.start('chat-execution', 'llm-round-trip', {
     sessionId,
@@ -111,6 +113,7 @@ export async function executePreparedChatTurn(params: {
       responseCacheHit,
       durationMs,
       directUsage,
+      knowledgeRetrievalTrace: null,
     }
   }
 
@@ -157,6 +160,7 @@ export async function executePreparedChatTurn(params: {
         promptMode,
       })
       fullResponse = result.finalResponse || result.fullText
+      knowledgeRetrievalTrace = result.knowledgeRetrievalTrace || null
     } else {
       let directHistorySnapshot = isAutoRunNoHistory
         ? (heartbeatLightContext ? [] : getSessionMessages(sessionId).slice(-6))
@@ -298,5 +302,6 @@ export async function executePreparedChatTurn(params: {
     responseCacheHit,
     durationMs,
     directUsage,
+    knowledgeRetrievalTrace,
   }
 }

package/src/lib/server/chat-execution/post-stream-finalization.ts

@@ -5,7 +5,7 @@
  * usage recording, forced external service summary, capability hooks,
  * and OpenClaw sync.
  */
-import type { Session, UsageRecord } from '@/types'
+import type { KnowledgeRetrievalTrace, Session, UsageRecord } from '@/types'
 import { log } from '@/lib/server/logger'
 import type { ChatTurnState } from '@/lib/server/chat-execution/chat-turn-state'
 
@@ -51,6 +51,7 @@ export interface PostStreamResult {
   fullText: string
   finalResponse: string
   toolEvents: import('@/types').MessageToolEvent[]
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export interface FinalizeStreamResultOpts {
@@ -70,6 +71,7 @@ export interface FinalizeStreamResultOpts {
   cleanup: () => Promise<void>
   runId: string
   classification?: MessageClassification | null
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Promise<PostStreamResult> {
@@ -138,7 +140,12 @@ export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Prom
     const finalResponse = await resolveAndSummarize()
     await emitLlmOutputHook(finalResponse)
     await cleanup()
-    return { fullText: state.fullText, finalResponse, toolEvents: state.streamedToolEvents }
+    return {
+      fullText: state.fullText,
+      finalResponse,
+      toolEvents: state.streamedToolEvents,
+      knowledgeRetrievalTrace: opts.knowledgeRetrievalTrace || null,
+    }
   }
 
   // Strip leaked classification JSON from model output (e.g. `{ "isDeliverableTask": true, ... }`)
@@ -212,5 +219,10 @@ export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Prom
 
   await cleanup()
 
-  return { fullText: state.fullText, finalResponse, toolEvents: state.streamedToolEvents }
+  return {
+    fullText: state.fullText,
+    finalResponse,
+    toolEvents: state.streamedToolEvents,
+    knowledgeRetrievalTrace: opts.knowledgeRetrievalTrace || null,
+  }
 }

package/src/lib/server/chat-execution/prompt-sections.ts

@@ -8,7 +8,7 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
-import type { Session, Agent } from '@/types'
+import type { KnowledgeRetrievalTrace, Session, Agent } from '@/types'
 import type { PromptMode } from '@/lib/server/chat-execution/prompt-mode'
 import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
 import type { ActiveProjectContext } from '@/lib/server/project-context'
@@ -428,6 +428,7 @@ export function buildSuggestionsSection(
 export interface ProactiveMemoryResult {
   section: string | null
   injectedIds: Record<string, number>
+  knowledgeTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function buildProactiveMemorySection(
@@ -438,22 +439,28 @@ export async function buildProactiveMemorySection(
   isMinimalPrompt: boolean,
   currentThreadRecallRequest: boolean,
 ): Promise<ProactiveMemoryResult> {
-  const noResult: ProactiveMemoryResult = { section: null, injectedIds: {} }
+  const noResult: ProactiveMemoryResult = { section: null, injectedIds: {}, knowledgeTrace: null }
   if (isMinimalPrompt || !session.agentId || currentThreadRecallRequest || message.length <= 12) return noResult
   if (!agent?.proactiveMemory) return noResult
   try {
     const { getMemoryDb } = await import('@/lib/server/memory/memory-db')
     const { buildSessionMemoryScopeFilter } = await import('@/lib/server/memory/session-memory-scope')
+    const { buildKnowledgeRetrievalTrace } = await import('@/lib/server/knowledge-sources')
     const memDb = getMemoryDb()
     const recalled = memDb.search(message, session.agentId, {
       scope: buildSessionMemoryScopeFilter(session, agent.memoryScopeMode || null, activeProjectRoot),
     })
+    const knowledgeTrace = await buildKnowledgeRetrievalTrace({
+      query: message,
+      viewerAgentId: session.agentId,
+    })
 
     // Dedup: skip memories already injected 2+ times in this session
     const priorCounts = session.injectedMemoryIds || {}
     const filtered = recalled.filter((entry) => (priorCounts[entry.id] || 0) < 2)
 
     const topRecalled = filtered.slice(0, 3)
+    const sections: string[] = []
     if (topRecalled.length > 0) {
       // Track injection counts
       const updatedCounts: Record<string, number> = { ...priorCounts }
@@ -464,9 +471,28 @@ export async function buildProactiveMemorySection(
       const recalledLines = topRecalled.map((entry) =>
         `- ${entry.abstract || entry.content.slice(0, 300)}`,
       )
+      sections.push(`## Recalled Context\nRelevant memories from previous interactions:\n${recalledLines.join('\n')}`)
+      if (knowledgeTrace?.hits.length) {
+        const groundingLines = knowledgeTrace.hits.map((hit) =>
+          `- [${hit.chunkIndex + 1}/${hit.chunkCount}] ${hit.sourceTitle}: ${hit.snippet}`,
+        )
+        sections.push(`## Source Grounding\nSource-backed knowledge retrieved for this turn:\n${groundingLines.join('\n')}`)
+      }
       return {
-        section: `## Recalled Context\nRelevant memories from previous interactions:\n${recalledLines.join('\n')}`,
+        section: sections.join('\n\n'),
         injectedIds: updatedCounts,
+        knowledgeTrace,
+      }
+    }
+
+    if (knowledgeTrace?.hits.length) {
+      const groundingLines = knowledgeTrace.hits.map((hit) =>
+        `- [${hit.chunkIndex + 1}/${hit.chunkCount}] ${hit.sourceTitle}: ${hit.snippet}`,
+      )
+      return {
+        section: `## Source Grounding\nSource-backed knowledge retrieved for this turn:\n${groundingLines.join('\n')}`,
+        injectedIds: priorCounts,
+        knowledgeTrace,
       }
     }
   } catch { /* non-critical */ }

package/src/lib/server/chat-execution/stream-agent-chat.ts

@@ -36,7 +36,7 @@ import { log } from '@/lib/server/logger'
 import { logExecution } from '@/lib/server/execution-log'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
 import { expandExtensionIds } from '@/lib/server/tool-aliases'
-import type { ExecutionBrief, Session, Message } from '@/types'
+import type { ExecutionBrief, KnowledgeRetrievalTrace, Session, Message } from '@/types'
 import { getEnabledCapabilityIds } from '@/lib/capability-selection'
 import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
 import { resolveActiveProjectContext } from '@/lib/server/project-context'
@@ -199,6 +199,7 @@ export interface StreamAgentChatResult {
   finalResponse: string
   /** Tool events emitted during the streamed run. */
   toolEvents: import('@/types').MessageToolEvent[]
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 type LangChainContentPart =
@@ -267,6 +268,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
     preferMinimalPrompt: lightweightDirectChat,
   })
   const isMinimalPrompt = promptMode === 'minimal'
+  let knowledgeRetrievalTrace: KnowledgeRetrievalTrace | null = null
 
   // Resolve agent's thinking level for provider-native params
   let agentThinkingLevel: 'minimal' | 'low' | 'medium' | 'high' | undefined
@@ -309,6 +311,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
       fullText: requestedToolPreflightResponse,
       finalResponse: requestedToolPreflightResponse,
       toolEvents: [],
+      knowledgeRetrievalTrace: null,
     }
   }
   const runtime = loadRuntimeSettings()
@@ -490,6 +493,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
       isMinimalPrompt, currentThreadRecallRequest,
     )
     if (memoryResult.section) promptParts.push(memoryResult.section)
+    knowledgeRetrievalTrace = memoryResult.knowledgeTrace || null
     // Persist injection dedup counts so repeated memories are suppressed
     if (Object.keys(memoryResult.injectedIds).length > 0) {
       session.injectedMemoryIds = memoryResult.injectedIds
@@ -1269,5 +1273,6 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
     cleanup,
     runId,
     classification,
+    knowledgeRetrievalTrace,
   })
 }