Skip to main content
Glama
deenesjakoruzh
tverney

Agent Memory

by tverney
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

用于 Agent Memory 的文件系统 MCP

mcp-agent-memory MCP server

MCP 服务器，将 agent-memory-daemon 暴露给任何兼容 MCP 的客户端 —— Kiro (CLI & IDE)、Claude Desktop、Cursor 等。

守护进程负责思考（整合 + 提取）；此服务器是一个轻量级的文件系统桥梁，以便智能体可以通过模型上下文协议（Model Context Protocol）读取、追加和搜索记忆。

它是如何协同工作的

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

  • MCP 服务器读取/写入 ~/.agent-memory/ 下的文件

  • 守护进程监视同一目录并运行整合 + 提取任务

  • 它们从不直接通信 —— 文件系统就是契约

Related MCP server: Recall

暴露的工具

工具

用途

memory_read

将 MEMORY.md 索引（及可选的主题文件）加载到智能体的上下文中

memory_append_session

写入会话摘要，供守护进程稍后从中提取记忆

memory_search

在记忆文件中进行子字符串搜索

memory_daemon_status

检查整合守护进程是否正在运行（仅限 macOS LaunchAgent）

安装

npm install -g mcp-agent-memory

快速入门（交互式向导）

设置所有内容（记忆目录、守护进程、客户端配置、日志和 LaunchAgent）的最快方法是使用设置向导：

mcp-agent-memory --setup

它会询问六个问题：

  1. 记忆目录 —— .agent-memory/ 所在的位置（默认为 ~/.agent-memory）

  2. 安装整合守护进程？ —— 如果仅使用 MCP 模式，请回答“no”（智能体可以读取/写入/搜索记忆，但没有自动整合功能）

  3. LLM 后端 —— bedrock、openai 或 kiro（如果您拒绝了守护进程，则跳过此项）

  4. 整合设置 —— min_hours、min_sessions、提取间隔、最大字符数

  5. 运行模式 —— standalone（手动启动）或 launchagent（登录时自动启动，仅限 macOS）

  6. 日志目录 + TTL —— 日志存放位置，以及保留天数（0 = 永久保留）

  7. 客户端注册 —— 在 Kiro、Claude Desktop 和/或 Cursor 配置中自动注册 MCP 服务器（现有的 MCP 条目会被保留）

当您选择 kiro 后端时，向导还会将一个精简的智能体复制到 ~/.kiro/agents/memconsolidate.json，这可以将 Token 使用量减少约 7 倍（请参阅 Kiro 后端）。

当您选择 launchagent 时，向导会检查是否安装了 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)

# macOS LaunchAgent control:
mcp-agent-memory --daemon status       # is the daemon running?
mcp-agent-memory --daemon start        # load and start
mcp-agent-memory --daemon stop         # unload (keeps the plist)
mcp-agent-memory --daemon restart      # stop + start
mcp-agent-memory --daemon remove       # unload and delete the plist

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

手动安装

如果您想跳过向导，可以按照以下步骤手动操作。

安装守护进程（可选）

MCP 服务器可以独立工作 —— 它只是读取和写入 ~/.agent-memory/ 下的文件。记忆会持久保存，但在您添加守护进程之前，它们不会被整合或从会话中提取。

npm install -g agent-memory-daemon

# 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

请参阅 examples/memconsolidate.toml 获取一个现成的配置，该配置符合此 MCP 服务器预期的目录布局。

在登录时运行守护进程（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 不会触动您的配置和记忆文件。

使用 Kiro 作为 LLM 后端

如果您有 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

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

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

Kiro 后端会自动传递 --agent memconsolidate，因此无需进一步配置。在简单的提示词上进行测量：使用精简智能体为 0.01 积分，而默认情况下为 0.07 积分（输出质量相同）。

请参阅 examples/kiro-agent-memconsolidate.json —— 该智能体具有 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
    }
  }
}

然后询问 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"
      }
    }
  }
}

重启 Claude Desktop。memory_* 工具将会出现。

Cursor

使用相同的服务器块添加到 ~/.cursor/mcp.json 中。

环境变量

变量

默认值

描述

MEMORY_DIRECTORY

~/.agent-memory/memory

守护进程存储已整合记忆文件的位置

SESSION_DIRECTORY

~/.agent-memory/sessions

智能体编写的会话摘要存放的位置

两个路径都必须与您的 agent-memory-daemon 配置所使用的路径匹配。

推荐的智能体提示词

告诉您的智能体在对话开始时调用 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 在调用时无需成本，但每个会话在整合期间都会由守护进程的 LLM 进行处理。请保持摘要简洁且结构化。

  • 定期整合或修剪旧的主题文件。运行 mcp-agent-memory --configure —— 如果您的记忆目录超过 25 个文件或 200 KB，它现在会发出警告。

  • 提取后的会话修剪由守护进程处理，而不是由 MCP 服务器处理。请参阅 agent-memory-daemon 的配置，了解在处理后归档或删除会话的选项（防止守护进程永远重新扫描旧会话）。

许可证

MIT

Available Tools

4 tools
memory_append_sessionA

