Claude Code × agentmemory：安装与配置指南

摘要：本文详细介绍了 agentmemory 记忆增强工具的安装与配置流程，帮助开发者将 Claude Code 与 agentmemory 无缝集成。内容涵盖前置条件检查、服务安装启动、Claude Code 连接方式（项目级/全局）、LLM 配置选项（免费 BM25/DeepSeek/Anthropic），以及完整的验证流程和常见问题解答，确保用户能够快速搭建并验证记忆增强开发环境。

前置条件

Node.js 18+（推荐通过 Homebrew 安装：brew install node）
Claude Code CLI 已安装并登录
macOS / Linux（Windows 支持实验性）

安装

bash 复制代码

# 全局安装
npm install -g @agentmemory/agentmemory

# 验证安装
agentmemory --version

macOS Homebrew Node 用户注意 ：如果安装后 agentmemory 命令找不到，手动创建软链：
bash 复制代码
ln -sf /opt/homebrew/lib/node_modules/@agentmemory/agentmemory/dist/cli.mjs \
     /opt/homebrew/bin/agentmemory
chmod +x /opt/homebrew/bin/agentmemory

启动服务

agentmemory 是一个常驻服务，需要在独立终端窗口运行：

bash 复制代码

agentmemory

启动后监听两个端口：

端口	用途
`3111`	API 服务（MCP 和 hooks 的通信端口）
`3113`	实时 Viewer（浏览器访问）

验证服务正常：

bash 复制代码

curl http://localhost:3111/agentmemory/health
# 返回 {"status":"healthy",...} 即正常

可选：设置开机自启

bash 复制代码

agentmemory service install

连接 Claude Code

agentmemory 支持两种连接范围：

方式一：按项目连接（推荐）

进入项目目录，执行一次：

bash 复制代码

cd ~/your-project
agentmemory connect claude-code

配置写入 .claude/settings.json（项目级），只对当前项目生效。适合多项目场景，各项目独立管理。

方式二：全局连接

bash 复制代码

agentmemory connect claude-code --global

配置写入 ~/.claude.json，所有 Claude Code 会话均接入记忆。适合单项目或希望统一管理的场景。

撤销全局连接： 从 ~/.claude.json 中删除 mcpServers.agentmemory 字段即可，重新按项目连接。

配置 LLM（可选）

agentmemory 用 LLM 做记忆压缩和合并，将碎片记忆整合为结构化知识。这是可选功能，有三种选择：

选项 A：跳过，纯 BM25（免费）

首次运行时选择 Skip --- BM25-only mode，或在配置文件中不设置任何 LLM key。

召回依赖关键词匹配，基础功能完全可用。

选项 B：DeepSeek（低成本推荐）

DeepSeek 提供 OpenAI 兼容 API，费用极低（约 $0.14/M tokens）。

bash 复制代码

# 编辑配置文件
mkdir -p ~/.agentmemory
cat >> ~/.agentmemory/.env << 'EOF'
OPENAI_API_KEY=sk-你的deepseek-api-key
OPENAI_BASE_URL=https://api.deepseek.com
EOF

安装向导里选择 OpenAI --- gpt，配置文件覆盖 base URL 即可。

选项 C：Anthropic（如果已有 API Key）

bash 复制代码

echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.agentmemory/.env

注意：这里使用的是 Anthropic API Key ，不是 Plan 订阅。两者独立计费。Plan 用户没有自动获得 API Key，需要在 console.anthropic.com 单独创建。

验证完整流程

启动服务：agentmemory
打开新的 Claude Code 会话（在已连接的项目目录）
正常使用 Claude Code 完成一些任务
会话结束后，访问 http://localhost:3113 查看 Viewer
下次会话使用 /agentmemory:recap 查看记录

常见问题

Q：重启电脑后服务不在了？

需要重新运行 agentmemory，或执行 agentmemory service install 设为系统服务。

Q：connect 提示 already wired？

说明已经配置过，使用 agentmemory connect claude-code --force 重新写入。

Q：Viewer 打开是空的？

需要先有记录的会话。当前正在进行的会话数据会在会话结束 hook 触发后写入。