第 1 课

一行装好 codebase-memory-mcp，给 Flask 建第一份索引

用官方安装脚本加 --skip-config 装好 0.12.1，先不改动任何智能体配置；克隆 Flask 3.1.3，用 index_repository 建索引，看懂节点、边、未索引文件和部分解析文件这几项报告；用 list_projects、get_graph_schema、get_architecture、index_status 看图里有什么、索引存在哪里。

图文20 分钟

课程目录第 1 / 3 课

返回课程介绍

学习位置仅保存在当前浏览器，有效期 180 天。

本课对照的官方资料：README 的 Quick Start、Installation 与 CLI Mode 部分（0.12.1 版）、安装脚本 install.sh 。测试环境：2026-11-14，Asia/Shanghai，Debian 13 x86_64 云主机（无显卡），全新 Linux 用户 kunlab，git 2.47、jq 1.7，codebase-memory-mcp 0.12.1（2026-10-17 发布）。下面所有「对照结果」都是这台机器的真实输出，只做了节选。

codebase-memory-mcp 做的事可以一句话说清：先把整个仓库解析一遍，把函数、类、调用、导入、文档章节等存成一张本地的图；之后不管是你在命令行里问，还是编程智能体通过 MCP 问，都直接查这张图，而不是从头 grep、一个个文件读。这一课先把它装好，拿 Flask 3.1.3 的源码建第一份索引，并看懂索引报告里的每一项。

第 1 步：用官方脚本安装

官方的一行安装命令会按系统和 CPU 下载对应的发布包，校验 SHA-256 后装到 ~/.local/bin。默认情况下，它还会检测本机装了哪些编程智能体并自动写入配置。第一次上手建议先加 --skip-config，只装程序、不改任何智能体配置，第 3 课再按需接入：

curl -fsSL \
  https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh \
  | bash -s -- --skip-config
export PATH="$HOME/.local/bin:$PATH"
codebase-memory-mcp --version
ls -l ~/.local/bin/

对照结果：

codebase-memory-mcp installer
  os:      linux
  arch:    amd64
  target:  /home/kunlab/.local/bin/codebase-memory-mcp

Downloading codebase-memory-mcp-linux-amd64-portable.tar.gz...
Checksum verified.
Extracting...
Verified candidate: codebase-memory-mcp 0.12.1
...
Added /home/kunlab/.local/bin to PATH in /home/kunlab/.bashrc
...
Skipping agent configuration (--skip-config)

codebase-memory-mcp 0.12.1

-rwxr-xr-x 1 kunlab kunlab 330641600 Nov 14 00:15 codebase-memory-mcp
-rwxr-xr-x 1 kunlab kunlab     13654 Nov 14 00:15 install.sh

几点说明：

程序约 330 MB，是因为 162 种语言的解析器和语义搜索用的 nomic-embed-code 向量模型都编译进了这一个文件，运行时不需要 Docker、Python 或 Node.js。
安装脚本会把 ~/.local/bin 写进 ~/.bashrc，新开的终端会自动生效；当前终端用上面的 export 立即生效。
旁边的 install.sh 是更新器。官方的更新方式就是重新运行它，程序本身从不后台联网检查新版本。
安装时出现的 Stopping active CBM sessions... 是正常步骤：安装前会先让本机正在运行的 codebase-memory-mcp 进程退出，避免新旧版本混用。

第 2 步：克隆练习仓库

用 Flask 3.1.3 的源码做练习：体量不大（83 个 Python 文件），调用关系又足够典型。--depth 1 只拉最新一次提交，省时间：

mkdir -p ~/cbm-lab && cd ~/cbm-lab
git clone -q --depth 1 --branch 3.1.3 https://github.com/pallets/flask.git
cd flask && git log --oneline -1
find . -name "*.py" | wc -l

对照结果：

22d9247 release version 3.1.3
83

克隆时 git 还会打印一大段 You are in 'detached HEAD' state 的说明，这是按标签检出的正常提示，不用理会。

第 3 步：建第一份索引

所有 MCP 工具都能用 codebase-memory-mcp cli <工具名> 在命令行里直接调用，参数就是把工具参数名里的下划线换成连字符。index_repository 负责建索引，--name 给项目起个短名字，后面每条查询都要用它：

codebase-memory-mcp cli --progress index_repository \
  --repo-path "$PWD" --name flask > ../flask-index.json
jq "{project, status, nodes, edges, not_indexed_files_count, parse_partial_count}" \
  ../flask-index.json

对照结果：

Preparing one-shot local CBM command...
Running index_repository locally...
Completed index_repository (1410 ms)
{
  "project": "flask",
  "status": "indexed",
  "nodes": 2488,
  "edges": 8017,
  "not_indexed_files_count": 8,
  "parse_partial_count": 3
}

