Agent Memory

用于 Agent 记忆的文件系统 MCP

MCP 服务，可将 agent-memory-daemon 提供给任何兼容 MCP 的客户端使用——包括 Kiro（CLI 和 IDE）、Claude Desktop、Cursor 等。

守护进程负责思考（整合 + 提取）；此服务则是一个轻量的文件系统桥接层，让 Agent 能通过模型上下文协议读取、追加和搜索记忆。

工作原理

 ┌──────────────┐     MCP/stdio     ┌────────────────────┐     filesystem      ┌────────────────────────┐
 │ Kiro / Claude│ ◄───────────────► │ mcp-server-memory  │ ◄─────────────────► │ agent-memory-daemon    │
 │   / Cursor   │                   │  (this package)    │   ~/.agent-memory/   │  (runs in background)  │
 └──────────────┘                   └────────────────────┘                     └────────────────────────┘

• MCP 服务读取和写入 ~/.agent-memory/ 下的文件
• 守护进程监视同一目录并执行整合 + 提取
• 二者不会直接通信——文件系统就是双方约定的接口

提供的工具

memory_read

读取 Agent 记忆索引（MEMORY.md），并可选读取指定的主题文件。不带参数调用时，只加载轻量索引（开销低）。仅在需要完整读取特定主题文件时传入 topics。

参数	类型	必填	描述
topics	string[]	否	要完整加载的主题文件名（例如 ["preferences", "projects"]）。省略时只返回索引。

memory_append_session

将会话摘要追加到会话目录。守护进程稍后会从中提取持久记忆。在有意义的交流结束时调用。摘要应聚焦于持久发现和决策（目标为 300–800 个令牌），而非逐步记录过程——较长的摘要会增加整合时的开销。

参数	类型	必填	描述
content	string	是	Markdown 格式的会话摘要。使用结构化标题和项目符号有助于提取；避免冗长的文字叙述。
source	string	否	来源标签，例如 "kiro"、"claude-desktop"

memory_search

在记忆文件中搜索子字符串。使用此工具可查找特定事实，而无需加载所有内容。

参数	类型	必填	描述
query	string	是	要在所有记忆文件中搜索的子字符串。

安装

npm install -g mcp-agent-memory

快速开始（交互式向导）

设置所有内容最快的方式——包括记忆目录、守护进程、客户端配置、日志和自动启动服务（macOS LaunchAgent 或 Linux systemd 用户服务）——是使用设置向导：

mcp-agent-memory --setup

向导会询问以下七个问题：

1. 记忆目录——.agent-memory/ 所在位置（默认 ~/.agent-memory）
2. 是否安装整合守护进程？——选择“否”可使用仅 MCP 模式（Agent 可以读取、写入和搜索记忆，但不会自动整合）
3. 大模型后端——bedrock、openai 或 kiro（若不安装守护进程，则跳过）
4. 整合设置——min_hours、min_sessions、提取间隔、最大字符数
5. 运行模式——standalone（手动启动）、launchagent（登录时自动启动，macOS）或 systemd（systemd 用户服务，Linux）。在 Linux 上，只有当 systemctl --user 可访问时，向导才会提供 systemd；否则会退回到 standalone 并说明原因。
6. 日志目录 + TTL——日志保存位置及保留天数（0 = 永久保留）
7. 注册客户端——将 MCP 服务自动注册到 Kiro、Claude Desktop 和/或 Cursor 的配置中（保留已有 MCP 条目）

选择 kiro 后端时，向导还会将一个精简版 Agent 复制到 ~/.kiro/agents/memconsolidate.json，可将令牌用量减少约 7 倍（参见 Kiro 后端）。

选择 launchagent 或 systemd 时，向导会检查是否已安装 agent-memory-daemon（若未安装，则会提供运行 npm install -g 的选项），随后注册并启动 plist / 用户单元。

CLI 参考

mcp-agent-memory                       # run as an MCP server (normal mode — clients spawn it)
mcp-agent-memory --setup               # first-time interactive setup
mcp-agent-memory --configure           # re-run most steps; can add/remove the daemon later
mcp-agent-memory --remove              # interactive uninstall (backup memory, clean configs)

# Auto-start service control (macOS LaunchAgent / Linux systemd user service):
mcp-agent-memory --daemon status       # is the daemon running?
mcp-agent-memory --daemon start        # install and start
mcp-agent-memory --daemon stop         # stop (keeps the plist / unit)
mcp-agent-memory --daemon restart      # stop + start
mcp-agent-memory --daemon remove       # stop and delete the plist / unit

--remove 会保留客户端 MCP 配置中的其他条目，只删除 memory 键。默认情况下，它会将 ~/.agent-memory/ 备份到带时间戳的 .bak-* 目录，以便你恢复已整合的记忆。

手动安装

如果你想跳过向导，可以按以下步骤手动安装。

安装守护进程（可选）

MCP 服务可独立运行——它只会读取和写入 ~/.agent-memory/ 下的文件。记忆会保留，但在添加守护进程之前，记忆不会被整合，也不会从会话中提取。

npm install -g agent-memory-daemon@^2.8.0

# copy the example config
mkdir -p ~/.agent-memory
cp examples/memconsolidate.toml ~/.agent-memory/memconsolidate.toml

# start the daemon
agent-memory-daemon start ~/.agent-memory/memconsolidate.toml

有关与此 MCP 服务所需目录布局匹配的即用型配置，请参阅 examples/memconsolidate.toml。

登录时运行守护进程（macOS）

无需手动启动守护进程，可将其注册为 LaunchAgent：

