feat: enable graph context by default

Author: codefromkarl

README.EN.md

@@ -15,5 +15,5 @@
 | Document | Purpose |
 |------|------|
 | [Docs index](./docs/README.md) | Unified entry for stable docs, plans, changelog, and archived delivery material |
-| [2026-04-09 update summary](./docs/changelog/2026-04-09.md) | Summary of the latest delivery-facing updates |
+| [2026-04-10 update summary](./docs/changelog/2026-04-10.md) | Default-on graph context for codebase retrieval plus docs sync |
 | [Latest delivery bundle](./docs/archive/deliveries/2026-04-09-index-and-memory/delivery-bundle.md) | Handoff bundle for the latest verified delivery |

README.md

@@ -33,6 +33,7 @@
 
 ## Updates
 
+- `2026-04-10`: `codebase-retrieval` now includes the lightweight direct graph summary by default, with MCP metadata, tests, and changelog docs updated in sync.
 - `2026-04-06`: tightened the default user path, memory governance, and operational visibility to make first use, feedback loops, and health checks clearer.
 - `2026-04-07`: improved the indexing pipeline with lighter planning, snapshot copy reduction, queue observability, fallback hardening, and repeatable benchmarks.
 - `2026-04-08`: added the embedding gateway, local caching and multi-upstream routing, plus Hugging Face integration and MCP context lifecycle tools.
@@ -279,10 +280,11 @@ ContextAtlas focuses on **what context to provide**, not how the task should be
 | Document | Purpose |
 |------|------|
 | [Docs index](./docs/README.md) | Unified entry for stable docs, plans, changelog, and archived delivery material |
+| [2026-04-10 update summary](./docs/changelog/2026-04-10.md) | Default-on graph context for codebase retrieval plus MCP/docs sync |
 | [First use guide](./docs/guides/first-use.md) | Fast onboarding path for the default `contextatlas` loop |
-| [2026-04-09 update summary](./docs/changelog/2026-04-09.md) | Summary of index planning thresholds, long-term memory table split, and delivery sync |
 | [2026-04-06 update summary](./docs/changelog/2026-04-06.md) | Summary of the new main path, memory governance, operations, release gate, and team metrics |
 | [2026-04-07 update summary](./docs/changelog/2026-04-07.md) | Summary of the seven indexing phases covering lightweight planning, snapshot copy reduction, health repair, observability, fallback hardening, storage trimming, and benchmarks |
+| [2026-04-09 update summary](./docs/changelog/2026-04-09.md) | Summary of index planning thresholds, long-term memory table split, and delivery sync |
 | [Deployment guide](./docs/guides/deployment.md) | Installation, deployment patterns, MCP integration, operations |
 | [CLI reference](./docs/reference/cli.md) | CLI commands, categories, and examples |
 | [MCP reference](./docs/reference/mcp.md) | MCP tools, parameters, and calling patterns |

README_ZH.md

@@ -37,6 +37,7 @@
 - `2026-04-07`：围绕索引链路完成轻量计划、快照复制优化、队列可观测、fallback 稳定性和性能基准建设。
 - `2026-04-08`：新增 embedding gateway、本地缓存与多上游切换能力，并补齐 Hugging Face 接入与 MCP 上下文生命周期工具。
 - `2026-04-09`：为索引计划增加 churn / cost 策略、把长期记忆迁到独立表 + FTS5，并完成默认路径硬化、阈值配置化、运维告警口径对齐与文档同步。
+- `2026-04-10`：`codebase-retrieval` 默认附带轻量直接图谱摘要，MCP 元数据、测试与更新日志同步到位。
 
 ## 目录
 
@@ -282,6 +283,7 @@ ContextAtlas 更关注“给 agent 什么上下文”，而不是“替 agent 
 | 文档 | 用途 |
 |------|------|
 | [文档总览](./docs/README.md) | 文档目录统一入口，区分稳定文档、计划、更新日志和归档材料 |