建索引只用了 1.4 秒。进度信息走标准错误，结果 JSON 走标准输出，所以可以放心重定向到文件。终端里还会多一行提示：这条命令临时启动了一个后台协调进程，命令结束就退出；如果要连续查很多次，可以先执行 codebase-memory-mcp daemon start 让它常驻，第 2 课就这样做。

报告里的几项含义：

nodes / edges：图里有多少个节点（文件、函数、类、文档章节等）和多少条关系（调用、定义、导入等）。
not_indexed_files_count：按设计跳过的文件，比如 .gitignore 里的内容、图片和 SVG。
parse_partial_count：解析了、但有个别行没解析出来的文件。

看看是哪 3 个文件只解析了一部分：

jq -r '.parse_partial.files[] | "\(.path)  lines \(.error_ranges)"' ../flask-index.json

对照结果：

examples/celery/src/task_app/templates/index.html  lines 14-14,24-24,32-32
examples/javascript/js_example/templates/xhr.html  lines 7-7
examples/tutorial/flaskr/schema.sql  lines 8-8,14-14

都是示例目录里的模板和 SQL，不影响 src/flask 的 Python 代码。官方的提醒是：图里查不到某样东西，不等于代码里没有，先看看它在不在这类「缺口」名单里。

第 4 步：看看图里有什么

先列出所有已建索引的项目，再看图的结构和语言分布：

codebase-memory-mcp cli list_projects
codebase-memory-mcp cli get_graph_schema --project flask | head -n 18
codebase-memory-mcp cli get_architecture --project flask --format json \
  | jq -c ".languages"

对照结果：

projects: 1  (cols: name root_path branch)
  flask /home/kunlab/cbm-lab/flask DETACHED

node_labels: 15  (cols: label count)
  Function 526
  Section 470
  Method 315
  Variable 272
  Route 266
  File 209
  Module 205
  Class 122
  Folder 48
  Decorator 21
  Package 21
  EnvVar 9
  Table 2
  Branch 1
  Project 1
edge_types: 23  (cols: type count)

{"cols":["language","files"],"rows":[["Python",83],["HTML",20],["YAML",7],
["TOML",5],["SQL",2],["CSS",2],["Bash",1]]}

DETACHED 是因为按标签克隆的仓库不在任何分支上，第 2 课会用到这一点。命令行默认输出紧凑的表格（方便智能体省 token），加 --format json 就是给程序处理的 JSON。Section 有 470 个，来自 docs/ 里的文档章节：文档和代码在同一张图里，可以一起查。

最后确认索引状态和存放位置：

codebase-memory-mcp cli index_status --project flask | head -n 6
ls ~/.cache/codebase-memory-mcp/

对照结果：

project: flask
nodes: 2488
edges: 8017
status: ready
root_path: /home/kunlab/cbm-lab/flask
indexed_at: 2026-11-13T16:14:17Z

_config.db
activity.db
activity.db-shm
activity.db-wal
flask.db
logs

indexed_at 是 UTC 时间，换成北京时间是 11 月 14 日 00:14。每个项目一个 SQLite 文件（这里是 flask.db），重启机器也还在；源码本身留在原处，不会被复制。

常见坑

装完提示找不到命令：当前终端还没读到新的 PATH。执行 export PATH="$HOME/.local/bin:$PATH"，或者新开一个终端。
不想让安装器动智能体配置：加 --skip-config。不加时，安装器会自动检测并改写已装智能体的配置文件，第 3 课会先用 --dry-run 预览再决定。
--repo-path 写了相对路径：官方排错表要求传绝对路径，用 "$PWD" 或完整路径最稳。
忘了项目叫什么：list_projects 会列出每个项目的名字和源码路径。不加 --name 时，名字由路径自动生成，比如 /home/kunlab/cbm-lab/flask 会变成 home-kunlab-cbm-lab-flask，后面每条命令都得用这个长名字。
想从头再来：codebase-memory-mcp cli delete_project --project flask 删掉这个项目的图，源码不受影响。

小结

这一课用官方脚本装好了 codebase-memory-mcp 0.12.1，给 Flask 3.1.3 建了第一份索引：2488 个节点、8017 条关系，用时约 1.4 秒；还看懂了报告里「未索引」和「部分解析」两类缺口，知道了索引存在 ~/.cache/codebase-memory-mcp/。下一课开始真正用这张图：查符号、查调用链、读源码、写 Cypher 查询，再改一行代码看影响面。

本课资料

codebase-memory-mcp把仓库编成知识图谱的本地 MCP：结构查询、调用链、影响面。