Append a session summary to the sessions directory. The daemon will later extract durable memories from it. Call this at the end of meaningful exchanges. Keep summaries focused on durable findings and decisions (target 300-800 tokens), not play-by-play — longer summaries cost more during consolidation.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesMarkdown-formatted session summary. Use structured headers and bullets for better extraction; avoid verbose prose.
sourceNoOrigin tag, e.g., "kiro", "claude-desktop"

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the daemon will later extract memories and that longer summaries incur higher cost. This adds useful behavioral context beyond the simple append.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, each serves a purpose: action, timing, and content guidelines. No redundancy, front-loaded with core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description provides complete guidance: what, when, how, and cost implications. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage, but description adds significant value by advising on summary focus, token target (300-800), and avoiding verbose prose. This guides the agent beyond schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Append a session summary to the sessions directory' with a specific verb and resource. It distinguishes from sibling read tools (memory_read, memory_search) by being a write operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises 'Call this at the end of meaningful exchanges' and provides guidelines on summary length and content. No exclusion criteria or alternatives mentioned, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_daemon_statusA

Check whether the memory consolidation daemon is running. Reports if the daemon is not installed or not available on this platform.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden. It discloses that the tool reports if the daemon is not installed or not available, indicating it can return multiple status outcomes. No contradictions with annotations (none provided).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The core purpose is front-loaded in the first sentence, and the second adds extra detail concisely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description covers the tool's purpose effectively. It explains what the tool does and the possible outcomes (daemon running, not installed, not available). No obvious gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema description coverage is 100% (trivially). The description does not need to add parameter information. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool checks the running status of the memory consolidation daemon, and also reports if the daemon is not installed or not available on the platform. This distinguishes it from sibling tools (memory_append_session, memory_read, memory_search) which perform different memory operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (checking daemon status) but does not explicitly state when to use this tool versus alternatives. No exclusions or alternatives are mentioned, though sibling tools have different purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_readA

Read the agent memory index (MEMORY.md) and optionally specific topic files. Call with no arguments to load only the lightweight index (cheap). Pass topics only when you need the full content of a specific topic file.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicsNoOptional topic file names to load in full (e.g., ["preferences", "projects"]). Omit to return the index only.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It reveals that calling without arguments is 'cheap' (lightweight), implying topic file retrieval is more expensive. This adds useful context beyond the schema, though it could further clarify error handling or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, then a follow-up sentence with usage details. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one optional parameter, the description covers the main usage. However, without an output schema, it lacks details on the return format (e.g., structure of the index or topic file content). This is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning: it explains that the topics parameter triggers full content retrieval, while omitting it returns the index. This informs the agent of the parameter's purpose beyond data typing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read the agent memory index (MEMORY.md) and optionally specific topic files.' It identifies the action (read) and resource (memory index/topic files), and distinguishes from siblings by specifying the no-arguments vs. topics usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'Call with no arguments to load only the lightweight index (cheap). Pass topics only when you need the full content of a specific topic file.' This tells the agent when to use each mode, effectively differentiating between lightweight and full retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.3
    • Addedmemory_daemon_status
    • Changedmemory_search1 field changed
      • addedInput schema / properties / query / description
        Added value: +"Substring to search for across all memory files (case-insensitive)"
  2. 3 tool updatesv1.0.0
    • First observedmemory_append_session
    • First observedmemory_read
    • First observedmemory_search
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool serves a distinct purpose: appending sessions, checking daemon status, reading memory index, and searching. No overlaps or ambiguities.

Naming Consistency5/5

All tools follow a consistent pattern: 'memory_' prefix followed by a descriptive verb or verb_noun (append_session, daemon_status, read, search). Naming is predictable and clear.

Tool Count5/5

With 4 tools, the surface is concise and well-scoped for a memory management server. Each tool addresses a core operation without redundancy.

Completeness4/5

The tools cover essential operations (append, read, search, status). Missing update/delete might be a minor gap, but the memory consolidation daemon likely handles lifecycle, making this acceptable.

Maintenance

ActivityNo data
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Recall by RecallWorks

    Recallofficial

    RecallWorks
    A
    license
    Not graded
    quality
    C
    maintenance
    Open-source MCP memory server for AI agents — persistent, searchable, tiered memory across sessions. Works over stdio (Cursor, Claude Desktop) or HTTP+SSE. MIT licensed.
    8
    MIT
  • Amber by ambermem

    Amberofficial

    ambermem
    A
    license
    A
    quality
    B
    maintenance
    Gives your AI persistent memory across conversations. Stores facts automatically, finds them by meaning using hybrid search with query expansion, and organizes everything into topics without manual tagging.
    18
    1
    MIT
  • @memofs/mcp-server by memo-fs

    @memofs/mcp-serverofficial

    memo-fs
    A
    license
    Not graded
    quality
    A
    maintenance
    @memofs/mcp-server lets AI coding agents (Claude Code, Claude Desktop, Codex, Cursor, opencode, Gemini CLI, GitHub Copilot, Zed, and any other MCP client) securely read and write MemoFS memory through standard Model Context Protocol tools.
    6
    MIT