+| [2026-04-10 更新总结](./docs/changelog/2026-04-10.md) | `codebase-retrieval` 默认附带图谱摘要，并同步 MCP 文档与测试口径 |
 | [首次使用](./docs/guides/first-use.md) | 10 分钟跑通默认闭环，先理解包名、CLI 名和第一条查询 |
 | [2026-04-07 更新总结](./docs/changelog/2026-04-07.md) | 索引 7 个阶段优化总结，覆盖轻量计划、快照复制、健康修复、队列可观测性、fallback、存储裁剪与 benchmark |
 | [部署手册](./docs/guides/deployment.md) | 安装、部署场景、MCP 集成、运维建议 |

docs/README.md

@@ -42,6 +42,7 @@
 
 ## 更新日志
 
+- [2026-04-10](./changelog/2026-04-10.md)
 - [2026-04-09](./changelog/2026-04-09.md)
 - [2026-04-08](./changelog/2026-04-08.md)
 - [2026-04-07](./changelog/2026-04-07.md)

docs/changelog/2026-04-10.md

@@ -0,0 +1,63 @@
+# ContextAtlas 更新总结（2026-04-10）
+
+本轮更新围绕一个很具体的收口动作展开：
+
+> 让 `codebase-retrieval` 的轻量图谱摘要从“可选增强”升级为“默认带出”，降低调用方的参数负担，同时保持显式关闭能力。
+
+## 一、本轮完成了什么
+
+这次主要完成了 4 个同步动作：
+
+1. `codebase-retrieval` 的 `include_graph_context` 默认值改为开启
+2. MCP 工具注册元数据同步改为默认开启
+3. 回归测试更新为覆盖“默认开启”口径
+4. 今日更新文档与 README / docs 索引同步
+
+## 二、默认行为调整
+
+此前这项能力属于轻集成：
+
+- 默认不启用
+- 调用方显式传 `include_graph_context: true` 时，才会从 top seed symbol 抽取少量符号
+- 再查询这些符号的直接 upstream / downstream
+- 最后在 text / json 返回里附带一段轻量图谱摘要
+
+本轮调整后：
+
+- 默认值改为 `true`
+- 现有调用方即使不传该参数，也会拿到轻量图谱摘要
+- 如果某些客户端明确不需要该摘要，仍可传 `include_graph_context: false` 关闭
+
+这样做的目的很直接：
+
+- 让常见检索调用默认更完整
+- 减少客户端 prompt / wrapper 里重复补参数
+- 保持响应体规模仍然可控，只追加 top symbols 的直接邻接摘要，不扩成重图查询
+
+## 三、涉及文件
+
+- `src/mcp/tools/codebaseRetrieval.ts`
+- `src/mcp/registry/tools.ts`
+- `tests/codebase-retrieval.test.ts`
+- `docs/reference/mcp.md`
+
+另外同步更新了：
+
+- `docs/README.md`
+- `README.md`
+- `README.EN.md`
+- `README_ZH.md`
+
+## 四、验证口径
+
+本次改动沿用现有验证门槛：
+
+```bash
+pnpm build
+node --import tsx --test tests/codebase-retrieval.test.ts
+```
+
+说明：
+
+- 与本次改动直接相关的 build 与工具测试应继续通过
+- `mcp-stdio` 在混合批跑场景下仍有既有不稳定现象，因此这次仍不把它作为该轻集成默认开启的放行门槛

docs/reference/mcp.md

@@ -129,6 +129,8 @@ contextatlas mcp
 
 ### 代码检索
 