./scripts/daemon.sh start          # install plist, load it, start at login
./scripts/daemon.sh status         # check if it's running
./scripts/daemon.sh stop           # unload (keeps the plist)
./scripts/daemon.sh remove         # unload and delete the plist

将自定义配置路径作为第二个参数传入：./scripts/daemon.sh start /path/to/config.toml。日志存放在 ~/.agent-memory/logs/daemon.{out,err}.log。remove 不会更改你的配置和记忆文件。

登录时运行守护进程（Linux / systemd）

在 Linux 上，将其注册为 systemd 用户服务：

./scripts/daemon-systemd.sh check      # is a systemd user manager reachable?
./scripts/daemon-systemd.sh start      # write unit, enable, start
./scripts/daemon-systemd.sh status     # check if it's running
./scripts/daemon-systemd.sh stop       # stop (keeps the unit)
./scripts/daemon-systemd.sh remove     # disable and delete the unit

单元文件会写入 ~/.config/systemd/user/agent-memory-daemon.service。日志存放位置与 macOS 相同。用户服务会在登录时启动。若要在没有登录会话时于启动时运行守护进程，请启用 lingering：sudo loginctl enable-linger $USER。

某些主机（容器、沙盒环境或仅限 SSH 的机器）无法访问 systemctl --user。在这种情况下，check/start 会以代码 2 退出并显示说明。请改为独立运行守护进程。

将 Kiro 用作大模型后端

如果你有 Kiro 点数，可以通过 kiro-cli 运行守护进程，无需支付 Bedrock 或 OpenAI API 调用费用。这需要 agent-memory-daemon ≥ 2.7（分支 feat/kiro-backend），该版本新增了 kiro 后端。

[llm_backend]
name = "kiro"
# optional overrides:
# binary = "/custom/path/to/kiro-cli"
# agent = "memconsolidate"          # set to "" to use Kiro's default session context (not recommended)
# model = "claude-sonnet-4-20250514"
# timeoutMs = 300000

使用轻量 Agent 可将令牌用量降低约 7 倍。 默认情况下，每次 kiro-cli chat 调用都会加载 Kiro 的完整系统提示词，以及全局配置中的所有 MCP 工具架构——每次调用约额外消耗 12–18K 个输入令牌。创建一个精简 Agent，即可跳过这些内容：

cp examples/kiro-agent-memconsolidate.json ~/.kiro/agents/memconsolidate.json

Kiro 后端会自动传入 --agent memconsolidate，因此无需进行其他配置。在一个简单提示词上的测量结果：使用轻量 Agent 时为 0.01 点数，默认配置时为 0.07 点数（输出质量相同）。

请参阅 examples/kiro-agent-memconsolidate.json——该 Agent 的配置为 mcpServers: {}、tools: [] 和 useLegacyMcpJson: false，因此不会继承全局 Kiro 配置中的任何内容。

手动配置客户端

--setup 和 --configure 向导会为你处理这些设置。本节适用于想手动完成配置的用户。

Kiro（CLI 和 IDE）

编辑 ~/.kiro/settings/mcp.json：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "disabled": false,
      "timeout": 30000,
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

为什么要设置 autoApprove？ 所有记忆工具都仅执行本地文件系统操作——它们会读取/写入 ~/.agent-memory/ 下的 Markdown 文件，且绝不会发起网络请求。将它们添加到 autoApprove 后，Kiro 就能在无需每次请求你确认的情况下调用它们，这对于实现无缝的“在会话开始时读取记忆”体验至关重要。

然后向 Kiro 提出请求：“读取我的记忆索引。” 或 “记住这件事：我更喜欢 pnpm 而不是 npm。”

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

重启 Claude Desktop。随后会显示 memory_* 工具。

Cursor

将相同的服务配置块（包括 autoApprove）添加到 ~/.cursor/mcp.json。

环境变量

变量	默认值	说明
MEMORY_DIRECTORY	~/.agent-memory/memory	守护进程存储整合后记忆文件的位置
SESSION_DIRECTORY	~/.agent-memory/sessions	Agent 写入的会话摘要存放位置

这两个路径必须与 agent-memory-daemon 配置中的路径一致。

推荐的 Agent 提示词

告诉你的 Agent 在对话开始时调用 memory_read，并在结束时调用 memory_append_session。Kiro 的引导规则示例（~/.kiro/steering/memory.md）：

At the start of every session, call memory_read (no arguments) to load my memory
index. Only pass `topics` when the task genuinely needs the full content of a
specific topic file.

When you learn something durable about me, my projects, or my preferences, call
memory_append_session with a concise markdown summary. Target 300-800 tokens,
use structured headers and bullets (not prose), and focus on durable findings
and decisions — not play-by-play. Verbose summaries cost more during the
daemon's consolidation pass.

Token 使用提示

这三个工具的成本各不相同。以下做法有助于降低推理和整合成本：

• 不带参数调用 memory_read 只会返回 MEMORY.md 索引（通常小于 1 KB）。除非需要完整内容，否则优先使用此方式，而不是使用 topics。
• memory_search 基于子字符串搜索，每个文件最多返回 3 行匹配内容，比加载整个主题文件成本更低。
• memory_append_session 在调用时不产生费用，但守护进程会在整合时使用大模型处理每个会话。请保持摘要简洁且结构清晰。
• 偶尔整合或精简旧主题文件。运行 mcp-agent-memory --configure——现在，当记忆目录超过 25 个文件或 200 KB 时，它会发出警告。
• 提取后的会话清理由守护进程负责，而非 MCP 服务。有关归档或删除已处理会话的选项，请参阅 agent-memory-daemon 的配置（可避免守护进程不断重新扫描旧会话）。

许可证

MIT