codebase-memory-mcp 诊断完全指南：如何用 CBM_DIAGNOSTICS 与 trajectory.ndjson 快速定位内存泄漏-编程实验室

codebase-memory-mcp 诊断完全指南：如何用 CBM_DIAGNOSTICS 与 trajectory.ndjson 快速定位内存泄漏

【免费下载链接】codebase-memory-mcpHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.项目地址: https://gitcode.com/GitHub_Trending/co/codebase-memory-mcp

codebase-memory-mcp是一款高性能代码智能 MCP 服务器，它把整个代码库索引成持久化知识图谱——平均毫秒级完成索引、支持 158 种语言、查询低于 1ms，单文件静态二进制、零依赖。当它长期运行出现内存缓慢上涨时，官方提供了一套内置诊断机制：CBM_DIAGNOSTICS环境变量 + 每 5 秒一条记录的trajectory.ndjson 内存轨迹文件。这篇文章带你从零开启诊断、读懂每一行轨迹数据，并快速判断「这到底是不是泄漏」。

1️⃣ CBM_DIAGNOSTICS 是什么？

codebase-memory-mcp 完全本地运行、不收集任何遥测数据——你的代码和查询永远不会离开本机。这也意味着：当出现难以复现的内存缓慢增长或性能退化时，官方没有任何数据可用，除非你主动捕获。

CBM_DIAGNOSTICS就是为此设计的开关（默认关闭）。开启后，守护进程会：

在系统临时目录（macOS/Linux 为$TMPDIR或/tmp，Windows 为%TEMP%）下创建一个全新的、仅属主可访问的随机私有目录cbm-diagnostics-<pid>-<随机串>
启动一个后台写入线程，每 5 秒采集一次资源指标
生成两份文件：snapshot.json（最新快照，退出时自动删除）和trajectory.ndjson（完整时间轨迹，进程退出后保留在磁盘上，超过约 8MB 自动轮转为trajectory.ndjson.1）

相关源码实现位于 src/foundation/diagnostics.c，接口定义见 src/foundation/diagnostics.h。

2️⃣ 一键开启：3 步捕获内存轨迹

第 1 步：设置环境变量

在启动第一个守护进程会话之前设置CBM_DIAGNOSTICS=1（或true）。建议写进每个 Agent 的 MCP 服务器配置env块，或在启动前export。

⚠️ 如果守护进程已在运行，先关闭所有基于守护进程的会话让它退出，再修改设置——守护进程只在首次会话启动时捕获该变量。

第 2 步：复现问题

让程序跑足够久——缓慢泄漏需要时间在趋势线上显现出来。

第 3 步：找到文件路径

随机化的精确路径会写入一条diagnostics.start发现记录（单行 JSON）中，位置在${CBM_CACHE_DIR}/logs/cbm-daemon.log。这条记录即使CBM_LOG_LEVEL压制了普通日志也一定会输出，保证路径始终可发现：

文件	作用
`trajectory.ndjson`	⭐ 内存轨迹——排查内存/泄漏问题的核心文件，记录在进程退出后仍在
`snapshot.json`	仅最新快照，适合快速现场检查，正常退出时删除

3️⃣ trajectory.ndjson 逐字段解读

轨迹文件是标准的 NDJSON 格式（每行一个 JSON 对象），每 5 秒追加一行。一条典型记录长这样：

{"uptime_s":300,"rss":52428800,"peak_rss":55050800,"committed":49283072,"peak_committed":49283072,"page_faults":15200,"fd":23,"queries":412}

各字段含义（写入逻辑见 src/foundation/diagnostics.c）：

字段	含义	排查价值
`uptime_s`	进程运行时长（秒）	时间轴基准
`rss`	当前常驻内存（字节）	泄漏判断的第一指标
`peak_rss`	历史峰值 RSS	是否逼近峰值不回落
`committed`	堆提交字节（Windows 为 commit charge）	区分「真实泄漏」与「分配器保留的空闲页」
`peak_committed`	提交字节峰值	同上
`page_faults`	缺页中断次数	内存分配活跃度
`fd`	打开的文件描述符数	排查 fd 泄漏
`queries`	累计工具调用次数	归一化分母：按查询数对比增长速率

项目图谱的可视化效果可参考下图（23,827 个节点 / 51,526 条边的代码知识图谱）：

💡 进阶：设置CBM_MEM_STATS=1还会额外生成cbm-allocator-stats-<pid>.txt，包含分配器自记账统计与 arena 分片图，用于区分「碎片化/切片粒度」与「真实泄漏」两种相反结论（见 src/foundation/diagnostics.c）。

4️⃣ 如何判断「这是不是泄漏」？

趋势（trend）才是定位泄漏的关键，单一时刻的数值没有意义。看轨迹时按以下思路：

rss是否随uptime_s单调增长？只涨不回落 → 高度可疑
增长速率 vsqueries：把 RSS 增量除以查询次数。若「每次查询消耗固定字节」且无界增长 → 每查询泄漏；若增长与查询数无关、只随时间走 → 后台任务或缓存问题
fd是否同步上涨？同步单调增长提示文件/句柄未释放
peak_rss与rss的差距：峰值后能回落说明内存被正常回收，多为突发负载而非泄漏

官方建议：你的 AI 助手可以直接读取这份 NDJSON，报告rss/committed是否单调增长、增速多快、相对查询数如何——这正是维护者定位问题所需的信息。

5️⃣ 隐私与安全设计亮点 🛡️

这套诊断机制在安全性上相当讲究：

私有随机目录：防止本机其他账户在可预测路径预置符号链接或特殊文件
独占创建 +openat锚定：POSIX 上所有 I/O 绑定到已校验的目录描述符，绝不穿越他人植入的链接（见 src/foundation/diagnostics.c）
0600 权限：快照描述本进程堆布局，仅属主可读
best-effort 原则：关机路径可中断、有 500ms 时限，卡死的文件系统也永远不会拖住守护进程
轨迹文件不含任何源码或查询文本，只有资源计数器，可放心附在 issue 中

安全与生命周期护栏由 tests/test_diagnostics.c 覆盖；配置项文档见 docs/CONFIGURATION.md。