+`codebase-retrieval` 现在默认会附带一段轻量直接图谱摘要；只有在你明确不需要时，才传 `include_graph_context: false` 关闭。
+
 ```json
 {
   "repo_path": "/path/to/repo",

src/mcp/registry/tools.ts

@@ -98,6 +98,11 @@ Examples of BAD queries:
           description: 'Whether to return a lightweight overview or the expanded full retrieval payload',
           default: 'expanded',
         },
+        include_graph_context: {
+          type: 'boolean',
+          description: 'Whether to append a compact direct graph context summary for top matched symbols.',
+          default: true,
+        },
       },
       required: ['repo_path', 'information_request'],
     },

src/mcp/tools/codebaseRetrieval.ts

@@ -14,7 +14,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { z } from 'zod';
 import { responseFormatSchema } from './responseFormat.js';
-import { generateProjectId } from '../../db/index.js';
+import { closeDb, generateProjectId, initDb } from '../../db/index.js';
+import { GraphStore } from '../../graph/GraphStore.js';
 import type {
   BlockFirstPayload,
   CheckpointCandidate,
@@ -57,6 +58,11 @@ export const codebaseRetrievalSchema = z.object({
     .optional()
     .default('expanded')
     .describe('Whether to return a lightweight overview or the expanded full retrieval payload'),
+  include_graph_context: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('When true, append a compact direct graph context summary for top matched symbols.'),
 });
 
 export type CodebaseRetrievalInput = z.infer<typeof codebaseRetrievalSchema>;
@@ -144,12 +150,24 @@ interface RetrievalResultCard {
   reasoning: string[];
   trustRules: string[];
   nextActions: string[];
+  graphContext?: RetrievalGraphContextSummary;
   status?: {
     headline: string;
     details: string[];
   };
 }
 
+interface RetrievalGraphSymbolSummary {
+  name: string;
+  filePath: string;
+  directUpstream: string[];
+  directDownstream: string[];
+}
+
+interface RetrievalGraphContextSummary {
+  symbols: RetrievalGraphSymbolSummary[];
+}
+
 // ===========================================
 // 自动索引逻辑
 // ===========================================
@@ -323,7 +341,14 @@ export async function handleCodebaseRetrieval(
   args: CodebaseRetrievalInput,
   onProgress?: ProgressCallback,
 ): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
-  const { repo_path, information_request, technical_terms, response_format, response_mode } = args;
+  const {
+    repo_path,
+    information_request,
+    technical_terms,
+    response_format,
+    response_mode,
+    include_graph_context,
+  } = args;
   const requestId = crypto.randomUUID().slice(0, 8);
   const startedAt = Date.now();
   const reportProgress = createRetrievalProgressReporter(onProgress);
@@ -644,6 +669,7 @@ export async function handleCodebaseRetrieval(
     informationRequest: information_request,
     technicalTerms: technical_terms || [],
     pack: contextPack,
+    includeGraphContext: include_graph_context ?? true,
     status: {
       headline: '索引状态: 完整模式已就绪',
       details: ['当前结果来自已建立索引的混合检索链路'],
@@ -683,6 +709,7 @@ function formatMcpResponse(
       ? {
           responseMode: options.responseMode,
           summary: overview.summary,
+          graphContext: resultCard.graphContext,
           topFiles: overview.topFiles,
           contextBlocks,
           references: overview.references,
@@ -698,6 +725,7 @@ function formatMcpResponse(
             files: files.length,
             totalSegments: files.reduce((acc, f) => acc + f.segments.length, 0),
           },
+          graphContext: resultCard.graphContext,
           contextBlocks,
           references: contextBlocks.flatMap((block) => block.provenance.map((item) => ({ blockId: block.id, ...item }))),
           expansionCandidates: overview.expansionCandidates,
@@ -730,6 +758,13 @@ function formatMcpResponse(
       '',
       '### Next Inspection Suggestions',
       ...(overview.nextInspectionSuggestions.length > 0 ? overview.nextInspectionSuggestions.map((item) => `- ${item}`) : ['- None']),
+      ...(resultCard.graphContext
+        ? [
+            '',
+            '### Graph Context',
+            ...formatGraphContextSummary(resultCard.graphContext),
+          ]
+        : []),
     ];
     return { content: [{ type: 'text', text: lines.join('\n') }] };
   }
@@ -768,6 +803,13 @@ function formatMcpResponse(
     '### 相关长期记忆 (Source: Long-term Memory)',
     formatLongTermMemoryMatches(resultCard.longTermMemories),
     '',
+    ...(resultCard.graphContext
+      ? [
+          '### 直接图谱摘要 (Source: Code Graph)',
+          formatGraphContextSummary(resultCard.graphContext).join('\n'),
+          '',
+        ]
+      : []),
     '### 近期反馈信号 (Source: Feedback Loop)',
     formatFeedbackMatches(resultCard.feedbackSignals),
     '',
@@ -854,12 +896,14 @@ async function buildRetrievalResultCard({
   informationRequest,
   technicalTerms,
   pack,
+  includeGraphContext,
   status,
 }: {
   repoPath: string;
   informationRequest: string;
   technicalTerms: string[];
   pack: ContextPack;
+  includeGraphContext: boolean;
   status?: RetrievalResultCard['status'];
 }): Promise<RetrievalResultCard> {
   try {
@@ -900,11 +944,16 @@ async function buildRetrievalResultCard({
       ),
     );
 
+    const graphContext = includeGraphContext
+      ? buildGraphContextSummary(repoPath, pack)
+      : undefined;
+
     return {
       memories: memoryMatchesWithFeedback,
       decisions: decisionMatches,
       longTermMemories: longTermMatches,
       feedbackSignals,
+      graphContext,
       reasoning: buildReasoningLines(
         informationRequest,
         technicalTerms,
@@ -929,6 +978,7 @@ async function buildRetrievalResultCard({
       decisions: [],
       longTermMemories: [],
       feedbackSignals: [],
+      graphContext: includeGraphContext ? buildGraphContextSummary(repoPath, pack) : undefined,
       reasoning: buildReasoningLines(informationRequest, technicalTerms, pack, [], [], [], []),
       trustRules: buildTrustRules(),
       nextActions: buildNextActions({
@@ -941,6 +991,81 @@ async function buildRetrievalResultCard({
   }
 }
 
+function buildGraphContextSummary(
+  repoPath: string,
+  pack: ContextPack,
+): RetrievalGraphContextSummary | undefined {
+  const projectId = generateProjectId(repoPath);
+  const snapshotId = resolveCurrentSnapshotId(projectId);
+  const db = initDb(projectId, snapshotId);
+
+  try {
+    const store = new GraphStore(db);
+    const seen = new Set<string>();
+    const symbols: RetrievalGraphSymbolSummary[] = [];
+
+    for (const seed of pack.seeds) {
+      const symbolName = extractSymbolNameFromBreadcrumb(seed.record.breadcrumb);
+      if (!symbolName) continue;
+
+      const matches = store
+        .findSymbolsByName(symbolName)
+        .filter((symbol) => symbol.filePath === seed.filePath);
+      const match = matches[0];
+      if (!match) continue;
+      if (seen.has(match.id)) continue;
+      seen.add(match.id);
+
+      const upstream = store
+        .getDirectRelations(match.id, 'upstream')
+        .slice(0, 3)
+        .map((relation) => `${relation.relationType}:${relation.targetName}`);
+      const downstream = store
+        .getDirectRelations(match.id, 'downstream')
+        .slice(0, 3)
+        .map((relation) => `${relation.relationType}:${relation.targetName}`);
+
+      symbols.push({
+        name: match.name,
+        filePath: match.filePath,
+        directUpstream: upstream,
+        directDownstream: downstream,
+      });
+
+      if (symbols.length >= 3) {
+        break;
+      }
+    }
+
+    return symbols.length > 0 ? { symbols } : undefined;
+  } catch (err) {
+    logger.debug({ error: (err as Error).message }, '构建图谱摘要失败，忽略 code graph summary');
+    return undefined;
+  } finally {
+    closeDb(db);
+  }
+}
+
+function extractSymbolNameFromBreadcrumb(breadcrumb: string): string | null {
+  const parts = breadcrumb.split(' > ');
+  const tail = parts[parts.length - 1];
+  if (!tail || tail.includes('/')) {
+    return null;
+  }
+
+  return tail
+    .replace(/^(abstract class |class |interface |fn\*? |def |func |struct |enum |trait |record |@interface )/, '')
+    .trim() || null;
+}
+
+function formatGraphContextSummary(summary: RetrievalGraphContextSummary): string[] {
+  return summary.symbols.flatMap((symbol) => [
+    `- ${symbol.name} (${symbol.filePath})`,
+    `  upstream: ${symbol.directUpstream.length > 0 ? symbol.directUpstream.join(', ') : 'none'}`,
+    `  downstream: ${symbol.directDownstream.length > 0 ? symbol.directDownstream.join(', ') : 'none'}`,
+  ]);
+}
+
 function rankFeatureMemoryMatches(
   memories: FeatureMemory[],
   informationRequest: string,