# codebase-memory-mcp 去依赖 SOP

## 目标
在需要使用 `codebase-memory-mcp` 时，尽量绕过 npm / PyPI / `go install` 这些包装层，直接接入仓库 release 的真实二进制。

## 已验证结论
1. `README.md` 明确写了该项目是 **single static binary, zero infrastructure**；默认持久化目录为 `~/.cache/codebase-memory-mcp/`。
2. `README.md` 的 Installation 章节给出了 macOS / Linux / Windows 的预编译包，并明确说明：**All binaries are statically linked — no shared library dependencies**。
3. `README.md` 给出了手动 MCP 配置，`command` 直接指向 `/path/to/codebase-memory-mcp`，`args` 为空数组。
4. `README.md` 的 Build from Source 写明源码构建前置仅有：**C compiler、C++ compiler、zlib、Git**；构建命令是 `scripts/build.sh`，产物在 `build/c/codebase-memory-mcp`。
5. Python 包装层 `pkg/pypi/src/codebase_memory_mcp/_cli.py` 文件头直接说明：**首次运行下载 binary，然后 exec**。
6. Go 包装层 `pkg/go/cmd/codebase-memory-mcp/main.go` 会在缓存里找真实 binary；若不存在，就从 GitHub Releases 下载对应平台压缩包，（如能取到）校验 `checksums.txt`，解压后再 `exec` 真正 binary。
7. npm 包装层由 `pkg/npm/install.js` + `pkg/npm/bin.js` 组成：`postinstall` 下载 GitHub Releases 二进制并尝试校验 checksum；运行时 `bin.js` 只是寻找本地 binary，缺失则再触发一次下载，然后 `spawnSync` 真正 binary。

## 结论翻译成操作策略

### 优先级 1：直接使用 release 二进制
适用：大多数本机 / CI / MCP 客户端集成场景。

做法：
1. 按系统架构从 releases 下载对应压缩包。
2. 用 release 自带的 `checksums.txt` 校验 SHA-256。
3. 解压出 `codebase-memory-mcp`（Windows 为 `.exe`）到稳定路径。
4. 在 MCP 配置里直接把 `command` 指向这个二进制。

README 中的手动配置模板：
```json
{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}
```

这样做的直接收益：
- 少一层 npm/pip/go 包管理器行为；
- 安装路径更可控；
- 排障时面对的就是实际运行的可执行文件。

### 优先级 2：被迫走 pip / npm / go install 时的认知
已读文件里，这三个入口都表现为“薄包装层”：

- **Python**：下载后二进制 `exec`
- **Go**：下载、校验、缓存后二进制 `exec`
- **npm**：`postinstall` 下载；启动时 `spawnSync` 二进制

因此排障时要先分层：
1. 是包装层的 **下载 / 校验 / 解压 / 缓存** 出问题；
2. 还是真实 `codebase-memory-mcp` 二进制本身运行有问题。

如果目标是“去依赖”，通常不要卡在修包装层，直接切回 release 二进制更省事。

### 优先级 3：只有 release 不适用时再源码构建
仅在这些情况下退回源码构建：
- 目标平台没有现成 release；
- 需要修改源码；
- 需要调试底层实现。

最小前置：
- C compiler
- C++ compiler
- zlib
- Git

构建方式：
```bash
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh
# binary at build/c/codebase-memory-mcp
```

## 排障顺序
1. **先确认你到底在运行谁**
   - 直接 release 二进制？
   - pip / npm / go 的包装层？
2. **若是包装层，先查下载、校验、解压、缓存路径**
3. **若目的是降复杂度，直接换成 release 二进制 + 手动 MCP 配置**
4. **只有 release 方案不适用时才退回源码构建**

## 一句话记忆
`codebase-memory-mcp` 的核心是 release 静态单二进制；pip/npm/go 入口主要负责下载并转交给这个二进制，去依赖时优先直连 release binary。

## 本 SOP 的证据文件
- `README.md`
- `pkg/pypi/src/codebase_memory_mcp/_cli.py`
- `pkg/go/cmd/codebase-memory-mcp/main.go`
- `pkg/npm/bin.js`
- `pkg/npm/install.js`