在 macOS 上安装并使用 Codebase Memory MCP：接入 Codex 桌面版

在大型项目中，仅靠逐文件搜索来理解调用关系和模块依赖，往往会消耗较多上下文，也不利于快速定位影响范围。Codebase Memory MCP 可以把代码结构索引为可查询的知识图谱，并接入 Codex 桌面版。下面从 macOS 安装、接入验证和实际使用入手，同时处理 PATH、目录权限与界面配置等常见问题。

Codebase Memory MCP 安装与使用总结（macOS + Codex 桌面版）

下面把整个流程从 安装 → 验证 → 使用 → 常见问题及解决，按小白视角完整总结一遍。你用的是 macOS + Codex 桌面版，可以直接照着核对。

---

一、整体结论

• codebase-memory-mcp 是给 Codex 外接的 MCP 知识图谱工具，安装后会 自动在后台运行。
• 它不会替代 Codex 自身的记忆，而是补充：Codex 的 AGENTS.md / Memories 管“规则和偏好”，它管“代码结构精确查询”。
• 核心优势：大幅省 Token。传统逐文件搜索约 412,000 tokens，结构化查询 5 次约 3,400 tokens，节省约 99%。
• 3D UI 只是可视化仪表盘，不影响 Codex 调用工具的能力和 Token 优势。

---

二、安装流程

1. 官方一键安装

终端运行：

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

安装脚本会自动：

• 下载适合 macOS 的二进制文件；
• 安装到 ~/.local/bin；
• 自动检测并配置 Codex 桌面版；
• 注册为 MCP 服务器。

2. 安装后验证

codebase-memory-mcp --version

能显示版本号即成功。

3. 配置 PATH

如果提示 command not found，说明 ~/.local/bin 不在 PATH 中。运行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

或者关闭终端重新打开。

4. 重启 Codex 桌面版

完全退出 Codex，再重新打开。在对话中输入：

/mcp

如果看到 codebase-memory-mcp 和 14 个工具，就说明接入成功。

---

三、你遇到的具体问题与解决

问题 1：安装报错 cannot create install directory /Users/user/.local/bin

原因：~/.local 目录可能被 root 占用，普通用户没有权限。

你尝试 mkdir -p ~/.local/bin 时报：

Permission denied
chown: Operation not permitted

解决步骤：

sudo chown -R $(whoami):staff ~/.local
chmod -R 755 ~/.local

验证：

ls -ld ~/.local

如果所有者变成你的用户名，就修好了。然后重新运行官方安装脚本。

问题 2：xattr: No such xattr: com.apple.quarantine

这是无害警告，可以忽略。不是安装失败原因。

问题 3：zsh: command not found: codebase-memory-mcp

原因：PATH 没包含 ~/.local/bin。

解决：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

之后就能直接运行：

codebase-memory-mcp --version
codebase-memory-mcp update

备选：使用绝对路径：

~/.local/bin/codebase-memory-mcp update

---

四、安装后怎么用

1. 在 Codex 桌面版中打开你的项目文件夹。
2. 对 Codex 说：

Index this codebase

3. 等它索引完成。普通项目通常很快，大型项目也能在分钟级完成。
4. 然后就可以问结构化问题，例如：
   • “谁调用了 processOrder？”
   • “修改 UserService 会影响哪些文件？”
   • “这个项目的核心模块和依赖关系是什么？”
   • “有没有从未被调用过的死代码？”

Codex 会自动调用 Codebase Memory MCP 的工具来回答，而不是盲目读大量文件。

如果想自动索引每个新项目，可以运行：

codebase-memory-mcp config set auto_index true

---

五、3D 可视化界面相关

1. 带 UI 和不带 UI 的区别

核心功能完全一样。UI 只是多了一个本地网页，把知识图谱用 3D 方式画出来：

• 旋转、缩放、查看模块和调用关系；
• 点选函数可高亮调用链；
• 修改代码后图谱自动更新；
• 有死代码视图。

它不会改变 Codex 的查询能力和 Token 优势。

2. 空间占用

几乎不额外占用空间。核心是单个静态二进制文件，约 20 MB，UI 内嵌其中。

3. 启动 UI

codebase-memory-mcp --ui=true --port=9749

浏览器打开：

http://localhost:9749

4. 不想要 UI 怎么关闭

不需要卸载重装。编辑配置文件：

~/.cache/codebase-memory-mcp/config.json

找到：

"ui_enabled": true

改成：

"ui_enabled": false

保存后，完全退出并重启 Codex 桌面版即可。

---

六、和 Codex 本地记忆的区别

维度	Codex 本地记忆	Codebase Memory MCP
本质	AGENTS.md 静态规则 + Memories 动态摘要	代码知识图谱
内容	自然语言，可能模糊	精确的符号、调用、依赖
更新	手动写 + 后台总结	一键索引，毫秒到分钟级
适合	项目约定、团队规则、个人偏好	代码导航、影响分析、调用链、死代码
Token	AGENTS.md 每次会话固定加载	按需查询，结构化返回，极省 Token

理想配置：

• AGENTS.md 保持精简；
• Memories 后台运行；
• 复杂代码结构查询交给 codebase-memory-mcp。

---

七、日常维护命令

# 查看版本
codebase-memory-mcp --version

# 更新
codebase-memory-mcp update

# 卸载
codebase-memory-mcp uninstall

---

八、你现在最需要记住的几件事

1. 安装目录是 ~/.local/bin，PATH 要加进去。
2. 如果权限报错，用 sudo chown -R $(whoami):staff ~/.local 修复。
3. 安装后必须重启 Codex，用 /mcp 验证。
4. 使用就是打开项目后说 Index this codebase，然后正常提问。
5. 不想要 3D UI，就改 ~/.cache/codebase-memory-mcp/config.json 里的 ui_enabled 为 false。
6. 它最大的价值是：让 Codex 精确查代码结构，而不是读一大堆文件，从而大幅省 Token。

按这个总结核对一遍，你的安装和使用流程就完整了。