{
"canonical_name": "Rumblingb/agent-memory-mcp",
"compilation_id": "pack_eb6e712394374bc08f3bcc0dc62387ed",
"created_at": "2026-05-15T06:04:23.472230+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install mcp",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_866de3c86e604e87886b6109f0d01aa1"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4b441f8b15d440b26bfe53b2e92c741a",
"canonical_name": "Rumblingb/agent-memory-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Rumblingb/agent-memory-mcp",
"slug": "agent-memory-mcp",
"source_packet_id": "phit_9bf0c6cf00994e4f8051c8066f2130bf",
"source_validation_id": "dval_040c2cda697b48e08165081bce8e4198"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "MCP server providing persistent key-value memory for AI agents with TTL and search",
"one_liner_zh": "MCP server providing persistent key-value memory for AI agents with TTL and search",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "agent-memory-mcp",
"title_zh": "agent-memory-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Verifiable Workflow",
"label_zh": "可验证工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-verifiable-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_9bf0c6cf00994e4f8051c8066f2130bf",
"page_model": {
"artifacts": {
"artifact_slug": "agent-memory-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install mcp",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/Rumblingb/agent-memory-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"结构化提取",
"可验证工作流",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "MCP server providing persistent key-value memory for AI agents with TTL and search"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "仓库名 `agent-memory-mcp` 与安装入口 `mcp` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | repo=agent-memory-mcp; install=mcp"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/Rumblingb/agent-memory-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "MCP server providing persistent key-value memory for AI agents with TTL and search",
"title": "agent-memory-mcp 能力包",
"trial_prompt": "# agent-memory-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-memory-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server providing persistent key-value memory for AI agents with TTL and search 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：核心功能详解。围绕“核心功能详解”模拟一次用户任务，不展示安装或运行结果。\n5. page-7：数据存储机制。围绕“数据存储机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“核心功能详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-7\n输入：用户提供的“数据存储机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“核心功能详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-7：Step 5 必须围绕“数据存储机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Rumblingb/agent-memory-mcp\n- https://github.com/Rumblingb/agent-memory-mcp#readme\n- README.md\n- server.py\n- requirements.txt\n- pyproject.toml\n- smithery.yaml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-memory-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "MCP server providing persistent key-value memory for AI agents with TTL and search",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "agent-memory-mcp 能力包",
"risk": "需复核",
"slug": "agent-memory-mcp",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"结构化提取",
"可验证工作流",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Rumblingb/agent-memory-mcp 项目说明书\n\n生成时间：2026-05-12 05:48:40 UTC\n\n## 目录\n\n- [项目概览](#page-1)\n- [安装与配置](#page-2)\n- [系统架构](#page-3)\n- [核心功能详解](#page-4)\n- [存储工具详解](#page-5)\n- [查询工具详解](#page-6)\n- [数据存储机制](#page-7)\n- [使用场景与最佳实践](#page-8)\n- [开发指南](#page-9)\n- [部署指南与常见问题](#page-10)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装与配置](#page-2), [系统架构](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 项目概览\n\n## 1. 项目简介\n\nAgent Memory MCP 是一个基于 MCP（Model Context Protocol）的持久化键值存储服务，专为 AI 智能体设计。该项目由 Nous Research 开发，采用 MIT 开源许可证，旨在解决 AI 智能体在会话之间丢失上下文的核心问题。\n\n**核心价值主张：** AI 智能体在每次新会话开始时会丢失所有上下文信息。Agent Memory MCP 通过提供持久化、可搜索的内存功能，使智能体能够跨会话、跨重启、跨日期记住重要信息。\n\n项目依赖极为精简，仅需 Python 3.10+ 和 `mcp>=1.0.0` 两个核心依赖，数据以 JSON 格式存储在本地磁盘 `~/.agent-memory/` 目录下，完全实现本地优先（Local-first）的设计理念。\n\n## 2. 核心功能特性\n\nAgent Memory MCP 提供了七大核心工具支持完整的内存管理能力：\n\n| 功能 | 描述 |\n|------|------|\n| **memory_remember** | 存储键值对，支持可选的 TTL（生存时间） |\n| **memory_recall** | 检索键值对及其完整元数据 |\n| **memory_forget** | 永久删除指定键 |\n| **memory_search** | 按关键词跨命名空间搜索 |\n| **memory_list_namespaces** | 列出所有命名空间及其条目计数 |\n| **memory_clear_namespace** | 清空整个命名空间 |\n| **memory_stats** | 获取全局存储统计信息 |\n\n**附加特性：**\n\n- **命名空间隔离**：按项目、用户或领域组织内存，支持不同智能体使用独立存储空间\n- **TTL 支持**：条目可设置自动过期时间，精确到秒级精度\n- **模糊搜索**：支持大小写不敏感的子字符串匹配，按访问频率排序\n- **访问追踪**：每条记忆记录创建时间、最后访问时间和访问次数\n- **线程安全**：通过 `fcntl.flock()` 实现文件级锁，确保多进程并发安全访问\n- **零外部依赖**：仅使用 Python 标准库（json、fcntl、pathlib、datetime）\n\n## 3. 系统架构\n\n### 3.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph AI层\n A[\"🤖 AI Agent
(Claude/GPT/Codex)\"]\n end\n \n subgraph MCP协议层\n B[\"📡 MCP Protocol
(stdio JSON-RPC)\"]\n end\n \n subgraph 服务器层\n C[\"⚙️ Agent Memory MCP Server
(server.py)\"]\n \n subgraph 核心模块\n D[\"🗄️ KV Store Engine\"]\n E[\"⏱️ TTL Manager\"]\n F[\"🔍 Search Engine
(substring match)\"]\n end\n end\n \n subgraph 存储层\n G[\"📁 ~/.agent-memory/\"]\n H[\"{namespace}.json\"]\n I[\"_meta.json\"]\n end\n \n A -->|\"remember()
recall()
search()
forget()\"| B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n E --> G\n F --> G\n G --> H\n G --> I\n```\n\n### 3.2 核心组件职责\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| **Server 入口** | `server.py` (main) | 初始化 MCP 服务器，监听 stdio 连接 |\n| **工具路由** | `server.py` (call_tool) | 根据工具名称分发请求到对应处理函数 |\n| **存储引擎** | `server.py` (_read_namespace, _write_namespace) | 读写 JSON 文件，支持文件锁 |\n| **TTL 管理器** | `server.py` (_is_expired, _cleanup_expired) | 检查和清理过期条目 |\n| **搜索引擎** | `server.py` (memory_search) | 子字符串模糊匹配 |\n| **格式化器** | `server.py` (_format_response) | 输出 Markdown 或 JSON 格式响应 |\n\n## 4. 数据存储结构\n\n### 4.1 存储目录布局\n\n所有数据持久化到 `~/.agent-memory/` 目录：\n\n```\n~/.agent-memory/\n├── default.json # 默认命名空间数据\n├── preferences.json # 用户偏好命名空间\n├── research.json # 研究数据命名空间\n├── agent_xxx.json # 智能体专用命名空间\n└── _meta.json # 全局元数据和统计\n```\n\n### 4.2 数据模型\n\n**命名空间文件结构（{namespace}.json）：**\n\n```json\n[\n {\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n }\n]\n```\n\n**元数据文件结构（_meta.json）：**\n\n```json\n{\n \"total_entries\": 156,\n \"namespace_count\": 5,\n \"oldest_entry\": \"2026-04-15\",\n \"newest_entry\": \"2026-05-12\"\n}\n```\n\n### 4.3 常量定义\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CHARACTER_LIMIT` | 25,000 | 单次响应最大字符数 |\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间名称 |\n| `STORAGE_DIR` | `Path.home() / \".agent-memory\"` | 数据存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n\n资料来源：[server.py:27-31]()\n\n## 5. 工具 API 参考\n\n### 5.1 memory_remember\n\n存储键值对，支持可选 TTL。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 键标识符 |\n| `value` | string | ✅ | 要存储的值 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `ttl_seconds` | integer | ❌ | 自动过期秒数 |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n```python\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30天\n)\n```\n\n### 5.2 memory_recall\n\n检索键值对及完整元数据。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要检索的键 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `value` | 存储的值 |\n| `created_at` | 创建时间 |\n| `accessed_at` | 最后访问时间 |\n| `expires_at` | TTL 过期时间（如设置） |\n| `access_count` | 访问次数统计 |\n\n### 5.3 memory_forget\n\n永久删除指定键。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要删除的键 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.4 memory_search\n\n跨命名空间模糊搜索。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `query` | string | ✅ | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | 限定搜索的命名空间 |\n| `limit` | integer | ❌ | 最大返回结果数（默认：10） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**搜索特性：**\n\n- 大小写不敏感匹配\n- 同时匹配键名和值内容\n- 按访问次数降序排序\n\n### 5.5 memory_list_namespaces\n\n列出所有命名空间及其条目统计。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.6 memory_clear_namespace\n\n清空指定命名空间下的所有条目。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `namespace` | string | ✅ | 要清空的命名空间 |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.7 memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `total_entries` | 总条目数（仅活跃条目） |\n| `total_size_bytes` | 存储总大小（字节） |\n| `total_size_human` | 存储总大小（人类可读） |\n| `namespace_count` | 命名空间数量 |\n| `oldest_entry` | 最旧条目创建时间 |\n| `newest_entry` | 最新条目创建时间 |\n| `storage_path` | 存储路径 |\n| `free_tier_limit` | 免费配额限制 |\n| `pro_tier_limit` | Pro 版本限制 |\n\n## 6. 并发与锁机制\n\n```mermaid\nsequenceDiagram\n participant Agent1 as Agent Process 1\n participant Agent2 as Agent Process 2\n participant FS as File System\n \n Agent1->>FS: 请求文件锁 (LOCK_EX)\n Note over FS: 锁定 {namespace}.json\n Agent1->>FS: 读取/写入数据\n Agent1->>FS: 释放文件锁 (LOCK_UN)\n \n Agent2->>FS: 请求文件锁 (LOCK_EX)\n Note over FS: 锁定 {namespace}.json\n Agent2->>FS: 读取/写入数据\n Agent2->>FS: 释放文件锁 (LOCK_UN)\n```\n\nAgent Memory MCP 使用 Python 的 `fcntl.flock()` 实现文件级排他锁，确保多个智能体进程可以安全地并发读写存储文件。锁粒度为单个命名空间文件，而非整个存储目录，这允许不同命名空间的操作并行执行。\n\n## 7. 命名空间安全\n\n命名空间名称通过正则表达式进行安全过滤，防止目录遍历攻击：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n资料来源：[server.py:59-62]()\n\n允许的字符集：`a-zA-Z0-9_. -`，所有非法字符替换为下划线。\n\n## 8. 响应格式\n\n### 8.1 Markdown 格式（默认）\n\n```\n## ✅ Success\n\n**key:** user:theme\n**value:** dark\n**created_at:** 2026-05-12T10:30:00Z\n\n**namespace:** preferences\n**expires_at:** 2026-06-11T10:30:00Z\n```\n\n### 8.2 JSON 格式\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"namespace\": \"preferences\"\n}\n```\n\n## 9. 安装与配置\n\n### 9.1 环境要求\n\n| 要求 | 最小版本 |\n|------|----------|\n| Python | 3.10+ |\n| MCP | >= 1.0.0 |\n\n### 9.2 安装步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install -r requirements.txt\n# 或仅安装 MCP\npip install mcp\n```\n\n资料来源：[README.md:60-68]()\n\n### 9.3 MCP 客户端配置\n\n**Claude Desktop (config.json)：**\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor：**\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n**通用配置（config.yaml）：**\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n### 9.4 测试与开发\n\n```bash\n# 使用 MCP Inspector 测试\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 运行测试套件\npython3 -m pytest tests/\n```\n\n## 10. 使用场景示例\n\n### 10.1 跨会话用户偏好\n\n```python\n# 会话 1：智能体学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\nawait memory_remember(\n key=\"user:currency\",\n value=\"USD\",\n namespace=\"preferences\"\n)\n\n# 会话 2（数天后）：智能体立即回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 10.2 研究积累智能体\n\n```python\n# 存储研究发现\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls. Enterprise: $199/mo. No free tier.\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# 搜索所有竞争对手研究\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n```\n\n### 10.3 智能体草稿板\n\n```python\n# 智能体使用内存作为工作草稿板\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh. Step 3: Update tests.\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 检索当前任务状态\nstate = await memory_recall(\"scratch:task:refactor-auth\", \"agent:code-reviewer\")\n```\n\n## 11. 设计原则\n\n| 原则 | 描述 |\n|------|------|\n| **简单优于复杂** | 定位为类 Redis 的 KV 存储，而非向量数据库，专注于智能体的记忆需求 |\n| **本地优先** | 数据存储在本地机器，无云服务、无 API 密钥、无延迟 |\n| **自描述** | 工具响应默认采用人类可读的 Markdown 格式，JSON 用于程序调用 |\n| **容错设计** | 延迟 TTL 过期、非严格搜索、优雅的错误处理 |\n\n资料来源：[README.md:77-84]()\n\n## 12. 版本与定价\n\n| 版本 | 价格 | 功能限制 |\n|------|------|----------|\n| **免费版** | $0 | 1,000 条目，5 个命名空间 |\n| **Pro 版** | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n## 13. 相关项目\n\n- [Agent Cost Tracker MCP](https://github.com/Rumblingb/agent-cost-tracker-mcp) — AI 智能体 Token 用量和成本追踪\n- [Search Proxy MCP](https://github.com/Rumblingb/search-proxy-mcp) — AI 智能体 Web 搜索\n- [AgentPassport API](https://github.com/Rumblingb/agentpassport-api) — 托管支付中间件\n\n资料来源：[README.md:86-91]()\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [部署指南与常见问题](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 安装与配置\n\n## 概述\n\n`agent-memory-mcp` 是一个基于 Model Context Protocol (MCP) 的持久化键值内存存储服务，专为 AI 代理设计。该项目通过提供 `memory_remember`、`memory_recall`、`memory_forget`、`memory_search` 等工具，使 AI 代理能够在不同会话之间保持上下文记忆。\n\n本页面详细说明该项目的环境要求、安装方式以及在不同 MCP 客户端中的配置方法。\n\n---\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 项目使用类型注解和 `asyncio` 语法 |\n| 操作系统 | macOS / Linux / Windows | 支持 POSIX 文件锁（Unix 系）或 WSL |\n| MCP SDK | ≥ 1.0.0 | 唯一的外部依赖 |\n\n资料来源：[README.md:1]()\n\n### 依赖项\n\n项目仅有单一外部依赖：\n\n```\nmcp>=1.0.0\n```\n\n资料来源：[requirements.txt:1]()\n\n项目完全基于 Python 标准库构建，使用了以下内置模块：\n\n- `json` — 数据序列化\n- `fcntl` — 文件级锁（POSIX 系统并发控制）\n- `pathlib` — 文件路径操作\n- `asyncio` — 异步 I/O 支持\n\n资料来源：[server.py:1-30]()\n\n---\n\n## 安装方式\n\n### 方式一：PyPI 快速安装\n\n对于已发布版本，可直接使用 pip 安装：\n\n```bash\npip install agent-memory-mcp\n```\n\n资料来源：[index.html:1]()\n\n### 方式二：源码安装\n\n适用于开发版本或自定义修改：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install -r requirements.txt\n```\n\n资料来源：[README.md:1]()\n\n如果需要本地安装可编辑版本：\n\n```bash\npip install -e .\n```\n\n---\n\n## MCP 客户端配置\n\n### 通用配置格式\n\n所有 MCP 客户端的配置结构相似，核心参数如下：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `command` | string | ✅ | 执行命令，通常为 `python3` |\n| `args` | array | ✅ | 脚本路径数组 |\n| `description` | string | ❌ | 服务描述文本 |\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n资料来源：[README.md:1]()\n\n---\n\n### Claude Desktop 配置\n\n#### 配置文件位置\n\n| 操作系统 | 配置文件路径 |\n|----------|--------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n#### 配置示例\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n#### 配置验证步骤\n\n1. 保存配置文件\n2. 重启 Claude Desktop 应用\n3. 在新会话中测试工具调用\n\n---\n\n### VS Code / Cursor 配置\n\n#### 配置文件位置\n\n| 编辑器 | 配置文件路径 |\n|--------|--------------|\n| VS Code | 用户级或工作区 `.vscode/mcp.json` |\n| Cursor | `~/.cursor/mcp.json` |\n\n#### 配置示例\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n> **注意**：`cwd` 参数指定了工作目录，确保脚本能够正确找到 `server.py`。\n\n---\n\n### Smithery.ai 部署配置\n\n对于 Smithery.ai 平台部署，项目提供了专用配置文件：\n\n```yaml\n# smithery.yaml\nname: agent-memory-mcp\nversion: 1.0.0\ndescription: Persistent key-value memory for AI agents with TTL, namespaces, and search.\n\nruntime:\n type: python\n entrypoint: server.py\n requirements: requirements.txt\n\ncapabilities:\n tools:\n - memory_remember\n - memory_recall\n - memory_forget\n - memory_search\n - memory_list_namespaces\n - memory_clear_namespace\n - memory_stats\n\nmetadata:\n author: Nous Research\n license: MIT\n repository: https://github.com/nousresearch/agent-memory-mcp\n```\n\n资料来源：[smithery.yaml:1]()\n\n---\n\n## 数据存储架构\n\n### 存储目录\n\n项目将所有数据存储在用户主目录下的隐藏文件夹中：\n\n```\n~/.agent-memory/\n```\n\n资料来源：[server.py:1]()\n\n### 文件结构\n\n| 文件名 | 用途 |\n|--------|------|\n| `{namespace}.json` | 各命名空间的内存条目数组 |\n| `_meta.json` | 全局统计信息和索引 |\n\n#### 条目数据结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n资料来源：[README.md:1]()\n\n### 命名空间安全机制\n\n系统会对命名空间名称进行安全处理，防止目录遍历攻击：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n资料来源：[server.py:1]()\n\n---\n\n## 并发安全机制\n\n项目使用 POSIX 文件锁 (`fcntl.flock()`) 实现多进程并发安全访问：\n\n```mermaid\ngraph TD\n A[Agent Process 1] -->|写入| F[File Lock]\n B[Agent Process 2] -->|等待| F\n C[Agent Process 3] -->|等待| F\n F -->|释放| G[namespace.json]\n F -->|获得锁| A\n```\n\n资料来源：[server.py:1]()\n\n---\n\n## 工具注册与可用工具\n\n服务器启动时会注册以下 7 个工具：\n\n| 工具名称 | 功能 | 破坏性操作 |\n|----------|------|------------|\n| `memory_remember` | 存储键值对 | ❌ |\n| `memory_recall` | 检索键值及元数据 | ❌ |\n| `memory_forget` | 删除指定键 | ✅ |\n| `memory_search` | 关键词跨命名空间搜索 | ❌ |\n| `memory_list_namespaces` | 列出所有命名空间 | ❌ |\n| `memory_clear_namespace` | 清空整个命名空间 | ✅ |\n| `memory_stats` | 获取存储统计信息 | ❌ |\n\n资料来源：[index.html:1]()\n\n---\n\n## MCP Inspector 测试\n\n安装完成后，可使用 MCP Inspector 进行本地测试：\n\n```bash\n# 安装 MCP Inspector（如未安装）\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 或直接运行服务器\npython3 server.py\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 常见问题\n\n### Q: 提示 \"mcp\" 模块未找到？\n\n确保已正确安装依赖：\n\n```bash\npip install mcp\n# 或\npip install -r requirements.txt\n```\n\n### Q: Windows 系统文件锁问题？\n\n项目主要面向 Unix/Linux/macOS 系统。在 Windows 上建议使用 WSL（Windows Subsystem for Linux）环境运行。\n\n### Q: 如何查看存储统计？\n\n使用 `memory_stats` 工具可查看：\n\n- 总条目数\n- 存储大小\n- 命名空间数量\n- 最旧/最新条目时间\n- 已过期条目数\n\n资料来源：[index.html:1]()\n\n---\n\n## 相关链接\n\n| 资源 | 地址 |\n|------|------|\n| GitHub 仓库 | https://github.com/Rumblingb/agent-memory-mcp |\n| 项目官网 | https://nousresearch.com |\n| MIT 许可证 | 见 LICENSE 文件 |\n| Nous Research | https://nousresearch.com |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心功能详解](#page-4), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n \n\n# 系统架构\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值内存存储系统，专为 AI 代理设计。本页面详细说明其整体架构、核心组件、数据存储机制和并发控制策略。\n\n## 1. 架构概述\n\nAgent Memory MCP 采用**分层架构设计**，核心组件包括 MCP 协议层、业务逻辑层和持久化存储层。系统通过标准输入输出（stdio）进行 JSON-RPC 通信，实现与 AI 代理的交互。\n\n```\n┌──────────────────────────────────────────────────────┐\n│ AI 代理层 (Claude/GPT/Codex) │\n│ remember() / recall() / search() / forget() │\n└──────────────────────┬───────────────────────────────┘\n │ MCP 协议 (stdio JSON-RPC)\n┌──────────────────────▼───────────────────────────────┐\n│ Agent Memory MCP 服务器 │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │\n│ │ 键值存储 │ │ TTL │ │ 搜索引擎 │ │\n│ │ 引擎 │ │ 管理器 │ │ (子字符串匹配) │ │\n│ └────┬─────┘ └────┬─────┘ └────────┬──────────┘ │\n│ │ │ │ │\n│ ┌────▼──────────────▼────────────────▼───────────┐ │\n│ │ ~/.agent-memory/ │ │\n│ │ {namespace}.json │ _meta.json │ │\n│ └────────────────────────────────────────────────┘ │\n└───────────────────────────────────────────────────────┘\n```\n\n资料来源：[server.py:1-50]()\n\n## 2. 核心组件\n\n### 2.1 MCP 服务器层\n\nMCP 服务器是系统的核心入口点，负责处理协议级别的通信。\n\n```python\nserver = Server(\n name=\"agent-memory\",\n version=\"1.0.0\",\n instructions=\"Agent Memory MCP — Persistent key-value memory for AI agents with TTL, namespaces, and search.\",\n website_url=\"https://github.com/nousresearch/agent-memory-mcp\",\n)\n```\n\n| 属性 | 值 | 说明 |\n|------|-----|------|\n| `name` | agent-memory | 服务器标识名 |\n| `version` | 1.0.0 | 语义化版本号 |\n| `instructions` | 协议说明 | MCP 客户端可见的指令 |\n| `website_url` | GitHub 仓库地址 | 项目主页 |\n\n资料来源：[server.py:175-181]()\n\n### 2.2 工具注册与路由\n\n系统定义了 7 个工具，全部通过 `@server.list_tools()` 装饰器注册，并通过 `@server.call_tool()` 统一路由分发。\n\n```python\n@server.list_tools()\nasync def list_tools() -> List[Tool]:\n return [\n Tool(name=\"memory_remember\", ...),\n Tool(name=\"memory_recall\", ...),\n Tool(name=\"memory_forget\", ...),\n Tool(name=\"memory_search\", ...),\n Tool(name=\"memory_list_namespaces\", ...),\n Tool(name=\"memory_clear_namespace\", ...),\n Tool(name=\"memory_stats\", ...),\n ]\n\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n if name == \"memory_remember\":\n text = memory_remember(**arguments, fmt=fmt)\n elif name == \"memory_recall\":\n text = memory_recall(**arguments, fmt=fmt)\n # ... 其他工具路由\n```\n\n资料来源：[server.py:183-240]()\n\n### 2.3 工具注解系统\n\n每个工具都携带元数据注解，用于指示工具的行为特性：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n- **readOnlyHint**: 是否为只读操作\n- **destructiveHint**: 是否为破坏性操作\n- **idempotentHint**: 是否为幂等操作\n- **openWorldHint**: 是否与外部世界交互\n\n资料来源：[server.py:95-170]()\n\n## 3. 数据存储架构\n\n### 3.1 存储目录结构\n\n数据默认存储在用户家目录下的 `.agent-memory` 文件夹中：\n\n```\n~/.agent-memory/\n├── {namespace}.json # 每个命名空间一个文件\n└── _meta.json # 全局元数据\n```\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间名称 |\n| `STORAGE_DIR` | `Path.home() / \".agent-memory\"` | 存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n| `CHARACTER_LIMIT` | 25,000 | 单次响应字符限制 |\n\n资料来源：[server.py:52-59]()\n\n### 3.2 文件命名空间隔离\n\n命名空间文件名经过安全处理，防止目录遍历攻击：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n \"\"\"Return the full path for a namespace JSON file.\"\"\"\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n资料来源：[server.py:69-76]()\n\n### 3.3 内存条目结构\n\n每个内存条目（Entry）包含以下字段：\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `key` | string | 唯一键标识符 |\n| `value` | string | 存储的值 |\n| `created_at` | ISO 8601 时间戳 | 创建时间 |\n| `accessed_at` | ISO 8601 时间戳 | 最后访问时间 |\n| `expires_at` | ISO 8601 时间戳 | TTL 过期时间（可选） |\n| `access_count` | integer | 访问计数 |\n\n资料来源：[server.py:82-100]()\n\n### 3.4 元数据文件结构\n\n`_meta.json` 存储全局统计信息：\n\n```json\n{\n \"total_entries\": 156,\n \"namespace_count\": 5,\n \"last_updated\": \"2026-05-12T15:00:00Z\"\n}\n```\n\n## 4. 并发控制机制\n\n### 4.1 文件锁机制\n\n系统使用 `fcntl.flock()` 实现进程级别的文件锁，确保多代理并发访问的安全性：\n\n```python\n@contextmanager\ndef _locked(namespace: Optional[str] = None) -> Iterator[None]:\n \"\"\"Context manager for file-level locking.\"\"\"\n if namespace:\n path = _namespace_path(namespace)\n with open(path, \"a+\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n else:\n # Lock the meta file for global operations\n with open(_meta_path(), \"a+\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n资料来源：[server.py:117-137]()\n\n### 4.2 锁粒度设计\n\n| 操作类型 | 锁范围 | 说明 |\n|---------|-------|------|\n| 单命名空间操作 | 命名空间文件锁 | 仅锁定特定命名空间 |\n| 全局统计操作 | 元数据文件锁 | 锁定 `_meta.json` |\n| 跨命名空间操作 | 无锁（读操作） | 使用懒加载避免死锁 |\n\n```mermaid\ngraph TD\n A[请求进入] --> B{操作类型?}\n B -->|单命名空间| C[锁定 namespace.json]\n B -->|全局统计| D[锁定 _meta.json]\n B -->|跨命名空间搜索| E[遍历+无锁读]\n C --> F[执行操作]\n D --> F\n E --> F\n F --> G[释放锁]\n G --> H[返回结果]\n```\n\n## 5. 业务逻辑层\n\n### 5.1 核心功能模块\n\n| 模块 | 功能 | 文件路径 |\n|------|------|----------|\n| `_ensure_storage()` | 确保存储目录存在 | server.py |\n| `_namespace_path()` | 生成命名空间文件路径 | server.py |\n| `_read_namespace()` | 读取命名空间数据 | server.py |\n| `_write_namespace()` | 写入命名空间数据 | server.py |\n| `_is_expired()` | 检查 TTL 是否过期 | server.py |\n| `_format_response()` | 格式化响应输出 | server.py |\n| `_recalc_meta()` | 重新计算元数据 | server.py |\n\n### 5.2 工具实现流程\n\n#### memory_remember 流程\n\n```mermaid\ngraph TD\n A[memory_remember 调用] --> B[验证 key 和 value]\n B --> C{命名空间存在?}\n C -->|否| D[自动创建命名空间]\n C -->|是| E[获取写锁]\n D --> E\n E --> F[构建新条目]\n F --> G[追加/更新到数组]\n G --> H[写入 JSON 文件]\n H --> I[释放锁]\n I --> J[返回成功响应]\n```\n\n资料来源：[server.py:140-200]()\n\n#### memory_recall 流程\n\n```mermaid\ngraph TD\n A[memory_recall 调用] --> B[获取读锁]\n B --> C[读取命名空间 JSON]\n C --> D[查找指定 key]\n D --> E{条目存在?}\n E -->|否| F[返回错误]\n E -->|是| G{TTL 已过期?}\n G -->|是| H[懒删除并返回错误]\n G -->|否| I[更新 accessed_at 和 access_count]\n I --> J[写入文件]\n J --> K[释放锁]\n K --> L[返回完整条目]\n```\n\n资料来源：[server.py:200-260]()\n\n### 5.3 TTL 管理机制\n\n系统采用**懒过期策略**，只在访问时检查 TTL：\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"Check if an entry has expired based on its TTL.\"\"\"\n if \"expires_at\" not in entry or entry[\"expires_at\"] is None:\n return False\n expires = datetime.fromisoformat(entry[\"expires_at\"])\n return datetime.now(timezone.utc) > expires\n```\n\n资料来源：[server.py:103-110]()\n\n| 策略 | 说明 |\n|------|------|\n| 写入时设置 | 创建条目时指定 `expires_at` |\n| 访问时检查 | recall 操作触发过期检查 |\n| 懒删除 | 过期条目在被访问时删除，不主动清理 |\n\n### 5.4 搜索机制\n\n```python\ndef _search_entries(entries: List[Dict], query: str, limit: int) -> List[Dict]:\n \"\"\"Search entries by keyword substring in keys and values.\"\"\"\n results = []\n for entry in entries:\n if _is_expired(entry):\n continue\n if query.lower() in entry[\"key\"].lower() or query.lower() in entry[\"value\"].lower():\n results.append(entry)\n results.sort(key=lambda e: e.get(\"access_count\", 0), reverse=True)\n return results[:limit]\n```\n\n资料来源：[server.py:110-125]()\n\n搜索特性：\n- **子字符串匹配**：支持关键词部分匹配\n- **大小写不敏感**：自动转换为小写比较\n- **跨键值搜索**：同时搜索 key 和 value 字段\n- **访问频率排序**：按 access_count 降序返回结果\n\n## 6. 响应格式化系统\n\n### 6.1 格式类型\n\n系统支持两种响应格式，通过 `format` 参数切换：\n\n| 格式 | 说明 | Content-Type |\n|------|------|--------------|\n| `markdown` | 人类可读的 Markdown 格式（默认） | text/markdown |\n| `json` | 程序可读的 JSON 格式 | application/json |\n\n### 6.2 Markdown 格式化示例\n\n```python\ndef _format_response(result: Dict[str, Any], fmt: Optional[str] = None) -> str:\n if fmt == \"json\":\n return json.dumps(result, indent=2)\n # Markdown (default)\n lines = []\n status = result.get(\"status\", \"ok\")\n if status == \"error\":\n lines.append(f\"## ❌ Error\")\n lines.append(f\"**{result.get('error', 'Unknown error')}**\")\n else:\n lines.append(f\"## ✅ Success\")\n # ... 格式化其他字段\n return \"\\n\".join(lines)\n```\n\n资料来源：[server.py:250-290]()\n\n## 7. 入口点设计\n\n### 7.1 主程序流程\n\n```python\nasync def main() -> None:\n _ensure_storage() # 确保存储目录存在\n async with stdio_server() as (read_stream, write_stream):\n await server.run(\n read_stream,\n write_stream,\n server.create_initialization_options(),\n )\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[server.py:310-325]()\n\n### 7.2 启动流程图\n\n```mermaid\nsequenceDiagram\n participant C as MCP 客户端\n participant S as Agent Memory MCP\n participant FS as 文件系统\n \n C->>S: 启动进程\n S->>FS: 创建 ~/.agent-memory/ 目录\n FS-->>S: 目录就绪\n S->>C: STDIO 服务就绪\n C->>S: JSON-RPC 请求\n S->>S: 处理工具调用\n S->>FS: 读写 JSON 文件\n S-->>C: JSON-RPC 响应\n```\n\n## 8. 错误处理机制\n\n### 8.1 错误响应结构\n\n```python\ndef _error(message: str, fmt: Optional[str] = None) -> str:\n result = {\"status\": \"error\", \"error\": message, \"isError\": True}\n return _format_response(result, fmt)\n```\n\n### 8.2 异常捕获\n\n```python\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n try:\n # 工具执行逻辑\n ...\n except Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:225-237]()\n\n### 8.3 错误类型\n\n| 错误场景 | HTTP 类比状态码 | 说明 |\n|---------|----------------|------|\n| Key 不存在 | 404 | 尝试访问不存在的 key |\n| 命名空间错误 | 400 | 无效的命名空间名称 |\n| 内部错误 | 500 | 文件系统或处理异常 |\n\n## 9. 依赖架构\n\n### 9.1 外部依赖\n\n```\nmcp>=1.0.0\n```\n\n系统仅依赖 MCP SDK，所有其他功能均使用 Python 标准库实现。\n\n### 9.2 标准库使用\n\n| 模块 | 用途 |\n|------|------|\n| `asyncio` | 异步 I/O 支持 |\n| `fcntl` | 文件锁实现 |\n| `json` | 数据序列化 |\n| `pathlib` | 跨平台路径处理 |\n| `re` | 命名空间名称验证 |\n| `datetime` | 时间戳处理 |\n\n资料来源：[server.py:10-28]()\n\n## 10. 配置常量汇总\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CHARACTER_LIMIT` | 25,000 | 响应字符数上限 |\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间 |\n| `STORAGE_DIR` | `~/.agent-memory/` | 存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n\n资料来源：[server.py:52-59]()\n\n## 11. 架构优势\n\n| 特性 | 实现方式 | 优势 |\n|------|----------|------|\n| **本地优先** | JSON 文件存储 | 无需网络，数据本地化 |\n| **零依赖** | 仅使用标准库 | 部署简单，兼容性强 |\n| **并发安全** | fcntl 文件锁 | 多进程安全访问 |\n| **命名隔离** | 文件级命名空间 | 避免命名冲突 |\n| **幂等操作** | 注解声明 | 便于 MCP 客户端优化 |\n\n## 12. 扩展方向\n\n当前架构支持以下潜在扩展：\n\n1. **压缩存储**：对 JSON 文件进行 gzip 压缩\n2. **索引优化**：为高频查询字段建立索引\n3. **TTL 后台清理**：定时任务主动清理过期条目\n4. **审计日志**：记录所有操作的详细日志\n5. **加密存储**：对敏感数据进行加密\n\n---\n\n\n\n## 核心功能详解\n\n### 相关页面\n\n相关主题：[存储工具详解](#page-5), [查询工具详解](#page-6), [系统架构](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 核心功能详解\n\n## 概述\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值存储系统，专为 AI 代理设计。该项目由 Nous Research 开发，采用 MIT 开源许可证，旨在解决 AI 代理在会话之间丢失所有上下文的问题。\n\n核心价值主张：赋予 AI 代理持久化、可搜索的记忆能力，使其能够在会话重启、崩溃和上下文窗口限制中存活下来。\n\n资料来源：[README.md]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[AI 代理
Claude/GPT/Codex] --> B[MCP 协议
stdio JSON-RPC]\n B --> C[Agent Memory MCP 服务器]\n C --> D[键值存储引擎]\n C --> E[TTL 管理器]\n C --> F[搜索引擎
子串匹配]\n D --> G[~/.agent-memory/]\n E --> G\n F --> G\n G --> H[{namespace}.json]\n G --> I[_meta.json]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 实现方式 |\n|------|------|----------|\n| **MCP Server** | 处理 MCP 协议通信 | `mcp.server.Server` |\n| **KV Store Engine** | 键值存储读写 | JSON 文件操作 |\n| **TTL Manager** | 过期时间管理 | 懒清理机制 |\n| **Search Engine** | 跨命名空间搜索 | 子串匹配 + 访问计数排序 |\n| **File Locking** | 并发安全 | `fcntl.flock()` POSIX 文件锁 |\n\n资料来源：[server.py:1-50]()\n\n## 核心工具详解\n\n系统提供 7 个结构化工具，覆盖完整的内存管理生命周期。\n\n资料来源：[server.py:140-280]()\n\n### 工具概览表\n\n| 工具名称 | 功能描述 | 只读 | 破坏性 | 幂等性 |\n|----------|----------|------|--------|--------|\n| `memory_remember` | 存储键值对 | ❌ | ❌ | ❌ |\n| `memory_recall` | 检索键值对 | ✅ | ❌ | ✅ |\n| `memory_forget` | 删除键值对 | ❌ | ✅ | ✅ |\n| `memory_search` | 关键词搜索 | ✅ | ❌ | ✅ |\n| `memory_list_namespaces` | 列出命名空间 | ✅ | ❌ | ✅ |\n| `memory_clear_namespace` | 清空命名空间 | ❌ | ✅ | ❌ |\n| `memory_stats` | 获取统计信息 | ✅ | ❌ | ✅ |\n\n资料来源：[server.py:220-280]()\n\n---\n\n### 1. memory_remember\n\n**功能**：存储值到持久化内存命名空间，支持可选的 TTL（生存时间）。\n\n```python\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30 days\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 记忆条目的唯一标识符 |\n| `value` | string | ✅ | - | 要存储的内容 |\n| `namespace` | string | ❌ | `\"default\"` | 存储的命名空间 |\n| `ttl_seconds` | integer | ❌ | `null` | 自动过期秒数 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**返回值结构**：\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"namespace\": \"preferences\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\"\n}\n```\n\n资料来源：[server.py:142-175]()\n\n---\n\n### 2. memory_recall\n\n**功能**：按键检索值，返回完整元数据。\n\n```python\nresult = await memory_recall(\n key=\"user:timezone\",\n namespace=\"preferences\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `value` | string | 存储的值 |\n| `created_at` | string | 创建时间 ISO 8601 |\n| `accessed_at` | string | 最后访问时间 |\n| `expires_at` | string | TTL 过期时间（若有） |\n| `access_count` | integer | 访问次数 |\n\n资料来源：[server.py:176-200]()\n\n---\n\n### 3. memory_forget\n\n**功能**：永久删除指定键。\n\n```python\nresult = await memory_forget(\n key=\"temp:session:123\",\n namespace=\"sessions\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n资料来源：[server.py:201-215]()\n\n---\n\n### 4. memory_search\n\n**功能**：跨命名空间关键词搜索，大小写不敏感，按访问次数排序。\n\n```python\nresults = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\",\n limit=10\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子串 |\n| `namespace` | string | ❌ | 全部 | 可选：限制搜索范围 |\n| `limit` | integer | ❌ | `10` | 最大返回结果数 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**搜索算法**：\n\n1. 遍历指定命名空间（或全部命名空间）的 JSON 文件\n2. 对每个条目进行子串匹配，同时检查 key 和 value\n3. 懒清理已过期的 TTL 条目\n4. 按 `access_count` 降序排序返回结果\n\n资料来源：[server.py:230-260]()\n\n---\n\n### 5. memory_list_namespaces\n\n**功能**：列出所有内存命名空间及活跃/过期条目计数。\n\n```python\nnamespaces = await memory_list_namespaces()\n```\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | string | 命名空间名称 |\n| `active_count` | integer | 活跃条目数 |\n| `expired_count` | integer | 过期条目数 |\n| `file_path` | string | 对应 JSON 文件路径 |\n\n资料来源：[server.py:261-275]()\n\n---\n\n### 6. memory_clear_namespace\n\n**功能**：永久删除命名空间中的所有条目。\n\n```python\nawait memory_clear_namespace(namespace=\"agent:temp\")\n# → \"Cleared 156 entries from 'agent:temp'\"\n```\n\n**警告**：此操作不可撤销。\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n资料来源：[server.py:276-295]()\n\n---\n\n### 7. memory_stats\n\n**功能**：获取全局存储统计信息。\n\n```python\nstats = await memory_stats(format=\"markdown\")\n```\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `total_entries` | integer | 总条目数 |\n| `namespace_count` | integer | 命名空间数量 |\n| `storage_size` | string | 存储大小（如 \"2.4 MB\"） |\n| `oldest_entry` | string | 最旧条目时间 |\n| `newest_entry` | string | 最新条目时间 |\n| `expired_entries` | integer | 过期条目数 |\n| `tier` | string | 当前套餐（free/pro） |\n\n资料来源：[server.py:296-315]()\n\n## 数据存储机制\n\n### 存储目录结构\n\n```\n~/.agent-memory/\n├── default.json # 默认命名空间\n├── preferences.json # 用户偏好命名空间\n├── research.json # 研究数据命名空间\n└── _meta.json # 全局元数据\n```\n\n**存储路径**：`Path.home() / \".agent-memory\"` = `~/.agent-memory/`\n\n资料来源：[server.py:38-45]()\n\n### 命名空间文件安全\n\n命名空间名称经过严格的安全过滤：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n允许的字符：`a-zA-Z0-9_.`-`，其他字符替换为下划线。空名称回退到 `default`。\n\n资料来源：[server.py:58-62]()\n\n### 条目数据模型\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 生成时机 |\n|------|------|----------|\n| `key` | 唯一标识符 | 写入时指定 |\n| `value` | 存储内容 | 写入时指定 |\n| `created_at` | 创建时间 | 首次写入 |\n| `accessed_at` | 最后访问时间 | 每次 recall |\n| `expires_at` | TTL 过期时间 | 设置 ttl_seconds 时 |\n| `access_count` | 访问计数器 | 每次 recall 递增 |\n\n资料来源：[server.py:100-130]()\n\n### 元数据文件结构\n\n```json\n{\n \"total_entries\": 1523,\n \"namespace_count\": 5,\n \"last_updated\": \"2026-05-12T15:00:00Z\"\n}\n```\n\n资料来源：[server.py:120-130]()\n\n## TTL 生命周期管理\n\n### TTL 工作流程\n\n```mermaid\ngraph LR\n A[memory_remember
ttl_seconds=3600] --> B[计算 expires_at]\n B --> C[存储条目]\n C --> D[recall/forget 时检查]\n D -->|未过期| E[返回结果]\n D -->|已过期| F[懒清理]\n F --> G[标记 expired=true]\n G --> H[下次扫描时删除]\n```\n\n### 懒清理机制\n\n系统采用懒清理策略，不主动后台任务清理过期条目：\n\n1. **读取时清理**：`memory_recall`、`memory_search` 执行时检查过期状态\n2. **写入时清理**：扫描命名空间时移除过期条目\n3. **不依赖外部调度**：无需 cron 或定时任务\n\n**优点**：降低系统复杂度，减少资源占用\n**权衡**：过期条目占用磁盘空间直到下次访问\n\n资料来源：[server.py:85-95]()\n\n## 并发控制\n\n### 文件锁机制\n\n系统使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全：\n\n```python\nwith _file_lock(namespace):\n # 读或写操作\n data = _read_namespace(namespace)\n _write_namespace(namespace, data)\n```\n\n**锁粒度**：命名空间级别（每个 JSON 文件独立锁）\n\n**并发场景支持**：\n\n| 场景 | 安全性 | 说明 |\n|------|--------|------|\n| 多进程读取 | ✅ | 读锁可共享 |\n| 多进程写入 | ✅ | 写锁互斥 |\n| 读同时写 | ✅ | 读写互斥 |\n| 跨命名空间 | ✅ | 无锁竞争 |\n\n资料来源：[server.py:70-80]()\n\n### 并发操作时序图\n\n```mermaid\nsequenceDiagram\n participant Agent1 as 代理进程 A\n participant Lock as 文件锁\n participant Agent2 as 代理进程 B\n \n Agent1->>Lock: 申请写锁 (LOCK_EX)\n Lock-->>Agent1: 锁授予\n Agent1->>Agent1: 读取 JSON\n Agent1->>Agent1: 修改数据\n Agent1->>Agent1: 写入 JSON\n Agent1->>Lock: 释放锁 (LOCK_UN)\n \n Agent2->>Lock: 申请写锁 (LOCK_EX)\n Lock-->>Agent2: 锁授予（等待后）\n Agent2->>Agent2: 读取 JSON\n Agent2->>Agent2: 修改数据\n Agent2->>Agent2: 写入 JSON\n Agent2->>Lock: 释放锁\n```\n\n## 响应格式化\n\n### 支持格式\n\n| 格式 | 说明 | 使用场景 |\n|------|------|----------|\n| `markdown` | 人类可读格式 | 调试、日志查看 |\n| `json` | 程序化解析 | 自动化流程 |\n\n### Markdown 格式示例\n\n```\n## ✅ Success\n\n**key:** user:theme\n**namespace:** preferences\n**created_at:** 2026-05-12T10:30:00Z\n**expires_at:** 2026-06-11T10:30:00Z\n```\n\n### JSON 格式示例\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"namespace\": \"preferences\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\"\n}\n```\n\n### 错误响应\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"Key 'xyz' not found in namespace 'default'\",\n \"isError\": true\n}\n```\n\n资料来源：[server.py:130-160]()\n\n## 定价与限制\n\n### 套餐对比\n\n| 套餐 | 价格 | 条目限制 | 命名空间限制 | 支持 |\n|------|------|----------|--------------|------|\n| **Free** | $0 | 1,000 条 | 5 个 | 社区支持 |\n| **Pro** | $19/月 | 无限 | 无限 | 优先支持 |\n\n资料来源：[smithery.yaml]()\n资料来源：[index.html]()\n\n## 依赖要求\n\n### 系统要求\n\n| 依赖 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 运行时环境 |\n| mcp | >=1.0.0 | MCP SDK 依赖 |\n\n### requirements.txt\n\n```\nmcp>=1.0.0\n```\n\n**无外部依赖**：系统使用 Python 标准库（`json`, `fcntl`, `pathlib`, `datetime`），仅需 MCP SDK。\n\n资料来源：[requirements.txt]()\n\n## 设计原则\n\n| 原则 | 实现方式 |\n|------|----------|\n| **简洁优先** | Redis 风格 KV，非向量数据库 |\n| **本地优先** | 数据存储在本地，无云服务/API密钥 |\n| **自描述** | 工具响应默认人类可读 markdown |\n| **容错性** | 懒 TTL 过期、非严格搜索、优雅错误处理 |\n\n资料来源：[README.md]()\n\n## MCP 配置示例\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n### VS Code / Cursor\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n### MCP Inspector 测试\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md]()\n\n## 使用场景\n\n### 跨会话用户偏好\n\n```python\n# 会话 1：代理学习用户偏好\nawait memory_remember(key=\"user:timezone\", value=\"America/Chicago\", namespace=\"preferences\")\nawait memory_remember(key=\"user:currency\", value=\"USD\", namespace=\"preferences\")\n\n# 会话 2（数天后）：代理即时回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 研究积累代理\n\n```python\n# 代理存储研究发现\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# 后续：搜索所有竞争对手研究\nfindings = await memory_search(query=\"competitor pricing\", namespace=\"research\")\n```\n\n### 代理临时便签\n\n```python\n# 代理使用内存作为工作便签\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh.\",\n namespace=\"agent:code-reviewer\"\n)\n```\n\n## 版本信息\n\n| 属性 | 值 |\n|------|-----|\n| 版本号 | 1.0.0 |\n| MCP Server 名称 | agent-memory |\n| 许可证 | MIT |\n| 开发者 | Nous Research |\n| GitHub | [nousresearch/agent-memory-mcp](https://github.com/nousresearch/agent-memory-mcp) |\n\n资料来源：[server.py:135-140]()\n资料来源：[smithery.yaml]()\n\n---\n\n\n\n## 存储工具详解\n\n### 相关页面\n\n相关主题：[查询工具详解](#page-6), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n \n\n# 存储工具详解\n\n## 概述\n\nagent-memory-mcp 的存储工具是整个系统的核心模块，提供了基于 MCP（Model Context Protocol）的持久化键值存储能力。这些工具使 AI Agent 能够在不同会话之间保持记忆，支持命名空间隔离、TTL（Time-To-Live）自动过期、模糊搜索和并发安全访问。\n\n存储系统采用本地 JSON 文件存储方案，数据持久化在 `~/.agent-memory/` 目录下，每个命名空间对应一个独立的 JSON 文件，配合元数据文件 `_meta.json` 记录全局统计信息。资料来源：[server.py:1-30]()\n\n## 架构设计\n\n### 系统组件\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP 客户端 (AI Agent) │\n│ remember / recall / forget / search / list / clear / stats │\n└───────────────────────────┬─────────────────────────────────┘\n │ MCP Protocol (stdio JSON-RPC)\n┌───────────────────────────▼─────────────────────────────────┐\n│ Agent Memory MCP Server │\n│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │\n│ │ KV 存储 │ │ TTL 管理 │ │ 搜索引擎 │ │\n│ │ 引擎 │ │ 处理器 │ │ (子字符串匹配) │ │\n│ └──────┬─────┘ └─────┬──────┘ └─────────┬──────────┘ │\n│ │ │ │ │\n│ ┌──────▼───────────────▼───────────────────▼──────────┐ │\n│ │ ~/.agent-memory/ │ │\n│ │ {namespace}.json │ _meta.json │ │\n│ └────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 存储目录结构\n\n| 文件 | 用途 | 描述 |\n|------|------|------|\n| `{namespace}.json` | 命名空间数据 | 每个命名空间独立存储，包含内存条目数组 |\n| `_meta.json` | 全局元数据 | 记录总条目数、命名空间数量等全局统计 |\n\n资料来源：[server.py:47-50]()\n\n## 存储工具清单\n\n### 工具功能对照表\n\n| 工具名称 | 功能描述 | 读取操作 | 写入操作 | 删除操作 |\n|----------|----------|----------|----------|----------|\n| `memory_remember` | 存储键值对（支持TTL） | ❌ | ✅ | ❌ |\n| `memory_recall` | 检索键值及元数据 | ✅ | ❌ | ❌ |\n| `memory_forget` | 删除指定键 | ❌ | ❌ | ✅ |\n| `memory_search` | 跨命名空间关键词搜索 | ✅ | ❌ | ❌ |\n| `memory_list_namespaces` | 列出所有命名空间 | ✅ | ❌ | ❌ |\n| `memory_clear_namespace` | 清空整个命名空间 | ❌ | ❌ | ✅ |\n| `memory_stats` | 获取全局存储统计 | ✅ | ❌ | ❌ |\n\n## 核心 API 参数详解\n\n### 1. memory_remember\n\n存储一个新的键值对到指定命名空间，支持可选的 TTL 自动过期时间。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 内存条目的唯一标识符 |\n| `value` | string | ✅ | - | 要存储的实际内容 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `ttl_seconds` | integer | ❌ | `null` | 存活秒数，设置后自动过期 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式：`\"markdown\"` 或 `\"json\"` |\n\n**条目数据结构：**\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 1\n}\n```\n\n资料来源：[server.py:54-59]()\n\n### 2. memory_recall\n\n根据键名检索存储的值，同时返回完整的访问元数据。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键名 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回的元数据字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `value` | string | 存储的实际值 |\n| `created_at` | string | 创建时间戳（ISO 8601） |\n| `accessed_at` | string | 最后访问时间戳 |\n| `expires_at` | string/null | TTL 过期时间（未设置则为 null） |\n| `access_count` | integer | 累计访问次数 |\n\n每次调用 `memory_recall` 会自动更新 `accessed_at` 和 `access_count`，实现访问追踪功能。资料来源：[server.py:63-67]()\n\n### 3. memory_forget\n\n永久删除指定的键值对。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键名 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `false` | 修改性操作 |\n| `destructiveHint` | `true` | 破坏性操作 |\n| `idempotentHint` | `true` | 重复执行结果一致 |\n\n资料来源：[server.py:73-83]()\n\n### 4. memory_search\n\n在所有命名空间或指定命名空间中搜索关键词，匹配键名和值的子字符串。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | `null` | 限定搜索范围（为空则搜索全部） |\n| `limit` | integer | ❌ | `10` | 最大返回结果数 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**搜索特性：**\n\n- **大小写不敏感**：搜索 `\"User\"` 可匹配 `\"user\"`、`\"USER\"` 等\n- **子字符串匹配**：搜索 `\"them\"` 可匹配 `\"theme\"`、`\"something\"` 等\n- **全字段匹配**：同时匹配 `key` 和 `value`\n- **结果排序**：按 `access_count` 降序排列\n\n**搜索流程：**\n\n```mermaid\ngraph TD\n A[输入搜索查询] --> B{指定 namespace?}\n B -->|是| C[只扫描指定命名空间]\n B -->|否| D[扫描所有命名空间 JSON 文件]\n C --> E[遍历条目列表]\n D --> E\n E --> F{key 或 value 包含查询?
大小写不敏感}\n F -->|是| G[加入结果集]\n F -->|否| H[跳过]\n G --> I{access_count 高于当前结果?}\n I -->|是| J[优先排序]\n I -->|否| K[保持原位置]\n J --> L{达到 limit?}\n K --> L\n L -->|否| E\n L -->|是| M[返回排序结果]\n```\n\n资料来源：[server.py:88-110]()\n\n### 5. memory_list_namespaces\n\n列出所有已存在的命名空间及其条目统计。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回数据：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | string | 命名空间名称 |\n| `active_count` | integer | 未过期的条目数 |\n| `expired_count` | integer | 已过期但未清理的条目数 |\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `true` | 只读操作 |\n| `destructiveHint` | `false` | 非破坏性操作 |\n| `openWorldHint` | `true` | 可能访问外部数据源 |\n\n资料来源：[server.py:115-130]()\n\n### 6. memory_clear_namespace\n\n清空指定命名空间中的所有条目。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**警告：** 此操作不可撤销，会永久删除该命名空间下的所有数据。\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `false` | 修改性操作 |\n| `destructiveHint` | `true` | 破坏性操作 |\n| `idempotentHint` | `true` | 重复执行结果一致 |\n| `openWorldHint` | `false` | 仅本地操作 |\n\n资料来源：[server.py:135-154]()\n\n### 7. memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回的统计数据：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `total_entries` | integer | 所有命名空间的条目总数（不含过期） |\n| `namespace_count` | integer | 命名空间总数 |\n| `total_size` | string | 存储目录大小（人类可读格式） |\n| `oldest_entry` | string | 最早条目的相对时间 |\n| `newest_entry` | string | 最新条目的相对时间 |\n| `expired_entries` | integer | 已过期条目数量 |\n\n资料来源：[server.py:159-178]()\n\n## 存储机制详解\n\n### 文件路径规范\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n命名空间路径通过正则表达式进行安全化处理，防止目录遍历攻击：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n| 原始命名空间 | 安全化后 | 文件路径 |\n|-------------|---------|----------|\n| `user:preferences` | `user_preferences` | `~/.agent-memory/user_preferences.json` |\n| `agent:code-reviewer` | `agent_code-reviewer` | `~/.agent-memory/agent_code-reviewer.json` |\n| `../etc/passwd` | `.._etc_passwd` | `~/.agent-memory/.._etc_passwd.json` |\n\n资料来源：[server.py:63-69]()\n\n### TTL 过期机制\n\n系统采用**惰性过期检查**策略，在以下时机检查并清理过期条目：\n\n1. `memory_recall` - 访问时检查\n2. `memory_search` - 搜索时检查\n3. `_read_namespace` - 读取命名空间时检查\n\n```mermaid\ngraph LR\n A[读取条目] --> B{有 expires_at?}\n B -->|是| C{当前时间 > expires_at?}\n C -->|是| D[标记为过期
返回 None]\n C -->|否| E[正常返回]\n B -->|否| E\n```\n\n**过期检查逻辑：**\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n if not entry.get(\"expires_at\"):\n return False\n return datetime.now(UTC) > datetime.fromisoformat(entry[\"expires_at\"])\n```\n\n资料来源：[server.py:115-119]()\n\n### 并发控制\n\n系统使用 `fcntl.flock()` 实现 POSIX 文件锁，确保多进程并发安全：\n\n```python\n@contextmanager\ndef _locked(path: Path, exclusive: bool = True):\n with path.open(\"a+\") as fh:\n lock_type = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH\n fcntl.flock(fh.fileno(), lock_type)\n try:\n yield fh\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n| 锁类型 | 应用场景 | 并发读 | 并发写 |\n|--------|----------|--------|--------|\n| `LOCK_EX` (排他锁) | `memory_remember`、`memory_forget`、`memory_clear_namespace` | ❌ | ❌ |\n| `LOCK_SH` (共享锁) | `memory_recall`、`memory_search`、`memory_list_namespaces`、`memory_stats` | ✅ | ❌ |\n\n资料来源：[server.py:32-41]()\n\n### 元数据管理\n\n`_meta.json` 存储全局统计信息，由 `_recalc_meta()` 动态计算：\n\n```python\ndef _recalc_meta() -> None:\n total = 0\n namespace_count = 0\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n namespace_count += 1\n entries = _read_namespace(p.stem)\n total += len([e for e in entries if not _is_expired(e)])\n _write_meta({\"total_entries\": total, \"namespace_count\": namespace_count})\n```\n\n资料来源：[server.py:195-204]()\n\n## 使用示例\n\n### 基本存储操作\n\n```python\n# 存储用户偏好（永久）\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\"\n)\n\n# 存储研究数据（7天过期）\nawait memory_remember(\n key=\"competitor:pricing:stripe\",\n value=\"Stripe charges 2.9% + $0.30 per transaction\",\n namespace=\"research\",\n ttl_seconds=604800 # 7 days\n)\n```\n\n### 跨会话记忆\n\n```python\n# Session 1: 学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\n\n# Session 2 (days later): 立即回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 搜索与清理\n\n```python\n# 搜索所有相关研究\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n\n# 清理旧数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n```\n\n## 响应格式化\n\n所有工具支持两种响应格式，通过 `format` 参数控制：\n\n| 格式 | 适用场景 | 示例输出 |\n|------|----------|----------|\n| `\"markdown\"` | 人类可读 | H2 标题、表格、加粗文本 |\n| `\"json\"` | 程序处理 | 结构化 JSON 对象 |\n\n**Markdown 格式响应结构：**\n\n```markdown\n## ✅ Success\n**key:** user:theme\n**value:** dark\n**created_at:** 2026-05-12T10:30:00Z\n**namespace:** preferences\n```\n\n**JSON 格式响应结构：**\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"namespace\": \"preferences\"\n}\n```\n\n资料来源：[server.py:128-154]()\n\n## 限制与配额\n\n| 层级 | 价格 | 条目限制 | 命名空间限制 |\n|------|------|----------|--------------|\n| Free | $0 | 1,000 条 | 5 个 |\n| Pro | $19/月 | 无限 | 无限 |\n\n存储大小超过限制时，系统返回警告信息但仍允许写入。资料来源：[smithery.yaml:17-27]()\n\n## 错误处理\n\n| 错误类型 | HTTP 状态 | 说明 |\n|----------|-----------|------|\n| 未知工具 | - | 返回 \"Unknown tool: {name}\" |\n| 内部错误 | `isError: true` | 捕获异常并返回详细错误信息 |\n| 命名空间为空 | - | 返回确认消息而非错误 |\n\n```python\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:203-211]()\n\n## 工具注解汇总\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | true |\n| `memory_list_namespaces` | true | false | true | true |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n资料来源：[server.py:83-178]()\n\n## 扩展配置\n\n### MCP 客户端配置\n\n**Claude Desktop:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n### 环境变量\n\n系统当前无额外环境变量要求。数据目录通过 `Path.home() / \".agent-memory\"` 自动确定。\n\n---\n\n\n\n## 查询工具详解\n\n### 相关页面\n\n相关主题：[存储工具详解](#page-5), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 查询工具详解\n\n## 概述\n\nAgent Memory MCP 提供了一套完整的查询工具，用于在持久化内存存储中检索和搜索数据。这套查询工具的核心是 `memory_search`（模糊搜索），辅以 `memory_list_namespaces`（命名空间列表）和 `memory_stats`（存储统计）两个辅助工具。三者共同构成了一个层次化的查询体系，使用户和 AI Agent 能够高效地定位和管理记忆数据。\n\n查询工具的设计遵循以下原则：\n\n- **读操作为主**：所有查询工具均标记为 `readOnlyHint=True`，不会修改底层数据\n- **幂等性保障**：重复执行相同查询将返回一致结果（`idempotentHint=True`）\n- **格式灵活**：支持 Markdown（人类可读）和 JSON（程序化处理）两种输出格式\n\n资料来源：[server.py:1-50]()\n\n## 工具清单\n\n| 工具名称 | 功能描述 | 只读 | 幂等 |\n|---------|---------|------|------|\n| `memory_search` | 在所有命名空间中按关键词搜索记忆 | ✅ | ✅ |\n| `memory_list_namespaces` | 列出所有命名空间及其条目计数 | ✅ | ✅ |\n| `memory_stats` | 获取全局存储统计信息 | ✅ | ✅ |\n\n资料来源：[server.py:160-200]()\n\n## 核心工具详解\n\n### 1. memory_search（模糊搜索）\n\n`memory_search` 是 Agent Memory MCP 中功能最强大的查询工具，支持跨命名空间的模糊匹配搜索。\n\n#### 功能特性\n\n- **跨命名空间搜索**：默认情况下搜索所有命名空间，可通过 `namespace` 参数限定范围\n- **模糊匹配**：同时匹配 key 和 value 中的子字符串\n- **大小写不敏感**：搜索不区分大小写\n- **相关性排序**：结果按访问次数（`access_count`）降序排列，热门记忆优先返回\n\n#### 参数定义\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索关键词或子字符串\",\n \"required\": true\n },\n \"namespace\": {\n \"type\": \"string\",\n \"description\": \"可选的命名空间限定。省略则搜索所有命名空间\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"最大返回结果数（默认: 10）\",\n \"default\": 10\n },\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n资料来源：[server.py:180-210]()\n\n#### 实现逻辑\n\n搜索功能的核心实现在 `_search_namespace` 辅助函数中：\n\n```python\ndef _search_namespace(\n namespace: str,\n query: str,\n limit: int = 10,\n) -> List[Dict[str, Any]]:\n \"\"\"Search within a single namespace, returning top matches by access count.\"\"\"\n entries = _read_namespace(namespace)\n # Filter: case-insensitive substring match on key OR value\n matched = [\n e for e in entries\n if not _is_expired(e) and (\n query.lower() in e[\"key\"].lower() or\n query.lower() in str(e.get(\"value\", \"\")).lower()\n )\n ]\n # Sort by access_count descending\n matched.sort(key=lambda e: e[\"access_count\"], reverse=True)\n return matched[:limit]\n```\n\n关键实现要点：\n\n1. **过期检查**：使用 `_is_expired()` 函数排除已过期的记忆条目\n2. **双重匹配**：同时检查 key 和 value 是否包含查询字符串\n3. **排序策略**：按 `access_count` 降序排列，确保高频访问的记忆优先显示\n4. **结果限制**：使用切片操作 `[:limit]` 限制返回数量\n\n资料来源：[server.py:220-240]()\n\n### 2. memory_list_namespaces（命名空间列表）\n\n此工具用于获取系统中所有命名空间的概览信息，包括活跃条目数和过期条目数。\n\n#### 参数定义\n\n```json\n{\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n#### 返回数据结构\n\n```json\n{\n \"namespaces\": [\n {\n \"name\": \"research\",\n \"active_entries\": 42,\n \"expired_entries\": 3\n },\n {\n \"name\": \"preferences\",\n \"active_entries\": 15,\n \"expired_entries\": 0\n }\n ]\n}\n```\n\n#### 实现逻辑\n\n```python\ndef memory_list_namespaces(fmt: Optional[str] = None) -> str:\n \"\"\"List all namespaces with entry counts.\"\"\"\n namespaces = []\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n entries = _read_namespace(p.stem)\n active = [e for e in entries if not _is_expired(e)]\n namespaces.append({\n \"name\": p.stem,\n \"active_entries\": len(active),\n \"expired_entries\": len(entries) - len(active),\n })\n return _success({\"namespaces\": namespaces}, fmt)\n```\n\n资料来源：[server.py:245-260]()\n\n### 3. memory_stats（存储统计）\n\n此工具提供全局存储的统计信息，帮助用户了解存储使用情况和配额限制。\n\n#### 参数定义\n\n```json\n{\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n#### 返回数据示例（Markdown 格式）\n\n```\n## 存储统计\n\n**总条目数**: 1,247\n**存储大小**: 2.3 MB\n**命名空间数**: 5\n**最早条目**: 2026-04-15（27天前）\n**最新条目**: 刚刚\n**已过期条目**: 12\n```\n\n#### 实现逻辑\n\n```python\ndef memory_stats(fmt: Optional[str] = None) -> str:\n \"\"\"Get storage statistics.\"\"\"\n _recalc_meta() # 重新计算全局元数据\n meta = _read_meta()\n \n # 计算存储大小\n total_size = sum(p.stat().st_size for p in STORAGE_DIR.glob(\"*.json\"))\n \n # 查找最早和最新条目\n oldest, newest = None, None\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n entries = _read_namespace(p.stem)\n for e in entries:\n ts = e.get(\"created_at\")\n if ts:\n if not oldest or ts < oldest:\n oldest = ts\n if not newest or ts > newest:\n newest = ts\n \n return _success({\n \"total_entries\": meta.get(\"total_entries\", 0),\n \"storage_size\": _format_size(total_size),\n \"namespace_count\": meta.get(\"namespace_count\", 0),\n \"oldest_entry\": oldest,\n \"newest_entry\": newest,\n \"expired_entries\": 0,\n }, fmt)\n```\n\n资料来源：[server.py:260-290]()\n\n## 工具注解（Tool Annotations）\n\nMCP 协议支持为每个工具提供语义注解，帮助客户端理解工具的行为特性：\n\n| 注解字段 | memory_search | memory_list_namespaces | memory_stats |\n|---------|---------------|------------------------|--------------|\n| `readOnlyHint` | `true` | `true` | `true` |\n| `destructiveHint` | `false` | `false` | `false` |\n| `idempotentHint` | `true` | `true` | `true` |\n| `openWorldHint` | `true` | `true` | `true` |\n\n**注解含义说明**：\n\n- `readOnlyHint`：表示该工具不会修改服务器状态\n- `destructiveHint`：表示该工具不会删除或破坏数据\n- `idempotentHint`：表示重复执行不会产生额外副作用\n- `openWorldHint`：表示该工具可能涉及外部世界交互（搜索功能搜索所有命名空间）\n\n资料来源：[server.py:195-200]()\n\n## 架构流程图\n\n### 查询请求处理流程\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B{memory_search?}\n A --> C{memory_list_namespaces?}\n A --> D{memory_stats?}\n \n B --> E[解析 query 参数]\n E --> F{namespace 参数存在?}\n F -->|是| G[搜索指定命名空间]\n F -->|否| H[遍历所有命名空间]\n G --> I[过滤过期条目]\n H --> I\n I --> J[按 access_count 排序]\n J --> K[限制返回数量]\n K --> L[格式化响应]\n \n C --> M[扫描 STORAGE_DIR]\n M --> N[读取每个命名空间文件]\n N --> O[统计活跃/过期条目]\n O --> L\n \n D --> P[重新计算全局元数据]\n P --> Q[计算存储大小]\n Q --> R[查找最老/最新条目]\n R --> L\n \n L --> S[返回 Markdown 或 JSON]\n \n subgraph \"存储层 ~/.agent-memory/\"\n T[\"{namespace}.json\"]\n U[\"_meta.json\"]\n end\n \n G --> T\n H --> T\n N --> T\n P --> U\n Q --> T\n R --> T\n```\n\n### 数据存储结构\n\n```mermaid\ngraph LR\n A[\"~/.agent-memory/\"] --> B[\"{namespace}.json\"]\n A --> C[\"_meta.json\"]\n \n B --> D[\"entries[]\"]\n D --> E[\"key\"]\n D --> F[\"value\"]\n D --> G[\"created_at\"]\n D --> H[\"accessed_at\"]\n D --> I[\"expires_at\"]\n D --> J[\"access_count\"]\n \n C --> K[\"total_entries\"]\n C --> L[\"namespace_count\"]\n```\n\n## 使用场景示例\n\n### 跨会话上下文恢复\n\n```python\n# Agent 在首次会话中存储用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\n\n# 后续会话中快速查询用户时区\ntz = await memory_search(\n query=\"timezone\",\n namespace=\"preferences\"\n)\n```\n\n### 研究积累与检索\n\n```python\n# 持续积累研究数据\nawait memory_remember(\n key=\"competitor:acme:pricing\",\n value=\"Acme Pro: $49/mo, Enterprise: $199/mo\",\n namespace=\"research\"\n)\n\n# 在所有命名空间中搜索竞争对手相关信息\nresults = await memory_search(\n query=\"competitor\",\n limit=20\n)\n```\n\n### 存储健康检查\n\n```python\n# 查看存储使用情况\nstats = await memory_stats()\n\n# 检查命名空间分布\nnamespaces = await memory_list_namespaces()\n\n# 定位过期数据\nfor ns in namespaces[\"namespaces\"]:\n if ns[\"expired_entries\"] > 100:\n print(f\"命名空间 {ns['name']} 有 {ns['expired_entries']} 个过期条目\")\n```\n\n## 响应格式化\n\n所有查询工具支持两种输出格式，通过 `format` 参数指定：\n\n### Markdown 格式（默认）\n\n```\n## ✅ Success\n\n**key:** user:timezone\n**value:** America/Chicago\n**created_at:** 2026-05-01T10:00:00Z\n**accessed_at:** 2026-05-12T14:22:00Z\n**access_count:** 47\n```\n\n### JSON 格式\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:timezone\",\n \"value\": \"America/Chicago\",\n \"created_at\": \"2026-05-01T10:00:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"access_count\": 47\n}\n```\n\n格式化逻辑统一由 `_format_response` 函数处理：\n\n```python\ndef _format_response(result: Dict[str, Any], fmt: Optional[str] = None) -> str:\n \"\"\"Format a result dictionary as either JSON or Markdown.\"\"\"\n if fmt == \"json\":\n return json.dumps(result, indent=2)\n # Markdown (default)\n lines = []\n # ... 构建 Markdown 格式字符串\n return \"\\n\".join(lines)\n```\n\n资料来源：[server.py:100-140]()\n\n## 错误处理\n\n查询工具的错误处理遵循统一模式：\n\n```python\ntry:\n if name == \"memory_search\":\n text = memory_search(**arguments, fmt=fmt)\n elif name == \"memory_list_namespaces\":\n text = memory_list_namespaces(fmt=fmt)\n elif name == \"memory_stats\":\n text = memory_stats(fmt=fmt)\n # ...\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n错误响应示例：\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"Internal error in memory_search: list index out of range\",\n \"isError\": true\n}\n```\n\n资料来源：[server.py:260-280]()\n\n## 线程安全性\n\n查询工具虽然都是只读操作，但在并发环境下仍需考虑数据一致性。系统使用 `fcntl.flock()` 实现文件级锁：\n\n```python\n@contextmanager\ndef _locked(path: Path) -> Any:\n \"\"\"Context manager for file locking with fcntl.flock.\"\"\"\n with path.open(\"a\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield fh\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n所有涉及文件读写的操作（`_read_namespace`、`_write_namespace` 等）都通过此上下文管理器保护，确保在多个 Agent 进程并发访问时不会产生数据竞争。\n\n资料来源：[server.py:60-80]()\n\n## 配额与限制\n\n根据 smithery.yaml 配置，查询工具受以下配额限制：\n\n| 套餐 | 价格 | 条目上限 | 命名空间上限 |\n|------|------|---------|-------------|\n| Free | $0 | 1,000 条 | 5 个 |\n| Pro | $19/月 | 无限 | 无限 |\n\n超出免费配额后，系统仍可正常执行查询操作，但建议用户升级至 Pro 套餐以获得无限存储能力。\n\n资料来源：[smithery.yaml:20-35]()\n\n## 总结\n\nAgent Memory MCP 的查询工具套件为 AI Agent 提供了一个高效、可靠的记忆检索系统：\n\n- **`memory_search`**：核心搜索工具，支持跨命名空间模糊匹配和相关性排序\n- **`memory_list_namespaces`**：命名空间管理工具，帮助用户了解数据分布\n- **`memory_stats`**：系统健康检查工具，提供存储使用统计\n\n这三个工具协同工作，使 Agent 能够在任意会话中快速定位历史记忆，实现真正的持久化上下文管理。所有工具均遵循只读、幂等的设计原则，确保在复杂的多 Agent 环境中安全可靠运行。\n\n---\n\n\n\n## 数据存储机制\n\n### 相关页面\n\n相关主题：[系统架构](#page-3), [使用场景与最佳实践](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 数据存储机制\n\n## 概述\n\nAgent Memory MCP 的数据存储机制是一个基于文件系统的持久化键值存储系统，专为 AI 代理设计。该系统将所有数据存储在用户本地目录 `~/.agent-memory/` 中，以 JSON 文件格式保存，支持命名空间隔离、时间 TTL（生存时间）管理、访问计数追踪和模糊搜索功能。资料来源：[server.py:27-29]()\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[Agent Memory MCP Server]\n B --> C[KV Store Engine]\n B --> D[TTL Manager]\n B --> E[Search Engine]\n C --> F[~/.agent-memory/]\n D --> F\n E --> F\n F --> G[{namespace}.json]\n F --> H[_meta.json]\n```\n\n## 存储目录结构\n\n### 目录位置\n\n默认存储目录位于用户主目录下的隐藏文件夹 `.agent-memory/`。系统启动时会自动创建该目录，无需手动配置。\n\n| 属性 | 值 |\n|------|-----|\n| 路径 | `~/.agent-memory/` |\n| 类型 | 用户主目录下的隐藏文件夹 |\n| 创建时机 | 服务首次启动时 |\n| 权限 | 继承系统默认权限 |\n\n资料来源：[server.py:30]()\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n### 目录结构设计\n\n```\n~/.agent-memory/\n├── _meta.json # 全局元数据统计文件\n├── default.json # 默认命名空间数据\n├── {namespace1}.json # 各命名空间独立存储\n├── {namespace2}.json\n└── {namespaceN}.json\n```\n\n每个命名空间对应一个独立的 JSON 文件，全局统计信息存储在 `_meta.json` 中。\n\n资料来源：[server.py:32]()\n\n```python\nMETA_FILE = \"_meta.json\"\n```\n\n## 命名空间管理\n\n### 命名空间概念\n\n命名空间（Namespace）用于隔离不同用途或不同代理的内存数据。这种设计允许：\n\n- 按项目分离数据\n- 按用户分离数据\n- 按功能域分离数据\n- 实现数据完全独立的存储空间\n\n资料来源：[README.md:72-74]()\n\n### 命名空间路径解析\n\n系统通过 `_namespace_path()` 函数将命名空间名称转换为安全的文件路径。命名空间名称会经过正则表达式处理，移除所有非法字符。\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n \"\"\"Return the full path for a namespace JSON file.\"\"\"\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n关键安全措施：\n- 只允许字母、数字、下划线、点和连字符\n- 所有非法字符替换为下划线\n- 空名称回退到默认命名空间\n- 文件路径无法逃逸到目录之外\n\n资料来源：[server.py:42-51]()\n\n### 默认命名空间\n\n如果未指定命名空间，系统使用 `default` 作为默认值。\n\n```python\nDEFAULT_NAMESPACE = \"default\"\n```\n\n资料来源：[server.py:31]()\n\n## 数据模型\n\n### 内存条目结构\n\n每个内存条目（Entry）是一个包含以下字段的 JSON 对象：\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `key` | string | 唯一键标识符 |\n| `value` | string | 存储的值/内容 |\n| `created_at` | ISO 8601 | 创建时间戳 |\n| `accessed_at` | ISO 8601 | 最后访问时间 |\n| `expires_at` | ISO 8601 或 null | TTL 过期时间（可选） |\n| `access_count` | integer | 访问次数计数器 |\n\n资料来源：[README.md:85-93]()\n\n### TTL 过期机制\n\n过期时间（TTL）通过 `expires_at` 字段实现。当设置 `ttl_seconds` 参数时，系统计算过期时间戳：\n\n```python\nif ttl_seconds:\n entry[\"expires_at\"] = datetime.now(timezone.utc).timestamp() + ttl_seconds\nelse:\n entry[\"expires_at\"] = None\n```\n\n过期检查采用**惰性清理**策略：在 `memory_recall` 和 `memory_search` 操作时，系统检查条目是否过期并自动移除。\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"检查条目是否已过期\"\"\"\n if entry.get(\"expires_at\") is None:\n return False\n return datetime.now(timezone.utc).timestamp() > entry[\"expires_at\"]\n```\n\n资料来源：[server.py:108-114]()\n\n## 文件操作与并发控制\n\n### 文件锁定机制\n\n系统使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全的并发访问。这是实现多进程安全的关键机制。\n\n```python\n@contextmanager\ndef _file_lock(path: Path, lock_type: int = fcntl.LOCK_EX):\n \"\"\"文件锁上下文管理器，支持读锁和写锁\"\"\"\n lock_path = path.with_suffix(\".lock\")\n with lock_path.open(\"w\") as lock_file:\n try:\n fcntl.flock(lock_file.fileno(), lock_type)\n yield\n finally:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n```\n\n| 锁类型 | 用途 | 并发读 | 并发写 |\n|--------|------|--------|--------|\n| `LOCK_EX` (排他锁) | 写入操作 | ❌ | ❌ |\n| `LOCK_SH` (共享锁) | 读取操作 | ✅ | ❌ |\n\n资料来源：[server.py:60-74]()\n\n### 读写操作实现\n\n**读取命名空间数据：**\n\n```python\ndef _read_namespace(namespace: str) -> List[Dict[str, Any]]:\n \"\"\"读取命名空间的所有条目\"\"\"\n path = _namespace_path(namespace)\n if not path.exists():\n return []\n with _file_lock(path, fcntl.LOCK_SH):\n with path.open(\"r\", encoding=\"utf-8\") as f:\n return json.load(f)\n```\n\n**写入命名空间数据：**\n\n```python\ndef _write_namespace(namespace: str, entries: List[Dict[str, Any]]) -> None:\n \"\"\"写入命名空间的所有条目\"\"\"\n path = _namespace_path(namespace)\n with _file_lock(path, fcntl.LOCK_EX):\n with path.open(\"w\", encoding=\"utf-8\") as f:\n json.dump(entries, f, ensure_ascii=False, indent=2)\n```\n\n资料来源：[server.py:76-90]()\n\n### 锁定文件结构\n\n对于每个命名空间文件，系统会创建对应的锁文件：\n\n```\n~/.agent-memory/\n├── _meta.json\n├── _meta.json.lock # 元数据文件锁\n├── default.json\n├── default.json.lock # 默认命名空间锁\n├── research.json\n└── research.json.lock # 研究命名空间锁\n```\n\n## 元数据管理\n\n### 全局元数据文件\n\n`_meta.json` 文件存储全局统计信息：\n\n```json\n{\n \"total_entries\": 150,\n \"namespace_count\": 5,\n \"oldest_entry\": \"2026-04-15T10:00:00Z\",\n \"newest_entry\": \"2026-06-12T14:30:00Z\"\n}\n```\n\n### 元数据计算\n\n系统通过 `_recalc_meta()` 函数扫描所有命名空间文件来重新计算全局统计：\n\n```python\ndef _recalc_meta() -> None:\n \"\"\"Recompute global metadata by scanning all namespaces.\"\"\"\n total = 0\n namespace_count = 0\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n namespace_count += 1\n entries = _read_namespace(p.stem)\n total += len([e for e in entries if not _is_expired(e)])\n _write_meta({\"total_entries\": total, \"namespace_count\": namespace_count})\n```\n\n该函数在 `memory_stats` 操作时被调用。\n\n资料来源：[server.py:167-178]()\n\n## 存储操作实现\n\n### 写入操作 (memory_remember)\n\n```mermaid\ngraph TD\n A[memory_remember 调用] --> B{key 是否存在?}\n B -->|存在| C[更新 existing_entry]\n B -->|不存在| D[创建 new_entry]\n C --> E[更新 accessed_at]\n D --> E\n E --> F[access_count 递增]\n F --> G[写入文件锁]\n G --> H[JSON 序列化]\n H --> I[写入 {namespace}.json]\n I --> J[释放文件锁]\n J --> K[返回成功响应]\n```\n\n资料来源：[server.py:180-230]()\n\n### 读取操作 (memory_recall)\n\n```mermaid\ngraph TD\n A[memory_recall 调用] --> B[获取文件锁 SH]\n B --> C[读取 JSON]\n C --> D{条目存在?}\n D -->|否| E[返回错误]\n D -->|是| F{条目过期?}\n F -->|是| G[删除过期条目]\n F -->|否| H[更新 accessed_at]\n H --> I[access_count 递增]\n G --> J[写入更新]\n I --> J\n J --> K[释放文件锁]\n K --> L[返回记忆数据]\n```\n\n资料来源：[server.py:232-285]()\n\n### 搜索操作 (memory_search)\n\n搜索功能支持模糊匹配，同时搜索键名和值内容：\n\n```python\nquery_lower = query.lower()\nfor entry in entries:\n if query_lower in entry[\"key\"].lower() or query_lower in entry[\"value\"].lower():\n results.append(entry)\n\nresults.sort(key=lambda e: e.get(\"access_count\", 0), reverse=True)\n```\n\n搜索特性：\n- **大小写不敏感**：所有匹配在比较前转换为小写\n- **子串匹配**：支持关键词子串搜索\n- **跨键值搜索**：同时匹配键名和值内容\n- **访问频率排序**：结果按访问次数降序排列\n\n资料来源：[server.py:287-345]()\n\n## 存储限制与配额\n\n### 层级限制\n\n| 层级 | 价格 | 条目限制 | 命名空间限制 |\n|------|------|----------|--------------|\n| Free（免费） | $0 | 1,000 条 | 5 个 |\n| Pro（专业） | $19/月 | 无限 | 无限 |\n\n资料来源：[README.md:106-111]()\n\n### 响应大小限制\n\n系统设置了字符输出限制，防止超大响应导致协议问题：\n\n```python\nCHARACTER_LIMIT = 25_000\n```\n\n超过限制的响应会被截断：\n\n```python\ndef _truncate(text: str, limit: int = CHARACTER_LIMIT) -> str:\n \"\"\"Truncate text if it exceeds the character limit.\"\"\"\n if len(text) > limit:\n return text[: limit - 3] + \"...\"\n return text\n```\n\n资料来源：[server.py:35](), [server.py:143-146]()\n\n## 依赖关系\n\n### Python 标准库依赖\n\n项目仅依赖 Python 标准库和 MCP SDK：\n\n| 模块 | 用途 |\n|------|------|\n| `asyncio` | 异步运行时 |\n| `fcntl` | POSIX 文件锁定 |\n| `json` | JSON 序列化/反序列化 |\n| `pathlib` | 跨平台路径操作 |\n| `datetime` | 时间戳处理 |\n| `re` | 命名空间名称规范化 |\n\n资料来源：[server.py:1-18]()\n\n### MCP SDK 依赖\n\n```python\n# requirements.txt\nmcp>=1.0.0\n```\n\n资料来源：[requirements.txt]()\n\n## 设计原则\n\n### 本地优先\n\n所有数据存储在用户本地机器上，不依赖云服务或外部 API。这确保了：\n\n- **零延迟**：本地文件 I/O 速度极快\n- **数据主权**：用户完全掌控自己的数据\n- **离线可用**：无需网络连接即可工作\n- **隐私保护**：数据不会离开用户的设备\n\n资料来源：[README.md:99-101]()\n\n### 简洁性\n\n采用类 Redis 的键值存储设计，而非复杂的向量数据库。这符合 AI 代理的实际需求——记住关键信息，而非大规模语义搜索。\n\n资料来源：[README.md:97-99]()\n\n## 故障处理\n\n### 错误响应格式\n\n所有错误以统一格式返回：\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"具体错误信息\",\n \"isError\": true\n}\n```\n\n错误响应支持 Markdown 和 JSON 两种格式，由调用方指定：\n\n```python\ndef _error(message: str, fmt: Optional[str] = None) -> str:\n result = {\"status\": \"error\", \"error\": message, \"isError\": True}\n return _format_response(result, fmt)\n```\n\n资料来源：[server.py:151-153]()\n\n### 异常捕获\n\n工具调用层统一捕获所有异常并返回结构化错误：\n\n```python\ntry:\n # ... 执行工具逻辑\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:360-368]()\n\n---\n\n\n\n## 使用场景与最佳实践\n\n### 相关页面\n\n相关主题：[核心功能详解](#page-4), [开发指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n \n\n# 使用场景与最佳实践\n\n本文档详细说明 Agent Memory MCP 的典型使用场景及对应的最佳实践指导，帮助开发者充分利用持久化内存系统的能力。\n\n## 核心使用场景概述\n\nAgent Memory MCP 设计用于解决 AI Agent 在会话间的上下文丢失问题。当 Agent 在不同会话间切换时，所有对话上下文都会重置为零。Agent Memory MCP 通过提供持久化、可搜索的内存存储，使 Agent 能够记住关键信息、用户偏好和中间计算结果。\n\n资料来源：[README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 场景一：跨会话用户偏好管理\n\n### 问题描述\n\n用户在首次对话中提供的偏好信息（如时区、货币、语言等）在会话结束时会被遗忘，导致 Agent 在后续会话中需要重复询问同样的问题，浪费 Token 成本。\n\n### 解决方案\n\n利用 `memory_remember` 存储用户偏好，利用 `memory_recall` 在后续会话中快速检索。\n\n### 实现示例\n\n```python\n# 会话 1：Agent 学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\nawait memory_remember(\n key=\"user:currency\",\n value=\"USD\",\n namespace=\"preferences\"\n)\n\n# 会话 2（数天后）：Agent 立即回忆偏好\ntz = await memory_recall(key=\"user:timezone\", namespace=\"preferences\")\n# → \"America/Chicago\"\n# 无需再次询问用户\n```\n\n资料来源：[README.md:1-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 时效性考虑\n\n对于用户偏好，建议使用较长的 TTL 或永久存储。关键代码逻辑如下：\n\n```python\n# 使用 30 天 TTL 存储用户偏好\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30 天\n)\n```\n\n资料来源：[server.py:200-250](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 场景二：研究积累代理\n\n### 问题描述\n\nAgent 在执行研究任务时，需要逐步积累发现的信息。传统方式下，这些信息无法跨会话保留，导致重复研究和上下文窗口浪费。\n\n### 解决方案\n\n创建独立的研究命名空间，系统化存储发现成果。\n\n### 实现示例\n\n```python\n# Agent 存储研究发现的竞品信息\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls. Enterprise: $199/mo. No free tier.\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# Agent 存储另一个竞品的定价信息\nawait memory_remember(\n key=\"competitor:stripe:pricing\",\n value=\"Stripe charges 2.9% + $0.30 per transaction for US cards\",\n namespace=\"research\"\n)\n\n# 后续：搜索所有竞品相关内容\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n```\n\n资料来源：[README.md:50-80](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 搜索机制说明\n\n`memory_search` 执行不区分大小写的子字符串匹配，同时搜索键名和值内容。返回结果按访问次数排序，高频访问的条目优先级更高。\n\n```python\n# 模糊搜索示例\nawait memory_search(\n query=\"stripe\",\n namespace=\"research\"\n)\n# 可匹配 key=\"competitor:stripe:pricing\" 或 value 包含 \"stripe\" 的条目\n```\n\n## 场景三：Agent 工作区（Scratchpad）\n\n### 问题描述\n\n复杂任务需要 Agent 在执行过程中记录中间状态、分步骤待办事项或调试信息。这些信息仅在当前任务周期内有用。\n\n### 解决方案\n\n使用专门的任务命名空间作为工作区，支持读写和清理。\n\n### 实现示例\n\n```python\n# Agent 使用内存作为工作区\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh. Step 3: Update tests.\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 检索当前任务状态\nstate = await memory_recall(\n key=\"scratch:task:refactor-auth\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 定期清理已完成的任务数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n# → \"Cleared 156 entries from 'agent:code-reviewer'\"\n```\n\n资料来源：[README.md:80-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 命名空间设计建议\n\n| 命名空间模式 | 用途 | TTL 建议 |\n|------------|------|----------|\n| `preferences` | 用户偏好 | 长 TTL 或永久 |\n| `research` | 研究发现 | 中等 TTL |\n| `agent:{agent-id}` | Agent 工作区 | 任务周期 |\n| `session:{session-id}` | 会话临时数据 | 会话结束清理 |\n\n## 场景四：周期性数据清理\n\n### 问题描述\n\n长期运行的 Agent 会积累大量过期或无效的数据，影响存储效率和检索性能。\n\n### 解决方案\n\n利用 `memory_clear_namespace` 定期清理命名空间，或使用 TTL 自动过期。\n\n### 最佳实践\n\n```python\n# Agent 清理旧的研究数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n# → \"Cleared 156 entries from 'agent:code-reviewer'\"\n\n# 检查当前存储统计\nstats = await memory_stats()\n# 返回：总条目数、命名空间数、最旧/最新条目、过期条目数\n```\n\n资料来源：[README.md:95-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 工具注解与语义\n\nAgent Memory MCP 为每个工具提供语义注解，帮助 Agent 理解工具行为：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n### 注解含义\n\n- **readOnlyHint**: 工具是否仅读取数据\n- **destructiveHint**: 工具是否执行删除操作\n- **idempotentHint**: 工具重复执行是否产生相同结果\n- **openWorldHint**: 工具是否与外部世界交互\n\n资料来源：[server.py:100-150](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 存储架构与数据模型\n\n### 存储位置\n\n所有数据持久化存储在 `~/.agent-memory/` 目录：\n\n```\n~/.agent-memory/\n├── {namespace}.json # 每个命名空间一个文件\n└── _meta.json # 全局统计数据\n```\n\n资料来源：[README.md:120-140](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 条目数据结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n### 访问计数机制\n\n每次调用 `memory_recall` 都会更新 `accessed_at` 时间戳并递增 `access_count`，这使得：\n\n1. 搜索结果按相关性排序（高频访问条目优先）\n2. 可以分析记忆条目的使用频率\n3. 便于识别长期未使用的陈旧数据\n\n资料来源：[server.py:250-300](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 并发安全机制\n\nAgent Memory MCP 使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全：\n\n```mermaid\ngraph TD\n A[Agent 进程 1] -->|写入| L[文件锁]\n B[Agent 进程 2] -->|等待| L\n C[Agent 进程 N] -->|等待| L\n L -->|解锁| A\n L -->|锁定| B\n B -->|解锁| B\n L -->|锁定| C\n```\n\n这允许多个 Agent 进程安全地并发读写内存存储。\n\n资料来源：[server.py:80-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 响应格式控制\n\n所有工具支持 `format` 参数指定返回格式：\n\n```python\n# 获取 Markdown 格式输出（人类可读）\nresult = await memory_stats(format=\"markdown\")\n\n# 获取 JSON 格式输出（程序化使用）\nresult = await memory_stats(format=\"json\")\n```\n\n### JSON 格式响应示例\n\n```json\n{\n \"status\": \"ok\",\n \"total_entries\": 847,\n \"active_entries\": 835,\n \"expired_entries\": 12,\n \"total_size\": \"2.4 MB\",\n \"namespaces\": 5,\n \"oldest_entry\": \"2026-04-15 (27 days ago)\",\n \"newest_entry\": \"just now\"\n}\n```\n\n资料来源：[server.py:300-350](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 定价层级与限制\n\n| 层级 | 价格 | 限制 |\n|------|-------|------|\n| **免费版** | $0 | 1,000 条目，5 个命名空间 |\n| **专业版** | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n资料来源：[README.md:150-160](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 设计原则\n\nAgent Memory MCP 遵循以下核心设计原则：\n\n1. **简洁优于复杂** — 类似 Redis 的键值存储，而非向量数据库。Agent 只需记住关键信息。\n2. **本地优先** — 数据保留在本地机器上。无云服务、无 API 密钥、无延迟。\n3. **自描述性** — 工具响应默认采用人类可读的 Markdown 格式，JSON 格式供程序调用。\n4. **容错性** — 延迟 TTL 过期、非严格搜索、优雅的错误处理。\n\n资料来源：[README.md:110-115](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 最佳实践总结\n\n### 命名空间策略\n\n- 按项目、用户或领域组织命名空间\n- 使用清晰、一致的命名约定（如 `agent:{name}`、`user:{id}`）\n- 定期清理不再需要的命名空间\n\n### TTL 设置指南\n\n| 数据类型 | TTL 建议 | 示例 |\n|---------|---------|------|\n| 用户偏好 | 永久或长 TTL | 30-90 天 |\n| 研究发现 | 中等 TTL | 7-30 天 |\n| 工作区数据 | 短 TTL 或清理 | 1-7 天 |\n| 会话数据 | 会话结束清理 | 无 TTL |\n\n### 键命名规范\n\n- 使用冒号分隔层级：`user:preferences:theme`\n- 保持键名简洁但具描述性\n- 避免在键名中包含敏感信息\n\n### 性能优化\n\n- 批量相似操作使用同一命名空间\n- 定期调用 `memory_stats` 监控存储使用\n- 及时清理过期数据以减少存储开销\n\n---\n\n\n\n## 开发指南\n\n### 相关页面\n\n相关主题：[部署指南与常见问题](#page-10), [安装与配置](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 开发指南\n\n本文档为 Agent Memory MCP 项目的完整开发指南，涵盖项目架构、工具实现、数据存储机制、测试方法以及部署配置。通过本指南，开发者可以深入理解系统设计理念，快速上手二次开发或集成工作。\n\n## 1. 项目概述\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值存储服务器，专为 AI Agent 设计。该项目解决了 AI Agent 在会话之间丢失上下文的核心问题，提供持久化、可搜索、带 TTL（生存时间）的记忆存储能力。\n\n项目核心特性包括：\n\n- 7 个结构化工具支持完整的记忆管理\n- Namespace 命名空间隔离机制\n- TTL 自动过期与延迟清理\n- 模糊搜索（子串匹配）\n- 访问计数追踪\n- 基于 `fcntl.flock()` 的线程安全并发访问\n- 零外部依赖（仅依赖 `mcp` 包）\n- JSON 文件存储，数据保留在本地 `~/.agent-memory/`\n\n资料来源：[server.py:1-30]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph AI_Agent[\"AI Agent (Claude/GPT/Codex)\"]\n A[remember / recall / search / forget]\n end\n \n subgraph MCP_Protocol[\"MCP 协议层 (stdio JSON-RPC)\"]\n B[Tool Call 请求]\n C[JSON-RPC 响应]\n end\n \n subgraph Server[\"Agent Memory MCP Server\"]\n D[KV Store Engine]\n E[TTL Manager]\n F[Search Engine
substring match]\n end\n \n subgraph Storage[\"数据持久化层\"]\n G[\"~/.agent-memory/\"]\n H[\"{namespace}.json\"]\n I[\"_meta.json\"]\n end\n \n A -->|MCP Protocol| B\n B --> D\n D --> E\n E --> F\n D --> H\n D --> I\n F --> G\n C -->|响应结果| A\n```\n\n架构采用经典的三层设计：协议层处理 MCP 通信、业务层实现核心逻辑、存储层负责数据持久化。`fcntl.flock()` 文件锁确保多个 Agent 进程可以安全地并发读写。\n\n资料来源：[README.md:架构图]()\n\n### 2.2 核心组件说明\n\n| 组件 | 文件位置 | 职责 | 依赖 |\n|------|----------|------|------|\n| MCP Server | `server.py` | 注册工具、处理请求路由 | `mcp.server` |\n| KV Store Engine | `server.py` | 键值存储 CRUD 操作 | `json`, `pathlib` |\n| TTL Manager | `server.py` | 过期检查与延迟清理 | `datetime`, `time` |\n| Search Engine | `server.py` | 子串匹配搜索 | `re` (正则) |\n| File Locker | `server.py` | 并发访问控制 | `fcntl` |\n\n资料来源：[server.py:28-60]()\n\n## 3. 项目结构\n\n```\nagent-memory-mcp/\n├── server.py # 主服务器实现（核心业务逻辑）\n├── requirements.txt # 依赖声明\n├── README.md # 项目文档\n├── LICENSE # MIT 许可证\n└── smithery.yaml # Smithery.ai 部署配置\n```\n\n核心代码全部集中在 `server.py` 单文件中，采用模块化函数设计，便于维护和理解。\n\n资料来源：[requirements.txt]()\n\n## 4. 环境配置与安装\n\n### 4.1 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 需要结构化并发支持 |\n| mcp | ≥1.0.0 | MCP Python SDK |\n| 操作系统 | POSIX 兼容 | 需要 `fcntl` 支持 |\n\n### 4.2 安装步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install mcp\n\n# 或使用 requirements.txt\npip install -r requirements.txt\n```\n\n资料来源：[README.md:安装章节]()\n\n### 4.3 存储目录\n\n首次运行时，系统自动创建存储目录：\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n数据存储结构如下：\n\n| 文件 | 内容 |\n|------|------|\n| `{namespace}.json` | 每个命名空间的记忆条目数组 |\n| `_meta.json` | 全局统计和索引信息 |\n\n资料来源：[server.py:54-56]()\n\n## 5. 工具实现详解\n\n### 5.1 工具注册机制\n\n所有工具通过 MCP Server 的装饰器模式注册：\n\n```python\n@server.list_tools()\nasync def list_tools() -> List[Tool]:\n return [Tool(...), Tool(...), ...]\n```\n\n路由分发通过 `call_tool` 装饰器实现：\n\n```python\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n if name == \"memory_remember\":\n text = memory_remember(**arguments, fmt=fmt)\n elif name == \"memory_recall\":\n text = memory_recall(**arguments, fmt=fmt)\n # ... 其他工具\n```\n\n资料来源：[server.py:320-345]()\n\n### 5.2 工具清单与参数\n\n#### 5.2.1 memory_remember\n\n存储键值对到指定命名空间。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 唯一键标识符 |\n| `value` | string | ✅ | - | 要存储的值 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `ttl_seconds` | integer | ❌ | - | TTL 秒数 |\n\n**Tool Annotations:**\n```python\nToolAnnotations(\n readOnlyHint=False,\n destructiveHint=False,\n idempotentHint=False,\n openWorldHint=False\n)\n```\n\n资料来源：[server.py:工具定义区域]()\n\n#### 5.2.2 memory_recall\n\n根据键检索值及其元数据。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n\n**返回值结构：**\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n资料来源：[server.py:170-200]()\n\n#### 5.2.3 memory_forget\n\n删除指定的键值对。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n\n#### 5.2.4 memory_search\n\n跨命名空间模糊搜索。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子串 |\n| `namespace` | string | ❌ | - | 限定命名空间（空则搜索全部） |\n| `limit` | integer | ❌ | 10 | 最大返回结果数 |\n\n搜索特性：\n- 大小写不敏感\n- 同时匹配 key 和 value\n- 按访问次数排序\n\n#### 5.2.5 memory_list_namespaces\n\n列出所有命名空间及其条目计数。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 输出格式：`markdown` 或 `json` |\n\n#### 5.2.6 memory_clear_namespace\n\n清空指定命名空间的所有条目。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n\n#### 5.2.7 memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 输出格式：`markdown` 或 `json` |\n\n资料来源：[server.py:工具定义区域]()\n\n### 5.3 工具注解系统\n\nMCP 协议支持工具注解，用于客户端优化行为：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n资料来源：[README.md:Tool Annotations]()\n\n## 6. 数据模型\n\n### 6.1 记忆条目结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n字段说明：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `key` | string | 全局唯一标识符 |\n| `value` | string | 存储的实际内容 |\n| `created_at` | ISO8601 string | 创建时间 |\n| `accessed_at` | ISO8601 string | 最后访问时间 |\n| `expires_at` | ISO8601 string 或 null | TTL 过期时间（可选） |\n| `access_count` | integer | 访问计数器 |\n\n资料来源：[server.py:记忆条目结构]()\n\n### 6.2 元数据文件结构\n\n```json\n{\n \"total_entries\": 142,\n \"namespace_count\": 5\n}\n```\n\n资料来源：[server.py:元数据写入]()\n\n## 7. 存储实现细节\n\n### 7.1 文件锁定机制\n\n```python\n@contextmanager\ndef _locked(namespace: str):\n lock_path = _namespace_path(namespace).with_suffix(\".lock\")\n with lock_path.open(\"w\") as lock_file:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n```\n\n使用 POSIX 文件锁 `fcntl.flock()` 实现排他锁，确保多进程并发安全。\n\n资料来源：[server.py:文件锁定实现]()\n\n### 7.2 命名空间安全处理\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n使用正则表达式过滤非法字符，防止路径穿越攻击。\n\n资料来源：[server.py:命名空间路径安全处理]()\n\n### 7.3 TTL 过期检查\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n if \"expires_at\" not in entry or entry[\"expires_at\"] is None:\n return False\n expires = datetime.fromisoformat(entry[\"expires_at\"])\n return datetime.now(timezone.utc) > expires\n```\n\n采用延迟清理策略，仅在访问时检查过期，避免后台清理线程开销。\n\n资料来源：[server.py:TTL检查逻辑]()\n\n## 8. 测试与调试\n\n### 8.1 本地测试\n\n```bash\n# 使用 MCP Inspector 测试\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 运行单元测试\npython3 -m pytest tests/\n```\n\n资料来源：[README.md:开发章节]()\n\n### 8.2 MCP Client 配置\n\n**通用配置 (config.yaml):**\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n**Claude Desktop:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:MCP Client配置]()\n\n## 9. 部署配置\n\n### 9.1 Smithery.ai 部署\n\n项目提供 Smithery.ai 平台的一键部署配置：\n\n```yaml\nname: agent-memory-mcp\nversion: 1.0.0\ndescription: Persistent key-value memory for AI agents with TTL, namespaces, and search.\n\nruntime:\n type: python\n entrypoint: server.py\n requirements: requirements.txt\n\ncapabilities:\n tools:\n - memory_remember\n - memory_recall\n - memory_forget\n - memory_search\n - memory_list_namespaces\n - memory_clear_namespace\n - memory_stats\n\npricing:\n free:\n max_entries: 1000\n pro:\n price: 19.00\n currency: USD\n interval: month\n max_entries: unlimited\n stripe_link: https://buy.stripe.com/PLACEHOLDER\n\nmetadata:\n author: Nous Research\n license: MIT\n repository: https://github.com/nousresearch/agent-memory-mcp\n tags:\n - memory\n - storage\n - agents\n - persistence\n - kv-store\n```\n\n资料来源：[smithery.yaml]()\n\n## 10. 响应格式化\n\n### 10.1 格式化策略\n\n系统支持两种响应格式，通过 `format` 参数控制：\n\n| 格式 | 适用场景 | 示例 |\n|------|----------|------|\n| `markdown` | 人类可读 | `## ✅ Success\\n**key:** value` |\n| `json` | 程序化处理 | `{\"status\": \"ok\", \"key\": \"value\"}` |\n\n### 10.2 错误处理\n\n所有工具都包装在统一的异常处理中：\n\n```python\ntry:\n # 工具执行\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n输出长度限制在 25,000 字符以内，防止大响应导致的问题。\n\n资料来源：[server.py:异常处理和输出限制]()\n\n## 11. 设计原则\n\n项目遵循以下核心设计原则：\n\n1. **简洁优于复杂** — 类似 Redis 的 KV 存储，而非向量数据库。Agent 只需要记住事情。\n2. **本地优先** — 数据保存在本地机器上。无云服务、无 API 密钥、无延迟。\n3. **自描述** — 工具响应默认是人类可读的 markdown，JSON 用于程序化调用。\n4. **容错性** — 延迟 TTL 过期、非严格搜索、优雅的错误处理。\n\n资料来源：[README.md:设计原则]()\n\n## 12. 扩展开发指南\n\n### 12.1 添加新工具\n\n在 `server.py` 中添加新工具需要完成以下步骤：\n\n1. 在 `list_tools()` 中定义 `Tool` 对象\n2. 在 `call_tool()` 中添加路由分支\n3. 实现对应的处理函数\n4. 添加单元测试\n\n```python\n# 1. 定义工具\nTool(\n name=\"memory_new_tool\",\n description=\"新工具描述\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {...},\n \"required\": [...]\n },\n annotations=ToolAnnotations(\n readOnlyHint=True,\n destructiveHint=False,\n idempotentHint=True,\n openWorldHint=False,\n ),\n)\n\n# 2. 路由分发\nelif name == \"memory_new_tool\":\n text = memory_new_tool(**arguments, fmt=fmt)\n\n# 3. 实现函数\ndef memory_new_tool(key: str, fmt: str = \"markdown\") -> str:\n # 业务逻辑\n return _success({\"result\": \"...\"}, fmt)\n```\n\n### 12.2 修改存储后端\n\n当前实现使用 JSON 文件存储。如需切换到其他后端（如 SQLite），需要重写以下函数：\n\n- `_read_namespace()`\n- `_write_namespace()`\n- `_locked()`\n- `_recalc_meta()`\n\n保持接口签名不变，上层业务逻辑无需修改。\n\n## 13. 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方仓库 | https://github.com/nousresearch/agent-memory-mcp |\n| Nous Research | https://nousresearch.com |\n| 相关项目 - Agent Cost Tracker MCP | https://github.com/Rumblingb/agent-cost-tracker-mcp |\n| 相关项目 - Search Proxy MCP | https://github.com/Rumblingb/search-proxy-mcp |\n| 相关项目 - AgentPassport API | https://github.com/Rumblingb/agentpassport-api |\n\n---\n\n\n\n## 部署指南与常见问题\n\n### 相关页面\n\n相关主题：[安装与配置](#page-2), [开发指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 部署指南与常见问题\n\n## 概述\n\n本页面提供 Agent Memory MCP 的完整部署指南与常见问题解答。该项目是一个基于 Model Context Protocol (MCP) 的持久化键值存储系统，专为 AI 代理设计，支持命名空间隔离、TTL 过期机制、模糊搜索和访问计数追踪。资料来源：[server.py:1-30]()\n\n## 系统要求\n\n| 要求项 | 规格 |\n|--------|------|\n| Python 版本 | 3.10+ |\n| 操作系统 | macOS、Linux、Windows |\n| 依赖包 | mcp >= 1.0.0 |\n| 网络 | 仅本地通信，无需外网 |\n\n资料来源：[requirements.txt:1]()\n\n## 部署方式\n\n### 方式一：pip 安装（推荐）\n\n通过 Python 包管理器直接安装：\n\n```bash\npip install agent-memory-mcp\n```\n\n安装完成后可直接使用 `python3 -m agent_memory_mcp` 启动服务。资料来源：[index.html]()\n\n### 方式二：源码安装\n\n适用于需要自定义修改或参与开发的情况：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install mcp\n\n# 或使用 requirements.txt\npip install -r requirements.txt\n\n# 启动服务\npython3 server.py\n```\n\n资料来源：[README.md:89-99]()\n\n### 方式三：MCP Inspector 测试\n\n在开发阶段，可使用 MCP Inspector 进行调试：\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md:101-102]()\n\n## MCP 客户端配置\n\n### Claude Desktop\n\n在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n资料来源：[README.md:117-123]()\n\n### VS Code / Cursor\n\n在 `.cursor/mcp.json` 或 VS Code 的 MCP 设置中添加：\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:125-132]()\n\n### 通用 YAML 配置\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n## 存储架构\n\n### 数据存储位置\n\n所有数据存储在用户主目录下的隐藏目录 `~/.agent-memory/` 中：\n\n| 文件 | 用途 |\n|------|------|\n| `{namespace}.json` | 各命名空间的记忆条目数组 |\n| `_meta.json` | 全局统计和索引信息 |\n\n资料来源：[server.py:47-49]()\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[agent-memory Server]\n B --> C{操作类型}\n C -->|remember| D[写入 JSON 文件]\n C -->|recall| E[读取并更新访问计数]\n C -->|search| F[模糊匹配搜索]\n C -->|forget| G[删除条目]\n D --> H[~/.agent-memory/]\n E --> H\n F --> H\n G --> H\n```\n\n### 命名空间隔离机制\n\n每个命名空间对应独立的 JSON 文件，通过命名空间路径函数进行隔离：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n关键安全措施：命名空间名只能包含 `a-zA-Z0-9_.-` 字符，其他字符会被替换为下划线，防止目录遍历攻击。资料来源：[server.py:58-65]()\n\n## 工具函数使用指南\n\n### 1. memory_remember — 存储记忆\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 记忆的唯一标识键 |\n| `value` | string | ✅ | 要存储的值 |\n| `namespace` | string | ❌ | 命名空间，默认 `\"default\"` |\n| `ttl_seconds` | integer | ❌ | 自动过期秒数 |\n\n**示例：**\n\n```python\n# 带 TTL 的用户偏好存储（30天过期）\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000\n)\n\n# 永久存储研究数据\nawait memory_remember(\n key=\"competitor:pricing:stripe\",\n value=\"Stripe charges 2.9% + $0.30 per transaction\",\n namespace=\"research\"\n)\n```\n\n资料来源：[README.md:135-145]()\n\n### 2. memory_recall — 检索记忆\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要检索的键名 |\n| `namespace` | string | ❌ | 命名空间，默认 `\"default\"` |\n\n**返回元数据：**\n\n| 字段 | 说明 |\n|------|------|\n| `value` | 存储的值 |\n| `created_at` | 创建时间戳 |\n| `accessed_at` | 最后访问时间 |\n| `expires_at` | TTL 过期时间（如有设置） |\n| `access_count` | 访问次数统计 |\n\n资料来源：[README.md:147-156]()\n\n### 3. memory_forget — 删除记忆\n\n```python\nawait memory_forget(\n key=\"user:old_preference\",\n namespace=\"preferences\"\n)\n```\n\n### 4. memory_search — 模糊搜索\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `query` | string | ✅ | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | 限定命名空间搜索 |\n| `limit` | integer | ❌ | 最大返回数量，默认 10 |\n| `format` | string | ❌ | 输出格式：`markdown` 或 `json` |\n\n```python\n# 跨所有命名空间搜索\nresults = await memory_search(query=\"competitor pricing\")\n\n# 限定命名空间搜索\nresults = await memory_search(\n query=\"api\",\n namespace=\"research\",\n limit=20\n)\n```\n\n搜索特性：大小写不敏感，同时匹配键名和值内容，结果按访问次数排序。资料来源：[server.py:275-295]()\n\n### 5. memory_list_namespaces — 列出命名空间\n\n```python\n# 返回所有命名空间及其活跃/过期条目计数\nnamespaces = await memory_list_namespaces()\n```\n\n### 6. memory_clear_namespace — 清除命名空间\n\n```python\n# 永久删除指定命名空间的所有条目\nawait memory_clear_namespace(namespace=\"research:old\")\n# → \"Cleared 156 entries from 'research:old'\"\n```\n\n**注意：** 此操作不可撤销。资料来源：[README.md:177-179]()\n\n### 7. memory_stats — 全局统计\n\n```python\n# 获取存储统计信息\nstats = await memory_stats(format=\"markdown\")\n```\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `total_entries` | 活跃条目总数 |\n| `total_size_bytes` | 存储文件总大小（字节） |\n| `total_size_human` | 人类可读大小 |\n| `namespace_count` | 命名空间数量 |\n| `oldest_entry` | 最早条目时间 |\n| `newest_entry` | 最新条目时间 |\n| `free_tier_limit` | 免费配额限制（1000条） |\n\n资料来源：[server.py:345-370]()\n\n## 常见问题排查\n\n### 问题一：导入错误 \"ModuleNotFoundError: No module named 'mcp'\"\n\n**原因：** 未安装 MCP 依赖包。\n\n**解决方案：**\n\n```bash\npip install mcp\n```\n\n或者使用项目提供的 requirements.txt：\n\n```bash\npip install -r requirements.txt\n```\n\n资料来源：[requirements.txt:1]()\n\n### 问题二：存储目录权限错误\n\n**症状：** `PermissionError: [Errno 13] Permission denied`\n\n**原因：** 无法在 `~/.agent-memory/` 创建文件。\n\n**解决方案：**\n\n```bash\n# 检查并修复目录权限\nls -la ~ | grep agent-memory\nchmod 755 ~/.agent-memory\n```\n\n存储目录由以下代码自动创建：\n\n```python\ndef _ensure_storage() -> None:\n \"\"\"Create the storage directory if it doesn't exist.\"\"\"\n STORAGE_DIR.mkdir(parents=True, exist_ok=True)\n```\n\n资料来源：[server.py:52-54]()\n\n### 问题三：并发访问数据不一致\n\n**症状：** 写入的数据在读取时丢失或损坏。\n\n**原因：** 未使用正确的并发控制机制。\n\n**解决方案：** Agent Memory MCP 使用 `fcntl.flock()` 实现文件级锁，确保多进程安全访问。确保所有访问都通过 MCP 服务器进行，而非直接操作 JSON 文件。资料来源：[README.md:203-205]()\n\n### 问题四：TTL 过期条目未自动清理\n\n**症状：** 过期条目仍然出现在搜索结果中。\n\n**原因：** 系统采用懒清理策略，仅在访问时检查过期状态。\n\n**解决方案：** 这是设计决策，不影响功能。过期条目会在下次 `recall` 或 `search` 时被自动过滤。如需主动清理，可调用 `memory_list_namespaces` 查看各命名空间状态。\n\n过期检测逻辑：\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"Check if an entry has expired based on its TTL.\"\"\"\n expires_at = entry.get(\"expires_at\")\n if not expires_at:\n return False\n expires_time = datetime.fromisoformat(expires_at)\n return datetime.now(timezone.utc) > expires_time\n```\n\n资料来源：[server.py:120-127]()\n\n### 问题五：中文或特殊字符无法正确存储\n\n**症状：** 存储的中文字符在检索时变成乱码。\n\n**原因：** 字符编码问题。\n\n**解决方案：** 确保 JSON 文件使用 UTF-8 编码。Python 的 `json` 模块默认使用 UTF-8，无需额外配置。如在终端显示乱码，请确保终端编码设置为 UTF-8。\n\n### 问题六：数据文件过大\n\n**症状：** `~/.agent-memory/` 目录占用过多磁盘空间。\n\n**解决方案：**\n\n1. 定期清理过期或无用命名空间：\n\n```python\n# 清理特定命名空间\nawait memory_clear_namespace(namespace=\"temp:sessions\")\n\n# 查看统计信息\nstats = await memory_stats()\n```\n\n2. 手动删除不使用的 JSON 文件：\n\n```bash\nrm ~/.agent-memory/old_namespace.json\n```\n\n资料来源：[server.py:380-385]()\n\n## 线程安全机制\n\nAgent Memory MCP 通过 POSIX 文件锁 `fcntl.flock()` 实现并发安全：\n\n```mermaid\ngraph LR\n A[进程 A] -->|LOCK_EX| C[文件锁]\n B[进程 B] -->|等待| C\n C -->|解锁| D[完成读写]\n D -->|UNLOCK| E[锁释放]\n B -->|获锁| D\n```\n\n所有文件操作都在锁保护区域内执行，确保同一时间只有一个进程可以写入。资料来源：[README.md:203-205]()\n\n## 响应格式\n\n工具支持两种输出格式，通过 `format` 参数指定：\n\n| 格式 | 用途 | 示例 |\n|------|------|------|\n| `markdown` | 人类可读，默认 | `## ✅ Success\\n**key:** value` |\n| `json` | 程序化处理 | `{\"status\": \"ok\", \"key\": \"value\"}` |\n\n```python\n# 获取 JSON 格式结果\nresult = await memory_recall(\n key=\"user:theme\",\n namespace=\"preferences\",\n format=\"json\"\n)\n```\n\n资料来源：[server.py:310-335]()\n\n## 开发测试\n\n运行项目测试套件：\n\n```bash\npython3 -m pytest tests/\n```\n\n使用 MCP Inspector 进行交互式测试：\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md:101-104]()\n\n## 定价与限制\n\n| 套餐 | 价格 | 限制 |\n|------|------|------|\n| 免费版 | $0 | 1,000 条目，5 个命名空间 |\n| Pro 版 | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n注意：免费版限制为功能性提示，非技术强制限制。数据始终存储在本地，不会因达到限制而丢失。资料来源：[index.html]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph AI层\n A[Claude/GPT/Codex] \n end\n \n subgraph MCP协议层\n B[MCP Protocol
stdio JSON-RPC]\n end\n \n subgraph 服务层\n C[Agent Memory
MCP Server]\n D[KV 存储引擎]\n E[TTL 管理器]\n F[搜索引擎
子字符串匹配]\n end\n \n subgraph 存储层\n G[~/.agent-memory/]\n H[namespace.json]\n I[_meta.json]\n end\n \n A -->|remember/recall/search| B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n E --> G\n F --> G\n G --> H\n G --> I\n```\n\n资料来源：[README.md:195-215]()\n\n## 参考链接\n\n- 项目仓库：https://github.com/Rumblingb/agent-memory-mcp\n- Nous Research：https://nousresearch.com\n- 相关项目：\n - [Agent Cost Tracker MCP](https://github.com/Rumblingb/agent-cost-tracker-mcp)\n - [Search Proxy MCP](https://github.com/Rumblingb/search-proxy-mcp)\n - [AgentPassport API](https://github.com/Rumblingb/agentpassport-api)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Rumblingb/agent-memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agent-memory-mcp` 与安装入口 `mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | repo=agent-memory-mcp; install=mcp\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | release_recency=unknown\n\n\n",
"markdown_key": "agent-memory-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1236240815",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Rumblingb/agent-memory-mcp"
},
{
"evidence_id": "art_4f1584cdb6d643c099ec7e025683da6e",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Rumblingb/agent-memory-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "agent-memory-mcp 说明书",
"toc": [
"https://github.com/Rumblingb/agent-memory-mcp 项目说明书",
"目录",
"项目概览",
"1. 项目简介",
"2. 核心功能特性",
"3. 系统架构",
"4. 数据存储结构",
"5. 工具 API 参考",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "13b6173f5d6088593d766b25eabb391d2c08151f",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"requirements.txt"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# agent-memory-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agent-memory-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/Rumblingb/agent-memory-mcp.git` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install -r requirements.txt` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx @modelcontextprotocol/inspector python3 server.py` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：9\n- 重要文件覆盖：9/9\n- 证据索引条目：8\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 agent-memory-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agent-memory-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 agent-memory-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **🧠 Agent Memory MCP**（project_doc）：! MCP Server https://img.shields.io/badge/MCP-Server-blue https://modelcontextprotocol.io ! Python https://img.shields.io/badge/Python-3.10%2B-green https://python.org ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! Smithery https://img.shields.io/badge/Smithery-Listed-purple https://smithery.ai ! Pro $19/mo https://img.shields.io/badge/Pro-%2419%2Fmo-635bff https://buy.stripe.com/fZu14p… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n\n## 证据索引\n\n- 共索引 8 条证据。\n\n- **🧠 Agent Memory MCP**（documentation）：! MCP Server https://img.shields.io/badge/MCP-Server-blue https://modelcontextprotocol.io ! Python https://img.shields.io/badge/Python-3.10%2B-green https://python.org ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! Smithery https://img.shields.io/badge/Smithery-Listed-purple https://smithery.ai ! Pro $19/mo https://img.shields.io/badge/Pro-%2419%2Fmo-635bff https://buy.stripe.com/fZu14p3D94RC9PWa791oI0v 证据：`README.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Python**（source_file）：Python pycache / .py cod $py.class .so .egg-info/ dist/ build/ .egg 证据：`.gitignore`\n- **Index**（source_file）：Agent Memory MCP — Persistent Memory for AI Agents { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: 0d1117; color: c9d1d9; line-height: 1.6; } .container { max-width: 800px; margin: 0 auto; padding: 60px 20px; } h1 { font-size: 2.5rem; margin-bottom: 0.5rem; background: linear-gradient 135deg, 58a6ff, bc8cff ; -webkit-background-clip: text; -webkit-text-fill-color: transparent; } .subtitle { font-size: 1.2rem; color: 8b949e; margin-bottom: 2rem; } .badges { margin: 1rem 0 2rem; display: flex; gap: 0.5rem; flex-wrap: wrap; } .badge { background: 21262d; border: 1px solid 30363d; border-radius… 证据：`index.html`\n- **Pyproject**（source_file）：build-system requires = \"setuptools =68.0\", \"wheel\" build-backend = \"setuptools.backends. legacy: Backend\" 证据：`pyproject.toml`\n- **Requirements**（source_file）：mcp =1.0.0 证据：`requirements.txt`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\" Agent Memory MCP Server ======================== A persistent key-value memory store for AI agents with TTL, namespaces, fuzzy search, and access counting. Data lives in ~/.agent-memory/ as one JSON file per namespace plus a meta.json stats file. 证据：`server.py`\n- **Smithery.ai deployment configuration for Agent Memory MCP**（source_file）：Smithery.ai deployment configuration for Agent Memory MCP name: agent-memory-mcp version: 1.0.0 description: Persistent key-value memory for AI agents with TTL, namespaces, and search. 证据：`smithery.yaml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `LICENSE`, `.gitignore`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `LICENSE`, `.gitignore`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, server.py\n- **安装与配置**：importance `high`\n - source_paths: requirements.txt, pyproject.toml, smithery.yaml\n- **系统架构**：importance `high`\n - source_paths: server.py\n- **核心功能详解**：importance `high`\n - source_paths: server.py\n- **存储工具详解**：importance `medium`\n - source_paths: server.py\n- **查询工具详解**：importance `medium`\n - source_paths: server.py\n- **数据存储机制**：importance `high`\n - source_paths: server.py\n- **使用场景与最佳实践**：importance `medium`\n - source_paths: server.py, README.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `13b6173f5d6088593d766b25eabb391d2c08151f`\n- inspected_files: `pyproject.toml`, `README.md`, `requirements.txt`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `agent-memory-mcp` 与安装入口 `mcp` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | repo=agent-memory-mcp; install=mcp\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Rumblingb/agent-memory-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Rumblingb/agent-memory-mcp 项目说明书\n\n生成时间：2026-05-12 05:48:40 UTC\n\n## 目录\n\n- [项目概览](#page-1)\n- [安装与配置](#page-2)\n- [系统架构](#page-3)\n- [核心功能详解](#page-4)\n- [存储工具详解](#page-5)\n- [查询工具详解](#page-6)\n- [数据存储机制](#page-7)\n- [使用场景与最佳实践](#page-8)\n- [开发指南](#page-9)\n- [部署指南与常见问题](#page-10)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装与配置](#page-2), [系统架构](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 项目概览\n\n## 1. 项目简介\n\nAgent Memory MCP 是一个基于 MCP（Model Context Protocol）的持久化键值存储服务，专为 AI 智能体设计。该项目由 Nous Research 开发，采用 MIT 开源许可证，旨在解决 AI 智能体在会话之间丢失上下文的核心问题。\n\n**核心价值主张：** AI 智能体在每次新会话开始时会丢失所有上下文信息。Agent Memory MCP 通过提供持久化、可搜索的内存功能，使智能体能够跨会话、跨重启、跨日期记住重要信息。\n\n项目依赖极为精简，仅需 Python 3.10+ 和 `mcp>=1.0.0` 两个核心依赖，数据以 JSON 格式存储在本地磁盘 `~/.agent-memory/` 目录下，完全实现本地优先（Local-first）的设计理念。\n\n## 2. 核心功能特性\n\nAgent Memory MCP 提供了七大核心工具支持完整的内存管理能力：\n\n| 功能 | 描述 |\n|------|------|\n| **memory_remember** | 存储键值对，支持可选的 TTL（生存时间） |\n| **memory_recall** | 检索键值对及其完整元数据 |\n| **memory_forget** | 永久删除指定键 |\n| **memory_search** | 按关键词跨命名空间搜索 |\n| **memory_list_namespaces** | 列出所有命名空间及其条目计数 |\n| **memory_clear_namespace** | 清空整个命名空间 |\n| **memory_stats** | 获取全局存储统计信息 |\n\n**附加特性：**\n\n- **命名空间隔离**：按项目、用户或领域组织内存，支持不同智能体使用独立存储空间\n- **TTL 支持**：条目可设置自动过期时间，精确到秒级精度\n- **模糊搜索**：支持大小写不敏感的子字符串匹配，按访问频率排序\n- **访问追踪**：每条记忆记录创建时间、最后访问时间和访问次数\n- **线程安全**：通过 `fcntl.flock()` 实现文件级锁，确保多进程并发安全访问\n- **零外部依赖**：仅使用 Python 标准库（json、fcntl、pathlib、datetime）\n\n## 3. 系统架构\n\n### 3.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph AI层\n A[\"🤖 AI Agent
(Claude/GPT/Codex)\"]\n end\n \n subgraph MCP协议层\n B[\"📡 MCP Protocol
(stdio JSON-RPC)\"]\n end\n \n subgraph 服务器层\n C[\"⚙️ Agent Memory MCP Server
(server.py)\"]\n \n subgraph 核心模块\n D[\"🗄️ KV Store Engine\"]\n E[\"⏱️ TTL Manager\"]\n F[\"🔍 Search Engine
(substring match)\"]\n end\n end\n \n subgraph 存储层\n G[\"📁 ~/.agent-memory/\"]\n H[\"{namespace}.json\"]\n I[\"_meta.json\"]\n end\n \n A -->|\"remember()
recall()
search()
forget()\"| B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n E --> G\n F --> G\n G --> H\n G --> I\n```\n\n### 3.2 核心组件职责\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| **Server 入口** | `server.py` (main) | 初始化 MCP 服务器，监听 stdio 连接 |\n| **工具路由** | `server.py` (call_tool) | 根据工具名称分发请求到对应处理函数 |\n| **存储引擎** | `server.py` (_read_namespace, _write_namespace) | 读写 JSON 文件，支持文件锁 |\n| **TTL 管理器** | `server.py` (_is_expired, _cleanup_expired) | 检查和清理过期条目 |\n| **搜索引擎** | `server.py` (memory_search) | 子字符串模糊匹配 |\n| **格式化器** | `server.py` (_format_response) | 输出 Markdown 或 JSON 格式响应 |\n\n## 4. 数据存储结构\n\n### 4.1 存储目录布局\n\n所有数据持久化到 `~/.agent-memory/` 目录：\n\n```\n~/.agent-memory/\n├── default.json # 默认命名空间数据\n├── preferences.json # 用户偏好命名空间\n├── research.json # 研究数据命名空间\n├── agent_xxx.json # 智能体专用命名空间\n└── _meta.json # 全局元数据和统计\n```\n\n### 4.2 数据模型\n\n**命名空间文件结构（{namespace}.json）：**\n\n```json\n[\n {\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n }\n]\n```\n\n**元数据文件结构（_meta.json）：**\n\n```json\n{\n \"total_entries\": 156,\n \"namespace_count\": 5,\n \"oldest_entry\": \"2026-04-15\",\n \"newest_entry\": \"2026-05-12\"\n}\n```\n\n### 4.3 常量定义\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CHARACTER_LIMIT` | 25,000 | 单次响应最大字符数 |\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间名称 |\n| `STORAGE_DIR` | `Path.home() / \".agent-memory\"` | 数据存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n\n资料来源：[server.py:27-31]()\n\n## 5. 工具 API 参考\n\n### 5.1 memory_remember\n\n存储键值对，支持可选 TTL。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 键标识符 |\n| `value` | string | ✅ | 要存储的值 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `ttl_seconds` | integer | ❌ | 自动过期秒数 |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n```python\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30天\n)\n```\n\n### 5.2 memory_recall\n\n检索键值对及完整元数据。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要检索的键 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `value` | 存储的值 |\n| `created_at` | 创建时间 |\n| `accessed_at` | 最后访问时间 |\n| `expires_at` | TTL 过期时间（如设置） |\n| `access_count` | 访问次数统计 |\n\n### 5.3 memory_forget\n\n永久删除指定键。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要删除的键 |\n| `namespace` | string | ❌ | 命名空间（默认：\"default\"） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.4 memory_search\n\n跨命名空间模糊搜索。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `query` | string | ✅ | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | 限定搜索的命名空间 |\n| `limit` | integer | ❌ | 最大返回结果数（默认：10） |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**搜索特性：**\n\n- 大小写不敏感匹配\n- 同时匹配键名和值内容\n- 按访问次数降序排序\n\n### 5.5 memory_list_namespaces\n\n列出所有命名空间及其条目统计。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.6 memory_clear_namespace\n\n清空指定命名空间下的所有条目。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `namespace` | string | ✅ | 要清空的命名空间 |\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n### 5.7 memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `format` | string | ❌ | 返回格式（markdown/json） |\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `total_entries` | 总条目数（仅活跃条目） |\n| `total_size_bytes` | 存储总大小（字节） |\n| `total_size_human` | 存储总大小（人类可读） |\n| `namespace_count` | 命名空间数量 |\n| `oldest_entry` | 最旧条目创建时间 |\n| `newest_entry` | 最新条目创建时间 |\n| `storage_path` | 存储路径 |\n| `free_tier_limit` | 免费配额限制 |\n| `pro_tier_limit` | Pro 版本限制 |\n\n## 6. 并发与锁机制\n\n```mermaid\nsequenceDiagram\n participant Agent1 as Agent Process 1\n participant Agent2 as Agent Process 2\n participant FS as File System\n \n Agent1->>FS: 请求文件锁 (LOCK_EX)\n Note over FS: 锁定 {namespace}.json\n Agent1->>FS: 读取/写入数据\n Agent1->>FS: 释放文件锁 (LOCK_UN)\n \n Agent2->>FS: 请求文件锁 (LOCK_EX)\n Note over FS: 锁定 {namespace}.json\n Agent2->>FS: 读取/写入数据\n Agent2->>FS: 释放文件锁 (LOCK_UN)\n```\n\nAgent Memory MCP 使用 Python 的 `fcntl.flock()` 实现文件级排他锁，确保多个智能体进程可以安全地并发读写存储文件。锁粒度为单个命名空间文件，而非整个存储目录，这允许不同命名空间的操作并行执行。\n\n## 7. 命名空间安全\n\n命名空间名称通过正则表达式进行安全过滤，防止目录遍历攻击：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n资料来源：[server.py:59-62]()\n\n允许的字符集：`a-zA-Z0-9_. -`，所有非法字符替换为下划线。\n\n## 8. 响应格式\n\n### 8.1 Markdown 格式（默认）\n\n```\n## ✅ Success\n\n**key:** user:theme\n**value:** dark\n**created_at:** 2026-05-12T10:30:00Z\n\n**namespace:** preferences\n**expires_at:** 2026-06-11T10:30:00Z\n```\n\n### 8.2 JSON 格式\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"namespace\": \"preferences\"\n}\n```\n\n## 9. 安装与配置\n\n### 9.1 环境要求\n\n| 要求 | 最小版本 |\n|------|----------|\n| Python | 3.10+ |\n| MCP | >= 1.0.0 |\n\n### 9.2 安装步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install -r requirements.txt\n# 或仅安装 MCP\npip install mcp\n```\n\n资料来源：[README.md:60-68]()\n\n### 9.3 MCP 客户端配置\n\n**Claude Desktop (config.json)：**\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor：**\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n**通用配置（config.yaml）：**\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n### 9.4 测试与开发\n\n```bash\n# 使用 MCP Inspector 测试\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 运行测试套件\npython3 -m pytest tests/\n```\n\n## 10. 使用场景示例\n\n### 10.1 跨会话用户偏好\n\n```python\n# 会话 1：智能体学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\nawait memory_remember(\n key=\"user:currency\",\n value=\"USD\",\n namespace=\"preferences\"\n)\n\n# 会话 2（数天后）：智能体立即回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 10.2 研究积累智能体\n\n```python\n# 存储研究发现\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls. Enterprise: $199/mo. No free tier.\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# 搜索所有竞争对手研究\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n```\n\n### 10.3 智能体草稿板\n\n```python\n# 智能体使用内存作为工作草稿板\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh. Step 3: Update tests.\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 检索当前任务状态\nstate = await memory_recall(\"scratch:task:refactor-auth\", \"agent:code-reviewer\")\n```\n\n## 11. 设计原则\n\n| 原则 | 描述 |\n|------|------|\n| **简单优于复杂** | 定位为类 Redis 的 KV 存储，而非向量数据库，专注于智能体的记忆需求 |\n| **本地优先** | 数据存储在本地机器，无云服务、无 API 密钥、无延迟 |\n| **自描述** | 工具响应默认采用人类可读的 Markdown 格式，JSON 用于程序调用 |\n| **容错设计** | 延迟 TTL 过期、非严格搜索、优雅的错误处理 |\n\n资料来源：[README.md:77-84]()\n\n## 12. 版本与定价\n\n| 版本 | 价格 | 功能限制 |\n|------|------|----------|\n| **免费版** | $0 | 1,000 条目，5 个命名空间 |\n| **Pro 版** | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n## 13. 相关项目\n\n- [Agent Cost Tracker MCP](https://github.com/Rumblingb/agent-cost-tracker-mcp) — AI 智能体 Token 用量和成本追踪\n- [Search Proxy MCP](https://github.com/Rumblingb/search-proxy-mcp) — AI 智能体 Web 搜索\n- [AgentPassport API](https://github.com/Rumblingb/agentpassport-api) — 托管支付中间件\n\n资料来源：[README.md:86-91]()\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [部署指南与常见问题](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 安装与配置\n\n## 概述\n\n`agent-memory-mcp` 是一个基于 Model Context Protocol (MCP) 的持久化键值内存存储服务，专为 AI 代理设计。该项目通过提供 `memory_remember`、`memory_recall`、`memory_forget`、`memory_search` 等工具，使 AI 代理能够在不同会话之间保持上下文记忆。\n\n本页面详细说明该项目的环境要求、安装方式以及在不同 MCP 客户端中的配置方法。\n\n---\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 项目使用类型注解和 `asyncio` 语法 |\n| 操作系统 | macOS / Linux / Windows | 支持 POSIX 文件锁（Unix 系）或 WSL |\n| MCP SDK | ≥ 1.0.0 | 唯一的外部依赖 |\n\n资料来源：[README.md:1]()\n\n### 依赖项\n\n项目仅有单一外部依赖：\n\n```\nmcp>=1.0.0\n```\n\n资料来源：[requirements.txt:1]()\n\n项目完全基于 Python 标准库构建，使用了以下内置模块：\n\n- `json` — 数据序列化\n- `fcntl` — 文件级锁（POSIX 系统并发控制）\n- `pathlib` — 文件路径操作\n- `asyncio` — 异步 I/O 支持\n\n资料来源：[server.py:1-30]()\n\n---\n\n## 安装方式\n\n### 方式一：PyPI 快速安装\n\n对于已发布版本，可直接使用 pip 安装：\n\n```bash\npip install agent-memory-mcp\n```\n\n资料来源：[index.html:1]()\n\n### 方式二：源码安装\n\n适用于开发版本或自定义修改：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install -r requirements.txt\n```\n\n资料来源：[README.md:1]()\n\n如果需要本地安装可编辑版本：\n\n```bash\npip install -e .\n```\n\n---\n\n## MCP 客户端配置\n\n### 通用配置格式\n\n所有 MCP 客户端的配置结构相似，核心参数如下：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `command` | string | ✅ | 执行命令，通常为 `python3` |\n| `args` | array | ✅ | 脚本路径数组 |\n| `description` | string | ❌ | 服务描述文本 |\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n资料来源：[README.md:1]()\n\n---\n\n### Claude Desktop 配置\n\n#### 配置文件位置\n\n| 操作系统 | 配置文件路径 |\n|----------|--------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n#### 配置示例\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n#### 配置验证步骤\n\n1. 保存配置文件\n2. 重启 Claude Desktop 应用\n3. 在新会话中测试工具调用\n\n---\n\n### VS Code / Cursor 配置\n\n#### 配置文件位置\n\n| 编辑器 | 配置文件路径 |\n|--------|--------------|\n| VS Code | 用户级或工作区 `.vscode/mcp.json` |\n| Cursor | `~/.cursor/mcp.json` |\n\n#### 配置示例\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n> **注意**：`cwd` 参数指定了工作目录，确保脚本能够正确找到 `server.py`。\n\n---\n\n### Smithery.ai 部署配置\n\n对于 Smithery.ai 平台部署，项目提供了专用配置文件：\n\n```yaml\n# smithery.yaml\nname: agent-memory-mcp\nversion: 1.0.0\ndescription: Persistent key-value memory for AI agents with TTL, namespaces, and search.\n\nruntime:\n type: python\n entrypoint: server.py\n requirements: requirements.txt\n\ncapabilities:\n tools:\n - memory_remember\n - memory_recall\n - memory_forget\n - memory_search\n - memory_list_namespaces\n - memory_clear_namespace\n - memory_stats\n\nmetadata:\n author: Nous Research\n license: MIT\n repository: https://github.com/nousresearch/agent-memory-mcp\n```\n\n资料来源：[smithery.yaml:1]()\n\n---\n\n## 数据存储架构\n\n### 存储目录\n\n项目将所有数据存储在用户主目录下的隐藏文件夹中：\n\n```\n~/.agent-memory/\n```\n\n资料来源：[server.py:1]()\n\n### 文件结构\n\n| 文件名 | 用途 |\n|--------|------|\n| `{namespace}.json` | 各命名空间的内存条目数组 |\n| `_meta.json` | 全局统计信息和索引 |\n\n#### 条目数据结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n资料来源：[README.md:1]()\n\n### 命名空间安全机制\n\n系统会对命名空间名称进行安全处理，防止目录遍历攻击：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n资料来源：[server.py:1]()\n\n---\n\n## 并发安全机制\n\n项目使用 POSIX 文件锁 (`fcntl.flock()`) 实现多进程并发安全访问：\n\n```mermaid\ngraph TD\n A[Agent Process 1] -->|写入| F[File Lock]\n B[Agent Process 2] -->|等待| F\n C[Agent Process 3] -->|等待| F\n F -->|释放| G[namespace.json]\n F -->|获得锁| A\n```\n\n资料来源：[server.py:1]()\n\n---\n\n## 工具注册与可用工具\n\n服务器启动时会注册以下 7 个工具：\n\n| 工具名称 | 功能 | 破坏性操作 |\n|----------|------|------------|\n| `memory_remember` | 存储键值对 | ❌ |\n| `memory_recall` | 检索键值及元数据 | ❌ |\n| `memory_forget` | 删除指定键 | ✅ |\n| `memory_search` | 关键词跨命名空间搜索 | ❌ |\n| `memory_list_namespaces` | 列出所有命名空间 | ❌ |\n| `memory_clear_namespace` | 清空整个命名空间 | ✅ |\n| `memory_stats` | 获取存储统计信息 | ❌ |\n\n资料来源：[index.html:1]()\n\n---\n\n## MCP Inspector 测试\n\n安装完成后，可使用 MCP Inspector 进行本地测试：\n\n```bash\n# 安装 MCP Inspector（如未安装）\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 或直接运行服务器\npython3 server.py\n```\n\n资料来源：[README.md:1]()\n\n---\n\n## 常见问题\n\n### Q: 提示 \"mcp\" 模块未找到？\n\n确保已正确安装依赖：\n\n```bash\npip install mcp\n# 或\npip install -r requirements.txt\n```\n\n### Q: Windows 系统文件锁问题？\n\n项目主要面向 Unix/Linux/macOS 系统。在 Windows 上建议使用 WSL（Windows Subsystem for Linux）环境运行。\n\n### Q: 如何查看存储统计？\n\n使用 `memory_stats` 工具可查看：\n\n- 总条目数\n- 存储大小\n- 命名空间数量\n- 最旧/最新条目时间\n- 已过期条目数\n\n资料来源：[index.html:1]()\n\n---\n\n## 相关链接\n\n| 资源 | 地址 |\n|------|------|\n| GitHub 仓库 | https://github.com/Rumblingb/agent-memory-mcp |\n| 项目官网 | https://nousresearch.com |\n| MIT 许可证 | 见 LICENSE 文件 |\n| Nous Research | https://nousresearch.com |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心功能详解](#page-4), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n \n\n# 系统架构\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值内存存储系统，专为 AI 代理设计。本页面详细说明其整体架构、核心组件、数据存储机制和并发控制策略。\n\n## 1. 架构概述\n\nAgent Memory MCP 采用**分层架构设计**，核心组件包括 MCP 协议层、业务逻辑层和持久化存储层。系统通过标准输入输出（stdio）进行 JSON-RPC 通信，实现与 AI 代理的交互。\n\n```\n┌──────────────────────────────────────────────────────┐\n│ AI 代理层 (Claude/GPT/Codex) │\n│ remember() / recall() / search() / forget() │\n└──────────────────────┬───────────────────────────────┘\n │ MCP 协议 (stdio JSON-RPC)\n┌──────────────────────▼───────────────────────────────┐\n│ Agent Memory MCP 服务器 │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │\n│ │ 键值存储 │ │ TTL │ │ 搜索引擎 │ │\n│ │ 引擎 │ │ 管理器 │ │ (子字符串匹配) │ │\n│ └────┬─────┘ └────┬─────┘ └────────┬──────────┘ │\n│ │ │ │ │\n│ ┌────▼──────────────▼────────────────▼───────────┐ │\n│ │ ~/.agent-memory/ │ │\n│ │ {namespace}.json │ _meta.json │ │\n│ └────────────────────────────────────────────────┘ │\n└───────────────────────────────────────────────────────┘\n```\n\n资料来源：[server.py:1-50]()\n\n## 2. 核心组件\n\n### 2.1 MCP 服务器层\n\nMCP 服务器是系统的核心入口点，负责处理协议级别的通信。\n\n```python\nserver = Server(\n name=\"agent-memory\",\n version=\"1.0.0\",\n instructions=\"Agent Memory MCP — Persistent key-value memory for AI agents with TTL, namespaces, and search.\",\n website_url=\"https://github.com/nousresearch/agent-memory-mcp\",\n)\n```\n\n| 属性 | 值 | 说明 |\n|------|-----|------|\n| `name` | agent-memory | 服务器标识名 |\n| `version` | 1.0.0 | 语义化版本号 |\n| `instructions` | 协议说明 | MCP 客户端可见的指令 |\n| `website_url` | GitHub 仓库地址 | 项目主页 |\n\n资料来源：[server.py:175-181]()\n\n### 2.2 工具注册与路由\n\n系统定义了 7 个工具，全部通过 `@server.list_tools()` 装饰器注册，并通过 `@server.call_tool()` 统一路由分发。\n\n```python\n@server.list_tools()\nasync def list_tools() -> List[Tool]:\n return [\n Tool(name=\"memory_remember\", ...),\n Tool(name=\"memory_recall\", ...),\n Tool(name=\"memory_forget\", ...),\n Tool(name=\"memory_search\", ...),\n Tool(name=\"memory_list_namespaces\", ...),\n Tool(name=\"memory_clear_namespace\", ...),\n Tool(name=\"memory_stats\", ...),\n ]\n\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n if name == \"memory_remember\":\n text = memory_remember(**arguments, fmt=fmt)\n elif name == \"memory_recall\":\n text = memory_recall(**arguments, fmt=fmt)\n # ... 其他工具路由\n```\n\n资料来源：[server.py:183-240]()\n\n### 2.3 工具注解系统\n\n每个工具都携带元数据注解，用于指示工具的行为特性：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n- **readOnlyHint**: 是否为只读操作\n- **destructiveHint**: 是否为破坏性操作\n- **idempotentHint**: 是否为幂等操作\n- **openWorldHint**: 是否与外部世界交互\n\n资料来源：[server.py:95-170]()\n\n## 3. 数据存储架构\n\n### 3.1 存储目录结构\n\n数据默认存储在用户家目录下的 `.agent-memory` 文件夹中：\n\n```\n~/.agent-memory/\n├── {namespace}.json # 每个命名空间一个文件\n└── _meta.json # 全局元数据\n```\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间名称 |\n| `STORAGE_DIR` | `Path.home() / \".agent-memory\"` | 存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n| `CHARACTER_LIMIT` | 25,000 | 单次响应字符限制 |\n\n资料来源：[server.py:52-59]()\n\n### 3.2 文件命名空间隔离\n\n命名空间文件名经过安全处理，防止目录遍历攻击：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n \"\"\"Return the full path for a namespace JSON file.\"\"\"\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n资料来源：[server.py:69-76]()\n\n### 3.3 内存条目结构\n\n每个内存条目（Entry）包含以下字段：\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `key` | string | 唯一键标识符 |\n| `value` | string | 存储的值 |\n| `created_at` | ISO 8601 时间戳 | 创建时间 |\n| `accessed_at` | ISO 8601 时间戳 | 最后访问时间 |\n| `expires_at` | ISO 8601 时间戳 | TTL 过期时间（可选） |\n| `access_count` | integer | 访问计数 |\n\n资料来源：[server.py:82-100]()\n\n### 3.4 元数据文件结构\n\n`_meta.json` 存储全局统计信息：\n\n```json\n{\n \"total_entries\": 156,\n \"namespace_count\": 5,\n \"last_updated\": \"2026-05-12T15:00:00Z\"\n}\n```\n\n## 4. 并发控制机制\n\n### 4.1 文件锁机制\n\n系统使用 `fcntl.flock()` 实现进程级别的文件锁，确保多代理并发访问的安全性：\n\n```python\n@contextmanager\ndef _locked(namespace: Optional[str] = None) -> Iterator[None]:\n \"\"\"Context manager for file-level locking.\"\"\"\n if namespace:\n path = _namespace_path(namespace)\n with open(path, \"a+\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n else:\n # Lock the meta file for global operations\n with open(_meta_path(), \"a+\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n资料来源：[server.py:117-137]()\n\n### 4.2 锁粒度设计\n\n| 操作类型 | 锁范围 | 说明 |\n|---------|-------|------|\n| 单命名空间操作 | 命名空间文件锁 | 仅锁定特定命名空间 |\n| 全局统计操作 | 元数据文件锁 | 锁定 `_meta.json` |\n| 跨命名空间操作 | 无锁（读操作） | 使用懒加载避免死锁 |\n\n```mermaid\ngraph TD\n A[请求进入] --> B{操作类型?}\n B -->|单命名空间| C[锁定 namespace.json]\n B -->|全局统计| D[锁定 _meta.json]\n B -->|跨命名空间搜索| E[遍历+无锁读]\n C --> F[执行操作]\n D --> F\n E --> F\n F --> G[释放锁]\n G --> H[返回结果]\n```\n\n## 5. 业务逻辑层\n\n### 5.1 核心功能模块\n\n| 模块 | 功能 | 文件路径 |\n|------|------|----------|\n| `_ensure_storage()` | 确保存储目录存在 | server.py |\n| `_namespace_path()` | 生成命名空间文件路径 | server.py |\n| `_read_namespace()` | 读取命名空间数据 | server.py |\n| `_write_namespace()` | 写入命名空间数据 | server.py |\n| `_is_expired()` | 检查 TTL 是否过期 | server.py |\n| `_format_response()` | 格式化响应输出 | server.py |\n| `_recalc_meta()` | 重新计算元数据 | server.py |\n\n### 5.2 工具实现流程\n\n#### memory_remember 流程\n\n```mermaid\ngraph TD\n A[memory_remember 调用] --> B[验证 key 和 value]\n B --> C{命名空间存在?}\n C -->|否| D[自动创建命名空间]\n C -->|是| E[获取写锁]\n D --> E\n E --> F[构建新条目]\n F --> G[追加/更新到数组]\n G --> H[写入 JSON 文件]\n H --> I[释放锁]\n I --> J[返回成功响应]\n```\n\n资料来源：[server.py:140-200]()\n\n#### memory_recall 流程\n\n```mermaid\ngraph TD\n A[memory_recall 调用] --> B[获取读锁]\n B --> C[读取命名空间 JSON]\n C --> D[查找指定 key]\n D --> E{条目存在?}\n E -->|否| F[返回错误]\n E -->|是| G{TTL 已过期?}\n G -->|是| H[懒删除并返回错误]\n G -->|否| I[更新 accessed_at 和 access_count]\n I --> J[写入文件]\n J --> K[释放锁]\n K --> L[返回完整条目]\n```\n\n资料来源：[server.py:200-260]()\n\n### 5.3 TTL 管理机制\n\n系统采用**懒过期策略**，只在访问时检查 TTL：\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"Check if an entry has expired based on its TTL.\"\"\"\n if \"expires_at\" not in entry or entry[\"expires_at\"] is None:\n return False\n expires = datetime.fromisoformat(entry[\"expires_at\"])\n return datetime.now(timezone.utc) > expires\n```\n\n资料来源：[server.py:103-110]()\n\n| 策略 | 说明 |\n|------|------|\n| 写入时设置 | 创建条目时指定 `expires_at` |\n| 访问时检查 | recall 操作触发过期检查 |\n| 懒删除 | 过期条目在被访问时删除，不主动清理 |\n\n### 5.4 搜索机制\n\n```python\ndef _search_entries(entries: List[Dict], query: str, limit: int) -> List[Dict]:\n \"\"\"Search entries by keyword substring in keys and values.\"\"\"\n results = []\n for entry in entries:\n if _is_expired(entry):\n continue\n if query.lower() in entry[\"key\"].lower() or query.lower() in entry[\"value\"].lower():\n results.append(entry)\n results.sort(key=lambda e: e.get(\"access_count\", 0), reverse=True)\n return results[:limit]\n```\n\n资料来源：[server.py:110-125]()\n\n搜索特性：\n- **子字符串匹配**：支持关键词部分匹配\n- **大小写不敏感**：自动转换为小写比较\n- **跨键值搜索**：同时搜索 key 和 value 字段\n- **访问频率排序**：按 access_count 降序返回结果\n\n## 6. 响应格式化系统\n\n### 6.1 格式类型\n\n系统支持两种响应格式，通过 `format` 参数切换：\n\n| 格式 | 说明 | Content-Type |\n|------|------|--------------|\n| `markdown` | 人类可读的 Markdown 格式（默认） | text/markdown |\n| `json` | 程序可读的 JSON 格式 | application/json |\n\n### 6.2 Markdown 格式化示例\n\n```python\ndef _format_response(result: Dict[str, Any], fmt: Optional[str] = None) -> str:\n if fmt == \"json\":\n return json.dumps(result, indent=2)\n # Markdown (default)\n lines = []\n status = result.get(\"status\", \"ok\")\n if status == \"error\":\n lines.append(f\"## ❌ Error\")\n lines.append(f\"**{result.get('error', 'Unknown error')}**\")\n else:\n lines.append(f\"## ✅ Success\")\n # ... 格式化其他字段\n return \"\\n\".join(lines)\n```\n\n资料来源：[server.py:250-290]()\n\n## 7. 入口点设计\n\n### 7.1 主程序流程\n\n```python\nasync def main() -> None:\n _ensure_storage() # 确保存储目录存在\n async with stdio_server() as (read_stream, write_stream):\n await server.run(\n read_stream,\n write_stream,\n server.create_initialization_options(),\n )\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[server.py:310-325]()\n\n### 7.2 启动流程图\n\n```mermaid\nsequenceDiagram\n participant C as MCP 客户端\n participant S as Agent Memory MCP\n participant FS as 文件系统\n \n C->>S: 启动进程\n S->>FS: 创建 ~/.agent-memory/ 目录\n FS-->>S: 目录就绪\n S->>C: STDIO 服务就绪\n C->>S: JSON-RPC 请求\n S->>S: 处理工具调用\n S->>FS: 读写 JSON 文件\n S-->>C: JSON-RPC 响应\n```\n\n## 8. 错误处理机制\n\n### 8.1 错误响应结构\n\n```python\ndef _error(message: str, fmt: Optional[str] = None) -> str:\n result = {\"status\": \"error\", \"error\": message, \"isError\": True}\n return _format_response(result, fmt)\n```\n\n### 8.2 异常捕获\n\n```python\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n try:\n # 工具执行逻辑\n ...\n except Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:225-237]()\n\n### 8.3 错误类型\n\n| 错误场景 | HTTP 类比状态码 | 说明 |\n|---------|----------------|------|\n| Key 不存在 | 404 | 尝试访问不存在的 key |\n| 命名空间错误 | 400 | 无效的命名空间名称 |\n| 内部错误 | 500 | 文件系统或处理异常 |\n\n## 9. 依赖架构\n\n### 9.1 外部依赖\n\n```\nmcp>=1.0.0\n```\n\n系统仅依赖 MCP SDK，所有其他功能均使用 Python 标准库实现。\n\n### 9.2 标准库使用\n\n| 模块 | 用途 |\n|------|------|\n| `asyncio` | 异步 I/O 支持 |\n| `fcntl` | 文件锁实现 |\n| `json` | 数据序列化 |\n| `pathlib` | 跨平台路径处理 |\n| `re` | 命名空间名称验证 |\n| `datetime` | 时间戳处理 |\n\n资料来源：[server.py:10-28]()\n\n## 10. 配置常量汇总\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CHARACTER_LIMIT` | 25,000 | 响应字符数上限 |\n| `DEFAULT_NAMESPACE` | \"default\" | 默认命名空间 |\n| `STORAGE_DIR` | `~/.agent-memory/` | 存储根目录 |\n| `META_FILE` | \"_meta.json\" | 元数据文件名 |\n\n资料来源：[server.py:52-59]()\n\n## 11. 架构优势\n\n| 特性 | 实现方式 | 优势 |\n|------|----------|------|\n| **本地优先** | JSON 文件存储 | 无需网络，数据本地化 |\n| **零依赖** | 仅使用标准库 | 部署简单，兼容性强 |\n| **并发安全** | fcntl 文件锁 | 多进程安全访问 |\n| **命名隔离** | 文件级命名空间 | 避免命名冲突 |\n| **幂等操作** | 注解声明 | 便于 MCP 客户端优化 |\n\n## 12. 扩展方向\n\n当前架构支持以下潜在扩展：\n\n1. **压缩存储**：对 JSON 文件进行 gzip 压缩\n2. **索引优化**：为高频查询字段建立索引\n3. **TTL 后台清理**：定时任务主动清理过期条目\n4. **审计日志**：记录所有操作的详细日志\n5. **加密存储**：对敏感数据进行加密\n\n---\n\n\n\n## 核心功能详解\n\n### 相关页面\n\n相关主题：[存储工具详解](#page-5), [查询工具详解](#page-6), [系统架构](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 核心功能详解\n\n## 概述\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值存储系统，专为 AI 代理设计。该项目由 Nous Research 开发，采用 MIT 开源许可证，旨在解决 AI 代理在会话之间丢失所有上下文的问题。\n\n核心价值主张：赋予 AI 代理持久化、可搜索的记忆能力，使其能够在会话重启、崩溃和上下文窗口限制中存活下来。\n\n资料来源：[README.md]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[AI 代理
Claude/GPT/Codex] --> B[MCP 协议
stdio JSON-RPC]\n B --> C[Agent Memory MCP 服务器]\n C --> D[键值存储引擎]\n C --> E[TTL 管理器]\n C --> F[搜索引擎
子串匹配]\n D --> G[~/.agent-memory/]\n E --> G\n F --> G\n G --> H[{namespace}.json]\n G --> I[_meta.json]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 实现方式 |\n|------|------|----------|\n| **MCP Server** | 处理 MCP 协议通信 | `mcp.server.Server` |\n| **KV Store Engine** | 键值存储读写 | JSON 文件操作 |\n| **TTL Manager** | 过期时间管理 | 懒清理机制 |\n| **Search Engine** | 跨命名空间搜索 | 子串匹配 + 访问计数排序 |\n| **File Locking** | 并发安全 | `fcntl.flock()` POSIX 文件锁 |\n\n资料来源：[server.py:1-50]()\n\n## 核心工具详解\n\n系统提供 7 个结构化工具，覆盖完整的内存管理生命周期。\n\n资料来源：[server.py:140-280]()\n\n### 工具概览表\n\n| 工具名称 | 功能描述 | 只读 | 破坏性 | 幂等性 |\n|----------|----------|------|--------|--------|\n| `memory_remember` | 存储键值对 | ❌ | ❌ | ❌ |\n| `memory_recall` | 检索键值对 | ✅ | ❌ | ✅ |\n| `memory_forget` | 删除键值对 | ❌ | ✅ | ✅ |\n| `memory_search` | 关键词搜索 | ✅ | ❌ | ✅ |\n| `memory_list_namespaces` | 列出命名空间 | ✅ | ❌ | ✅ |\n| `memory_clear_namespace` | 清空命名空间 | ❌ | ✅ | ❌ |\n| `memory_stats` | 获取统计信息 | ✅ | ❌ | ✅ |\n\n资料来源：[server.py:220-280]()\n\n---\n\n### 1. memory_remember\n\n**功能**：存储值到持久化内存命名空间，支持可选的 TTL（生存时间）。\n\n```python\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30 days\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 记忆条目的唯一标识符 |\n| `value` | string | ✅ | - | 要存储的内容 |\n| `namespace` | string | ❌ | `\"default\"` | 存储的命名空间 |\n| `ttl_seconds` | integer | ❌ | `null` | 自动过期秒数 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**返回值结构**：\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"namespace\": \"preferences\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\"\n}\n```\n\n资料来源：[server.py:142-175]()\n\n---\n\n### 2. memory_recall\n\n**功能**：按键检索值，返回完整元数据。\n\n```python\nresult = await memory_recall(\n key=\"user:timezone\",\n namespace=\"preferences\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `value` | string | 存储的值 |\n| `created_at` | string | 创建时间 ISO 8601 |\n| `accessed_at` | string | 最后访问时间 |\n| `expires_at` | string | TTL 过期时间（若有） |\n| `access_count` | integer | 访问次数 |\n\n资料来源：[server.py:176-200]()\n\n---\n\n### 3. memory_forget\n\n**功能**：永久删除指定键。\n\n```python\nresult = await memory_forget(\n key=\"temp:session:123\",\n namespace=\"sessions\"\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n资料来源：[server.py:201-215]()\n\n---\n\n### 4. memory_search\n\n**功能**：跨命名空间关键词搜索，大小写不敏感，按访问次数排序。\n\n```python\nresults = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\",\n limit=10\n)\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子串 |\n| `namespace` | string | ❌ | 全部 | 可选：限制搜索范围 |\n| `limit` | integer | ❌ | `10` | 最大返回结果数 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n**搜索算法**：\n\n1. 遍历指定命名空间（或全部命名空间）的 JSON 文件\n2. 对每个条目进行子串匹配，同时检查 key 和 value\n3. 懒清理已过期的 TTL 条目\n4. 按 `access_count` 降序排序返回结果\n\n资料来源：[server.py:230-260]()\n\n---\n\n### 5. memory_list_namespaces\n\n**功能**：列出所有内存命名空间及活跃/过期条目计数。\n\n```python\nnamespaces = await memory_list_namespaces()\n```\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | string | 命名空间名称 |\n| `active_count` | integer | 活跃条目数 |\n| `expired_count` | integer | 过期条目数 |\n| `file_path` | string | 对应 JSON 文件路径 |\n\n资料来源：[server.py:261-275]()\n\n---\n\n### 6. memory_clear_namespace\n\n**功能**：永久删除命名空间中的所有条目。\n\n```python\nawait memory_clear_namespace(namespace=\"agent:temp\")\n# → \"Cleared 156 entries from 'agent:temp'\"\n```\n\n**警告**：此操作不可撤销。\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 响应格式 |\n\n资料来源：[server.py:276-295]()\n\n---\n\n### 7. memory_stats\n\n**功能**：获取全局存储统计信息。\n\n```python\nstats = await memory_stats(format=\"markdown\")\n```\n\n**返回值结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `total_entries` | integer | 总条目数 |\n| `namespace_count` | integer | 命名空间数量 |\n| `storage_size` | string | 存储大小（如 \"2.4 MB\"） |\n| `oldest_entry` | string | 最旧条目时间 |\n| `newest_entry` | string | 最新条目时间 |\n| `expired_entries` | integer | 过期条目数 |\n| `tier` | string | 当前套餐（free/pro） |\n\n资料来源：[server.py:296-315]()\n\n## 数据存储机制\n\n### 存储目录结构\n\n```\n~/.agent-memory/\n├── default.json # 默认命名空间\n├── preferences.json # 用户偏好命名空间\n├── research.json # 研究数据命名空间\n└── _meta.json # 全局元数据\n```\n\n**存储路径**：`Path.home() / \".agent-memory\"` = `~/.agent-memory/`\n\n资料来源：[server.py:38-45]()\n\n### 命名空间文件安全\n\n命名空间名称经过严格的安全过滤：\n\n```python\nsafe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\nif not safe:\n safe = DEFAULT_NAMESPACE\n```\n\n允许的字符：`a-zA-Z0-9_.`-`，其他字符替换为下划线。空名称回退到 `default`。\n\n资料来源：[server.py:58-62]()\n\n### 条目数据模型\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 生成时机 |\n|------|------|----------|\n| `key` | 唯一标识符 | 写入时指定 |\n| `value` | 存储内容 | 写入时指定 |\n| `created_at` | 创建时间 | 首次写入 |\n| `accessed_at` | 最后访问时间 | 每次 recall |\n| `expires_at` | TTL 过期时间 | 设置 ttl_seconds 时 |\n| `access_count` | 访问计数器 | 每次 recall 递增 |\n\n资料来源：[server.py:100-130]()\n\n### 元数据文件结构\n\n```json\n{\n \"total_entries\": 1523,\n \"namespace_count\": 5,\n \"last_updated\": \"2026-05-12T15:00:00Z\"\n}\n```\n\n资料来源：[server.py:120-130]()\n\n## TTL 生命周期管理\n\n### TTL 工作流程\n\n```mermaid\ngraph LR\n A[memory_remember
ttl_seconds=3600] --> B[计算 expires_at]\n B --> C[存储条目]\n C --> D[recall/forget 时检查]\n D -->|未过期| E[返回结果]\n D -->|已过期| F[懒清理]\n F --> G[标记 expired=true]\n G --> H[下次扫描时删除]\n```\n\n### 懒清理机制\n\n系统采用懒清理策略，不主动后台任务清理过期条目：\n\n1. **读取时清理**：`memory_recall`、`memory_search` 执行时检查过期状态\n2. **写入时清理**：扫描命名空间时移除过期条目\n3. **不依赖外部调度**：无需 cron 或定时任务\n\n**优点**：降低系统复杂度，减少资源占用\n**权衡**：过期条目占用磁盘空间直到下次访问\n\n资料来源：[server.py:85-95]()\n\n## 并发控制\n\n### 文件锁机制\n\n系统使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全：\n\n```python\nwith _file_lock(namespace):\n # 读或写操作\n data = _read_namespace(namespace)\n _write_namespace(namespace, data)\n```\n\n**锁粒度**：命名空间级别（每个 JSON 文件独立锁）\n\n**并发场景支持**：\n\n| 场景 | 安全性 | 说明 |\n|------|--------|------|\n| 多进程读取 | ✅ | 读锁可共享 |\n| 多进程写入 | ✅ | 写锁互斥 |\n| 读同时写 | ✅ | 读写互斥 |\n| 跨命名空间 | ✅ | 无锁竞争 |\n\n资料来源：[server.py:70-80]()\n\n### 并发操作时序图\n\n```mermaid\nsequenceDiagram\n participant Agent1 as 代理进程 A\n participant Lock as 文件锁\n participant Agent2 as 代理进程 B\n \n Agent1->>Lock: 申请写锁 (LOCK_EX)\n Lock-->>Agent1: 锁授予\n Agent1->>Agent1: 读取 JSON\n Agent1->>Agent1: 修改数据\n Agent1->>Agent1: 写入 JSON\n Agent1->>Lock: 释放锁 (LOCK_UN)\n \n Agent2->>Lock: 申请写锁 (LOCK_EX)\n Lock-->>Agent2: 锁授予（等待后）\n Agent2->>Agent2: 读取 JSON\n Agent2->>Agent2: 修改数据\n Agent2->>Agent2: 写入 JSON\n Agent2->>Lock: 释放锁\n```\n\n## 响应格式化\n\n### 支持格式\n\n| 格式 | 说明 | 使用场景 |\n|------|------|----------|\n| `markdown` | 人类可读格式 | 调试、日志查看 |\n| `json` | 程序化解析 | 自动化流程 |\n\n### Markdown 格式示例\n\n```\n## ✅ Success\n\n**key:** user:theme\n**namespace:** preferences\n**created_at:** 2026-05-12T10:30:00Z\n**expires_at:** 2026-06-11T10:30:00Z\n```\n\n### JSON 格式示例\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"namespace\": \"preferences\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\"\n}\n```\n\n### 错误响应\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"Key 'xyz' not found in namespace 'default'\",\n \"isError\": true\n}\n```\n\n资料来源：[server.py:130-160]()\n\n## 定价与限制\n\n### 套餐对比\n\n| 套餐 | 价格 | 条目限制 | 命名空间限制 | 支持 |\n|------|------|----------|--------------|------|\n| **Free** | $0 | 1,000 条 | 5 个 | 社区支持 |\n| **Pro** | $19/月 | 无限 | 无限 | 优先支持 |\n\n资料来源：[smithery.yaml]()\n资料来源：[index.html]()\n\n## 依赖要求\n\n### 系统要求\n\n| 依赖 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 运行时环境 |\n| mcp | >=1.0.0 | MCP SDK 依赖 |\n\n### requirements.txt\n\n```\nmcp>=1.0.0\n```\n\n**无外部依赖**：系统使用 Python 标准库（`json`, `fcntl`, `pathlib`, `datetime`），仅需 MCP SDK。\n\n资料来源：[requirements.txt]()\n\n## 设计原则\n\n| 原则 | 实现方式 |\n|------|----------|\n| **简洁优先** | Redis 风格 KV，非向量数据库 |\n| **本地优先** | 数据存储在本地，无云服务/API密钥 |\n| **自描述** | 工具响应默认人类可读 markdown |\n| **容错性** | 懒 TTL 过期、非严格搜索、优雅错误处理 |\n\n资料来源：[README.md]()\n\n## MCP 配置示例\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n### VS Code / Cursor\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n### MCP Inspector 测试\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md]()\n\n## 使用场景\n\n### 跨会话用户偏好\n\n```python\n# 会话 1：代理学习用户偏好\nawait memory_remember(key=\"user:timezone\", value=\"America/Chicago\", namespace=\"preferences\")\nawait memory_remember(key=\"user:currency\", value=\"USD\", namespace=\"preferences\")\n\n# 会话 2（数天后）：代理即时回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 研究积累代理\n\n```python\n# 代理存储研究发现\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# 后续：搜索所有竞争对手研究\nfindings = await memory_search(query=\"competitor pricing\", namespace=\"research\")\n```\n\n### 代理临时便签\n\n```python\n# 代理使用内存作为工作便签\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh.\",\n namespace=\"agent:code-reviewer\"\n)\n```\n\n## 版本信息\n\n| 属性 | 值 |\n|------|-----|\n| 版本号 | 1.0.0 |\n| MCP Server 名称 | agent-memory |\n| 许可证 | MIT |\n| 开发者 | Nous Research |\n| GitHub | [nousresearch/agent-memory-mcp](https://github.com/nousresearch/agent-memory-mcp) |\n\n资料来源：[server.py:135-140]()\n资料来源：[smithery.yaml]()\n\n---\n\n\n\n## 存储工具详解\n\n### 相关页面\n\n相关主题：[查询工具详解](#page-6), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n \n\n# 存储工具详解\n\n## 概述\n\nagent-memory-mcp 的存储工具是整个系统的核心模块，提供了基于 MCP（Model Context Protocol）的持久化键值存储能力。这些工具使 AI Agent 能够在不同会话之间保持记忆，支持命名空间隔离、TTL（Time-To-Live）自动过期、模糊搜索和并发安全访问。\n\n存储系统采用本地 JSON 文件存储方案，数据持久化在 `~/.agent-memory/` 目录下，每个命名空间对应一个独立的 JSON 文件，配合元数据文件 `_meta.json` 记录全局统计信息。资料来源：[server.py:1-30]()\n\n## 架构设计\n\n### 系统组件\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP 客户端 (AI Agent) │\n│ remember / recall / forget / search / list / clear / stats │\n└───────────────────────────┬─────────────────────────────────┘\n │ MCP Protocol (stdio JSON-RPC)\n┌───────────────────────────▼─────────────────────────────────┐\n│ Agent Memory MCP Server │\n│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │\n│ │ KV 存储 │ │ TTL 管理 │ │ 搜索引擎 │ │\n│ │ 引擎 │ │ 处理器 │ │ (子字符串匹配) │ │\n│ └──────┬─────┘ └─────┬──────┘ └─────────┬──────────┘ │\n│ │ │ │ │\n│ ┌──────▼───────────────▼───────────────────▼──────────┐ │\n│ │ ~/.agent-memory/ │ │\n│ │ {namespace}.json │ _meta.json │ │\n│ └────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 存储目录结构\n\n| 文件 | 用途 | 描述 |\n|------|------|------|\n| `{namespace}.json` | 命名空间数据 | 每个命名空间独立存储，包含内存条目数组 |\n| `_meta.json` | 全局元数据 | 记录总条目数、命名空间数量等全局统计 |\n\n资料来源：[server.py:47-50]()\n\n## 存储工具清单\n\n### 工具功能对照表\n\n| 工具名称 | 功能描述 | 读取操作 | 写入操作 | 删除操作 |\n|----------|----------|----------|----------|----------|\n| `memory_remember` | 存储键值对（支持TTL） | ❌ | ✅ | ❌ |\n| `memory_recall` | 检索键值及元数据 | ✅ | ❌ | ❌ |\n| `memory_forget` | 删除指定键 | ❌ | ❌ | ✅ |\n| `memory_search` | 跨命名空间关键词搜索 | ✅ | ❌ | ❌ |\n| `memory_list_namespaces` | 列出所有命名空间 | ✅ | ❌ | ❌ |\n| `memory_clear_namespace` | 清空整个命名空间 | ❌ | ❌ | ✅ |\n| `memory_stats` | 获取全局存储统计 | ✅ | ❌ | ❌ |\n\n## 核心 API 参数详解\n\n### 1. memory_remember\n\n存储一个新的键值对到指定命名空间，支持可选的 TTL 自动过期时间。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 内存条目的唯一标识符 |\n| `value` | string | ✅ | - | 要存储的实际内容 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `ttl_seconds` | integer | ❌ | `null` | 存活秒数，设置后自动过期 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式：`\"markdown\"` 或 `\"json\"` |\n\n**条目数据结构：**\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T10:30:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 1\n}\n```\n\n资料来源：[server.py:54-59]()\n\n### 2. memory_recall\n\n根据键名检索存储的值，同时返回完整的访问元数据。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键名 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回的元数据字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `value` | string | 存储的实际值 |\n| `created_at` | string | 创建时间戳（ISO 8601） |\n| `accessed_at` | string | 最后访问时间戳 |\n| `expires_at` | string/null | TTL 过期时间（未设置则为 null） |\n| `access_count` | integer | 累计访问次数 |\n\n每次调用 `memory_recall` 会自动更新 `accessed_at` 和 `access_count`，实现访问追踪功能。资料来源：[server.py:63-67]()\n\n### 3. memory_forget\n\n永久删除指定的键值对。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键名 |\n| `namespace` | string | ❌ | `\"default\"` | 目标命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `false` | 修改性操作 |\n| `destructiveHint` | `true` | 破坏性操作 |\n| `idempotentHint` | `true` | 重复执行结果一致 |\n\n资料来源：[server.py:73-83]()\n\n### 4. memory_search\n\n在所有命名空间或指定命名空间中搜索关键词，匹配键名和值的子字符串。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | `null` | 限定搜索范围（为空则搜索全部） |\n| `limit` | integer | ❌ | `10` | 最大返回结果数 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**搜索特性：**\n\n- **大小写不敏感**：搜索 `\"User\"` 可匹配 `\"user\"`、`\"USER\"` 等\n- **子字符串匹配**：搜索 `\"them\"` 可匹配 `\"theme\"`、`\"something\"` 等\n- **全字段匹配**：同时匹配 `key` 和 `value`\n- **结果排序**：按 `access_count` 降序排列\n\n**搜索流程：**\n\n```mermaid\ngraph TD\n A[输入搜索查询] --> B{指定 namespace?}\n B -->|是| C[只扫描指定命名空间]\n B -->|否| D[扫描所有命名空间 JSON 文件]\n C --> E[遍历条目列表]\n D --> E\n E --> F{key 或 value 包含查询?
大小写不敏感}\n F -->|是| G[加入结果集]\n F -->|否| H[跳过]\n G --> I{access_count 高于当前结果?}\n I -->|是| J[优先排序]\n I -->|否| K[保持原位置]\n J --> L{达到 limit?}\n K --> L\n L -->|否| E\n L -->|是| M[返回排序结果]\n```\n\n资料来源：[server.py:88-110]()\n\n### 5. memory_list_namespaces\n\n列出所有已存在的命名空间及其条目统计。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回数据：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | string | 命名空间名称 |\n| `active_count` | integer | 未过期的条目数 |\n| `expired_count` | integer | 已过期但未清理的条目数 |\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `true` | 只读操作 |\n| `destructiveHint` | `false` | 非破坏性操作 |\n| `openWorldHint` | `true` | 可能访问外部数据源 |\n\n资料来源：[server.py:115-130]()\n\n### 6. memory_clear_namespace\n\n清空指定命名空间中的所有条目。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**警告：** 此操作不可撤销，会永久删除该命名空间下的所有数据。\n\n**工具注解：**\n\n| 注解 | 值 | 说明 |\n|------|-----|------|\n| `readOnlyHint` | `false` | 修改性操作 |\n| `destructiveHint` | `true` | 破坏性操作 |\n| `idempotentHint` | `true` | 重复执行结果一致 |\n| `openWorldHint` | `false` | 仅本地操作 |\n\n资料来源：[server.py:135-154]()\n\n### 7. memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 返回格式 |\n\n**返回的统计数据：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `total_entries` | integer | 所有命名空间的条目总数（不含过期） |\n| `namespace_count` | integer | 命名空间总数 |\n| `total_size` | string | 存储目录大小（人类可读格式） |\n| `oldest_entry` | string | 最早条目的相对时间 |\n| `newest_entry` | string | 最新条目的相对时间 |\n| `expired_entries` | integer | 已过期条目数量 |\n\n资料来源：[server.py:159-178]()\n\n## 存储机制详解\n\n### 文件路径规范\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n命名空间路径通过正则表达式进行安全化处理，防止目录遍历攻击：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n| 原始命名空间 | 安全化后 | 文件路径 |\n|-------------|---------|----------|\n| `user:preferences` | `user_preferences` | `~/.agent-memory/user_preferences.json` |\n| `agent:code-reviewer` | `agent_code-reviewer` | `~/.agent-memory/agent_code-reviewer.json` |\n| `../etc/passwd` | `.._etc_passwd` | `~/.agent-memory/.._etc_passwd.json` |\n\n资料来源：[server.py:63-69]()\n\n### TTL 过期机制\n\n系统采用**惰性过期检查**策略，在以下时机检查并清理过期条目：\n\n1. `memory_recall` - 访问时检查\n2. `memory_search` - 搜索时检查\n3. `_read_namespace` - 读取命名空间时检查\n\n```mermaid\ngraph LR\n A[读取条目] --> B{有 expires_at?}\n B -->|是| C{当前时间 > expires_at?}\n C -->|是| D[标记为过期
返回 None]\n C -->|否| E[正常返回]\n B -->|否| E\n```\n\n**过期检查逻辑：**\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n if not entry.get(\"expires_at\"):\n return False\n return datetime.now(UTC) > datetime.fromisoformat(entry[\"expires_at\"])\n```\n\n资料来源：[server.py:115-119]()\n\n### 并发控制\n\n系统使用 `fcntl.flock()` 实现 POSIX 文件锁，确保多进程并发安全：\n\n```python\n@contextmanager\ndef _locked(path: Path, exclusive: bool = True):\n with path.open(\"a+\") as fh:\n lock_type = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH\n fcntl.flock(fh.fileno(), lock_type)\n try:\n yield fh\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n| 锁类型 | 应用场景 | 并发读 | 并发写 |\n|--------|----------|--------|--------|\n| `LOCK_EX` (排他锁) | `memory_remember`、`memory_forget`、`memory_clear_namespace` | ❌ | ❌ |\n| `LOCK_SH` (共享锁) | `memory_recall`、`memory_search`、`memory_list_namespaces`、`memory_stats` | ✅ | ❌ |\n\n资料来源：[server.py:32-41]()\n\n### 元数据管理\n\n`_meta.json` 存储全局统计信息，由 `_recalc_meta()` 动态计算：\n\n```python\ndef _recalc_meta() -> None:\n total = 0\n namespace_count = 0\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n namespace_count += 1\n entries = _read_namespace(p.stem)\n total += len([e for e in entries if not _is_expired(e)])\n _write_meta({\"total_entries\": total, \"namespace_count\": namespace_count})\n```\n\n资料来源：[server.py:195-204]()\n\n## 使用示例\n\n### 基本存储操作\n\n```python\n# 存储用户偏好（永久）\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\"\n)\n\n# 存储研究数据（7天过期）\nawait memory_remember(\n key=\"competitor:pricing:stripe\",\n value=\"Stripe charges 2.9% + $0.30 per transaction\",\n namespace=\"research\",\n ttl_seconds=604800 # 7 days\n)\n```\n\n### 跨会话记忆\n\n```python\n# Session 1: 学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\n\n# Session 2 (days later): 立即回忆偏好\ntz = await memory_recall(\"user:timezone\", \"preferences\")\n# 无需再次询问用户\n```\n\n### 搜索与清理\n\n```python\n# 搜索所有相关研究\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n\n# 清理旧数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n```\n\n## 响应格式化\n\n所有工具支持两种响应格式，通过 `format` 参数控制：\n\n| 格式 | 适用场景 | 示例输出 |\n|------|----------|----------|\n| `\"markdown\"` | 人类可读 | H2 标题、表格、加粗文本 |\n| `\"json\"` | 程序处理 | 结构化 JSON 对象 |\n\n**Markdown 格式响应结构：**\n\n```markdown\n## ✅ Success\n**key:** user:theme\n**value:** dark\n**created_at:** 2026-05-12T10:30:00Z\n**namespace:** preferences\n```\n\n**JSON 格式响应结构：**\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"namespace\": \"preferences\"\n}\n```\n\n资料来源：[server.py:128-154]()\n\n## 限制与配额\n\n| 层级 | 价格 | 条目限制 | 命名空间限制 |\n|------|------|----------|--------------|\n| Free | $0 | 1,000 条 | 5 个 |\n| Pro | $19/月 | 无限 | 无限 |\n\n存储大小超过限制时，系统返回警告信息但仍允许写入。资料来源：[smithery.yaml:17-27]()\n\n## 错误处理\n\n| 错误类型 | HTTP 状态 | 说明 |\n|----------|-----------|------|\n| 未知工具 | - | 返回 \"Unknown tool: {name}\" |\n| 内部错误 | `isError: true` | 捕获异常并返回详细错误信息 |\n| 命名空间为空 | - | 返回确认消息而非错误 |\n\n```python\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:203-211]()\n\n## 工具注解汇总\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | true |\n| `memory_list_namespaces` | true | false | true | true |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n资料来源：[server.py:83-178]()\n\n## 扩展配置\n\n### MCP 客户端配置\n\n**Claude Desktop:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n### 环境变量\n\n系统当前无额外环境变量要求。数据目录通过 `Path.home() / \".agent-memory\"` 自动确定。\n\n---\n\n\n\n## 查询工具详解\n\n### 相关页面\n\n相关主题：[存储工具详解](#page-5), [数据存储机制](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 查询工具详解\n\n## 概述\n\nAgent Memory MCP 提供了一套完整的查询工具，用于在持久化内存存储中检索和搜索数据。这套查询工具的核心是 `memory_search`（模糊搜索），辅以 `memory_list_namespaces`（命名空间列表）和 `memory_stats`（存储统计）两个辅助工具。三者共同构成了一个层次化的查询体系，使用户和 AI Agent 能够高效地定位和管理记忆数据。\n\n查询工具的设计遵循以下原则：\n\n- **读操作为主**：所有查询工具均标记为 `readOnlyHint=True`，不会修改底层数据\n- **幂等性保障**：重复执行相同查询将返回一致结果（`idempotentHint=True`）\n- **格式灵活**：支持 Markdown（人类可读）和 JSON（程序化处理）两种输出格式\n\n资料来源：[server.py:1-50]()\n\n## 工具清单\n\n| 工具名称 | 功能描述 | 只读 | 幂等 |\n|---------|---------|------|------|\n| `memory_search` | 在所有命名空间中按关键词搜索记忆 | ✅ | ✅ |\n| `memory_list_namespaces` | 列出所有命名空间及其条目计数 | ✅ | ✅ |\n| `memory_stats` | 获取全局存储统计信息 | ✅ | ✅ |\n\n资料来源：[server.py:160-200]()\n\n## 核心工具详解\n\n### 1. memory_search（模糊搜索）\n\n`memory_search` 是 Agent Memory MCP 中功能最强大的查询工具，支持跨命名空间的模糊匹配搜索。\n\n#### 功能特性\n\n- **跨命名空间搜索**：默认情况下搜索所有命名空间，可通过 `namespace` 参数限定范围\n- **模糊匹配**：同时匹配 key 和 value 中的子字符串\n- **大小写不敏感**：搜索不区分大小写\n- **相关性排序**：结果按访问次数（`access_count`）降序排列，热门记忆优先返回\n\n#### 参数定义\n\n```json\n{\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索关键词或子字符串\",\n \"required\": true\n },\n \"namespace\": {\n \"type\": \"string\",\n \"description\": \"可选的命名空间限定。省略则搜索所有命名空间\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"最大返回结果数（默认: 10）\",\n \"default\": 10\n },\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n资料来源：[server.py:180-210]()\n\n#### 实现逻辑\n\n搜索功能的核心实现在 `_search_namespace` 辅助函数中：\n\n```python\ndef _search_namespace(\n namespace: str,\n query: str,\n limit: int = 10,\n) -> List[Dict[str, Any]]:\n \"\"\"Search within a single namespace, returning top matches by access count.\"\"\"\n entries = _read_namespace(namespace)\n # Filter: case-insensitive substring match on key OR value\n matched = [\n e for e in entries\n if not _is_expired(e) and (\n query.lower() in e[\"key\"].lower() or\n query.lower() in str(e.get(\"value\", \"\")).lower()\n )\n ]\n # Sort by access_count descending\n matched.sort(key=lambda e: e[\"access_count\"], reverse=True)\n return matched[:limit]\n```\n\n关键实现要点：\n\n1. **过期检查**：使用 `_is_expired()` 函数排除已过期的记忆条目\n2. **双重匹配**：同时检查 key 和 value 是否包含查询字符串\n3. **排序策略**：按 `access_count` 降序排列，确保高频访问的记忆优先显示\n4. **结果限制**：使用切片操作 `[:limit]` 限制返回数量\n\n资料来源：[server.py:220-240]()\n\n### 2. memory_list_namespaces（命名空间列表）\n\n此工具用于获取系统中所有命名空间的概览信息，包括活跃条目数和过期条目数。\n\n#### 参数定义\n\n```json\n{\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n#### 返回数据结构\n\n```json\n{\n \"namespaces\": [\n {\n \"name\": \"research\",\n \"active_entries\": 42,\n \"expired_entries\": 3\n },\n {\n \"name\": \"preferences\",\n \"active_entries\": 15,\n \"expired_entries\": 0\n }\n ]\n}\n```\n\n#### 实现逻辑\n\n```python\ndef memory_list_namespaces(fmt: Optional[str] = None) -> str:\n \"\"\"List all namespaces with entry counts.\"\"\"\n namespaces = []\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n entries = _read_namespace(p.stem)\n active = [e for e in entries if not _is_expired(e)]\n namespaces.append({\n \"name\": p.stem,\n \"active_entries\": len(active),\n \"expired_entries\": len(entries) - len(active),\n })\n return _success({\"namespaces\": namespaces}, fmt)\n```\n\n资料来源：[server.py:245-260]()\n\n### 3. memory_stats（存储统计）\n\n此工具提供全局存储的统计信息，帮助用户了解存储使用情况和配额限制。\n\n#### 参数定义\n\n```json\n{\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\"markdown\", \"json\"],\n \"description\": \"响应格式（默认: markdown）\"\n }\n}\n```\n\n#### 返回数据示例（Markdown 格式）\n\n```\n## 存储统计\n\n**总条目数**: 1,247\n**存储大小**: 2.3 MB\n**命名空间数**: 5\n**最早条目**: 2026-04-15（27天前）\n**最新条目**: 刚刚\n**已过期条目**: 12\n```\n\n#### 实现逻辑\n\n```python\ndef memory_stats(fmt: Optional[str] = None) -> str:\n \"\"\"Get storage statistics.\"\"\"\n _recalc_meta() # 重新计算全局元数据\n meta = _read_meta()\n \n # 计算存储大小\n total_size = sum(p.stat().st_size for p in STORAGE_DIR.glob(\"*.json\"))\n \n # 查找最早和最新条目\n oldest, newest = None, None\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n entries = _read_namespace(p.stem)\n for e in entries:\n ts = e.get(\"created_at\")\n if ts:\n if not oldest or ts < oldest:\n oldest = ts\n if not newest or ts > newest:\n newest = ts\n \n return _success({\n \"total_entries\": meta.get(\"total_entries\", 0),\n \"storage_size\": _format_size(total_size),\n \"namespace_count\": meta.get(\"namespace_count\", 0),\n \"oldest_entry\": oldest,\n \"newest_entry\": newest,\n \"expired_entries\": 0,\n }, fmt)\n```\n\n资料来源：[server.py:260-290]()\n\n## 工具注解（Tool Annotations）\n\nMCP 协议支持为每个工具提供语义注解，帮助客户端理解工具的行为特性：\n\n| 注解字段 | memory_search | memory_list_namespaces | memory_stats |\n|---------|---------------|------------------------|--------------|\n| `readOnlyHint` | `true` | `true` | `true` |\n| `destructiveHint` | `false` | `false` | `false` |\n| `idempotentHint` | `true` | `true` | `true` |\n| `openWorldHint` | `true` | `true` | `true` |\n\n**注解含义说明**：\n\n- `readOnlyHint`：表示该工具不会修改服务器状态\n- `destructiveHint`：表示该工具不会删除或破坏数据\n- `idempotentHint`：表示重复执行不会产生额外副作用\n- `openWorldHint`：表示该工具可能涉及外部世界交互（搜索功能搜索所有命名空间）\n\n资料来源：[server.py:195-200]()\n\n## 架构流程图\n\n### 查询请求处理流程\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B{memory_search?}\n A --> C{memory_list_namespaces?}\n A --> D{memory_stats?}\n \n B --> E[解析 query 参数]\n E --> F{namespace 参数存在?}\n F -->|是| G[搜索指定命名空间]\n F -->|否| H[遍历所有命名空间]\n G --> I[过滤过期条目]\n H --> I\n I --> J[按 access_count 排序]\n J --> K[限制返回数量]\n K --> L[格式化响应]\n \n C --> M[扫描 STORAGE_DIR]\n M --> N[读取每个命名空间文件]\n N --> O[统计活跃/过期条目]\n O --> L\n \n D --> P[重新计算全局元数据]\n P --> Q[计算存储大小]\n Q --> R[查找最老/最新条目]\n R --> L\n \n L --> S[返回 Markdown 或 JSON]\n \n subgraph \"存储层 ~/.agent-memory/\"\n T[\"{namespace}.json\"]\n U[\"_meta.json\"]\n end\n \n G --> T\n H --> T\n N --> T\n P --> U\n Q --> T\n R --> T\n```\n\n### 数据存储结构\n\n```mermaid\ngraph LR\n A[\"~/.agent-memory/\"] --> B[\"{namespace}.json\"]\n A --> C[\"_meta.json\"]\n \n B --> D[\"entries[]\"]\n D --> E[\"key\"]\n D --> F[\"value\"]\n D --> G[\"created_at\"]\n D --> H[\"accessed_at\"]\n D --> I[\"expires_at\"]\n D --> J[\"access_count\"]\n \n C --> K[\"total_entries\"]\n C --> L[\"namespace_count\"]\n```\n\n## 使用场景示例\n\n### 跨会话上下文恢复\n\n```python\n# Agent 在首次会话中存储用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\n\n# 后续会话中快速查询用户时区\ntz = await memory_search(\n query=\"timezone\",\n namespace=\"preferences\"\n)\n```\n\n### 研究积累与检索\n\n```python\n# 持续积累研究数据\nawait memory_remember(\n key=\"competitor:acme:pricing\",\n value=\"Acme Pro: $49/mo, Enterprise: $199/mo\",\n namespace=\"research\"\n)\n\n# 在所有命名空间中搜索竞争对手相关信息\nresults = await memory_search(\n query=\"competitor\",\n limit=20\n)\n```\n\n### 存储健康检查\n\n```python\n# 查看存储使用情况\nstats = await memory_stats()\n\n# 检查命名空间分布\nnamespaces = await memory_list_namespaces()\n\n# 定位过期数据\nfor ns in namespaces[\"namespaces\"]:\n if ns[\"expired_entries\"] > 100:\n print(f\"命名空间 {ns['name']} 有 {ns['expired_entries']} 个过期条目\")\n```\n\n## 响应格式化\n\n所有查询工具支持两种输出格式，通过 `format` 参数指定：\n\n### Markdown 格式（默认）\n\n```\n## ✅ Success\n\n**key:** user:timezone\n**value:** America/Chicago\n**created_at:** 2026-05-01T10:00:00Z\n**accessed_at:** 2026-05-12T14:22:00Z\n**access_count:** 47\n```\n\n### JSON 格式\n\n```json\n{\n \"status\": \"ok\",\n \"key\": \"user:timezone\",\n \"value\": \"America/Chicago\",\n \"created_at\": \"2026-05-01T10:00:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"access_count\": 47\n}\n```\n\n格式化逻辑统一由 `_format_response` 函数处理：\n\n```python\ndef _format_response(result: Dict[str, Any], fmt: Optional[str] = None) -> str:\n \"\"\"Format a result dictionary as either JSON or Markdown.\"\"\"\n if fmt == \"json\":\n return json.dumps(result, indent=2)\n # Markdown (default)\n lines = []\n # ... 构建 Markdown 格式字符串\n return \"\\n\".join(lines)\n```\n\n资料来源：[server.py:100-140]()\n\n## 错误处理\n\n查询工具的错误处理遵循统一模式：\n\n```python\ntry:\n if name == \"memory_search\":\n text = memory_search(**arguments, fmt=fmt)\n elif name == \"memory_list_namespaces\":\n text = memory_list_namespaces(fmt=fmt)\n elif name == \"memory_stats\":\n text = memory_stats(fmt=fmt)\n # ...\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n错误响应示例：\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"Internal error in memory_search: list index out of range\",\n \"isError\": true\n}\n```\n\n资料来源：[server.py:260-280]()\n\n## 线程安全性\n\n查询工具虽然都是只读操作，但在并发环境下仍需考虑数据一致性。系统使用 `fcntl.flock()` 实现文件级锁：\n\n```python\n@contextmanager\ndef _locked(path: Path) -> Any:\n \"\"\"Context manager for file locking with fcntl.flock.\"\"\"\n with path.open(\"a\") as fh:\n fcntl.flock(fh.fileno(), fcntl.LOCK_EX)\n try:\n yield fh\n finally:\n fcntl.flock(fh.fileno(), fcntl.LOCK_UN)\n```\n\n所有涉及文件读写的操作（`_read_namespace`、`_write_namespace` 等）都通过此上下文管理器保护，确保在多个 Agent 进程并发访问时不会产生数据竞争。\n\n资料来源：[server.py:60-80]()\n\n## 配额与限制\n\n根据 smithery.yaml 配置，查询工具受以下配额限制：\n\n| 套餐 | 价格 | 条目上限 | 命名空间上限 |\n|------|------|---------|-------------|\n| Free | $0 | 1,000 条 | 5 个 |\n| Pro | $19/月 | 无限 | 无限 |\n\n超出免费配额后，系统仍可正常执行查询操作，但建议用户升级至 Pro 套餐以获得无限存储能力。\n\n资料来源：[smithery.yaml:20-35]()\n\n## 总结\n\nAgent Memory MCP 的查询工具套件为 AI Agent 提供了一个高效、可靠的记忆检索系统：\n\n- **`memory_search`**：核心搜索工具，支持跨命名空间模糊匹配和相关性排序\n- **`memory_list_namespaces`**：命名空间管理工具，帮助用户了解数据分布\n- **`memory_stats`**：系统健康检查工具，提供存储使用统计\n\n这三个工具协同工作，使 Agent 能够在任意会话中快速定位历史记忆，实现真正的持久化上下文管理。所有工具均遵循只读、幂等的设计原则，确保在复杂的多 Agent 环境中安全可靠运行。\n\n---\n\n\n\n## 数据存储机制\n\n### 相关页面\n\n相关主题：[系统架构](#page-3), [使用场景与最佳实践](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 数据存储机制\n\n## 概述\n\nAgent Memory MCP 的数据存储机制是一个基于文件系统的持久化键值存储系统，专为 AI 代理设计。该系统将所有数据存储在用户本地目录 `~/.agent-memory/` 中，以 JSON 文件格式保存，支持命名空间隔离、时间 TTL（生存时间）管理、访问计数追踪和模糊搜索功能。资料来源：[server.py:27-29]()\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[Agent Memory MCP Server]\n B --> C[KV Store Engine]\n B --> D[TTL Manager]\n B --> E[Search Engine]\n C --> F[~/.agent-memory/]\n D --> F\n E --> F\n F --> G[{namespace}.json]\n F --> H[_meta.json]\n```\n\n## 存储目录结构\n\n### 目录位置\n\n默认存储目录位于用户主目录下的隐藏文件夹 `.agent-memory/`。系统启动时会自动创建该目录，无需手动配置。\n\n| 属性 | 值 |\n|------|-----|\n| 路径 | `~/.agent-memory/` |\n| 类型 | 用户主目录下的隐藏文件夹 |\n| 创建时机 | 服务首次启动时 |\n| 权限 | 继承系统默认权限 |\n\n资料来源：[server.py:30]()\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n### 目录结构设计\n\n```\n~/.agent-memory/\n├── _meta.json # 全局元数据统计文件\n├── default.json # 默认命名空间数据\n├── {namespace1}.json # 各命名空间独立存储\n├── {namespace2}.json\n└── {namespaceN}.json\n```\n\n每个命名空间对应一个独立的 JSON 文件，全局统计信息存储在 `_meta.json` 中。\n\n资料来源：[server.py:32]()\n\n```python\nMETA_FILE = \"_meta.json\"\n```\n\n## 命名空间管理\n\n### 命名空间概念\n\n命名空间（Namespace）用于隔离不同用途或不同代理的内存数据。这种设计允许：\n\n- 按项目分离数据\n- 按用户分离数据\n- 按功能域分离数据\n- 实现数据完全独立的存储空间\n\n资料来源：[README.md:72-74]()\n\n### 命名空间路径解析\n\n系统通过 `_namespace_path()` 函数将命名空间名称转换为安全的文件路径。命名空间名称会经过正则表达式处理，移除所有非法字符。\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n \"\"\"Return the full path for a namespace JSON file.\"\"\"\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n关键安全措施：\n- 只允许字母、数字、下划线、点和连字符\n- 所有非法字符替换为下划线\n- 空名称回退到默认命名空间\n- 文件路径无法逃逸到目录之外\n\n资料来源：[server.py:42-51]()\n\n### 默认命名空间\n\n如果未指定命名空间，系统使用 `default` 作为默认值。\n\n```python\nDEFAULT_NAMESPACE = \"default\"\n```\n\n资料来源：[server.py:31]()\n\n## 数据模型\n\n### 内存条目结构\n\n每个内存条目（Entry）是一个包含以下字段的 JSON 对象：\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `key` | string | 唯一键标识符 |\n| `value` | string | 存储的值/内容 |\n| `created_at` | ISO 8601 | 创建时间戳 |\n| `accessed_at` | ISO 8601 | 最后访问时间 |\n| `expires_at` | ISO 8601 或 null | TTL 过期时间（可选） |\n| `access_count` | integer | 访问次数计数器 |\n\n资料来源：[README.md:85-93]()\n\n### TTL 过期机制\n\n过期时间（TTL）通过 `expires_at` 字段实现。当设置 `ttl_seconds` 参数时，系统计算过期时间戳：\n\n```python\nif ttl_seconds:\n entry[\"expires_at\"] = datetime.now(timezone.utc).timestamp() + ttl_seconds\nelse:\n entry[\"expires_at\"] = None\n```\n\n过期检查采用**惰性清理**策略：在 `memory_recall` 和 `memory_search` 操作时，系统检查条目是否过期并自动移除。\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"检查条目是否已过期\"\"\"\n if entry.get(\"expires_at\") is None:\n return False\n return datetime.now(timezone.utc).timestamp() > entry[\"expires_at\"]\n```\n\n资料来源：[server.py:108-114]()\n\n## 文件操作与并发控制\n\n### 文件锁定机制\n\n系统使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全的并发访问。这是实现多进程安全的关键机制。\n\n```python\n@contextmanager\ndef _file_lock(path: Path, lock_type: int = fcntl.LOCK_EX):\n \"\"\"文件锁上下文管理器，支持读锁和写锁\"\"\"\n lock_path = path.with_suffix(\".lock\")\n with lock_path.open(\"w\") as lock_file:\n try:\n fcntl.flock(lock_file.fileno(), lock_type)\n yield\n finally:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n```\n\n| 锁类型 | 用途 | 并发读 | 并发写 |\n|--------|------|--------|--------|\n| `LOCK_EX` (排他锁) | 写入操作 | ❌ | ❌ |\n| `LOCK_SH` (共享锁) | 读取操作 | ✅ | ❌ |\n\n资料来源：[server.py:60-74]()\n\n### 读写操作实现\n\n**读取命名空间数据：**\n\n```python\ndef _read_namespace(namespace: str) -> List[Dict[str, Any]]:\n \"\"\"读取命名空间的所有条目\"\"\"\n path = _namespace_path(namespace)\n if not path.exists():\n return []\n with _file_lock(path, fcntl.LOCK_SH):\n with path.open(\"r\", encoding=\"utf-8\") as f:\n return json.load(f)\n```\n\n**写入命名空间数据：**\n\n```python\ndef _write_namespace(namespace: str, entries: List[Dict[str, Any]]) -> None:\n \"\"\"写入命名空间的所有条目\"\"\"\n path = _namespace_path(namespace)\n with _file_lock(path, fcntl.LOCK_EX):\n with path.open(\"w\", encoding=\"utf-8\") as f:\n json.dump(entries, f, ensure_ascii=False, indent=2)\n```\n\n资料来源：[server.py:76-90]()\n\n### 锁定文件结构\n\n对于每个命名空间文件，系统会创建对应的锁文件：\n\n```\n~/.agent-memory/\n├── _meta.json\n├── _meta.json.lock # 元数据文件锁\n├── default.json\n├── default.json.lock # 默认命名空间锁\n├── research.json\n└── research.json.lock # 研究命名空间锁\n```\n\n## 元数据管理\n\n### 全局元数据文件\n\n`_meta.json` 文件存储全局统计信息：\n\n```json\n{\n \"total_entries\": 150,\n \"namespace_count\": 5,\n \"oldest_entry\": \"2026-04-15T10:00:00Z\",\n \"newest_entry\": \"2026-06-12T14:30:00Z\"\n}\n```\n\n### 元数据计算\n\n系统通过 `_recalc_meta()` 函数扫描所有命名空间文件来重新计算全局统计：\n\n```python\ndef _recalc_meta() -> None:\n \"\"\"Recompute global metadata by scanning all namespaces.\"\"\"\n total = 0\n namespace_count = 0\n for p in STORAGE_DIR.glob(\"*.json\"):\n if p.stem == \"_meta\":\n continue\n namespace_count += 1\n entries = _read_namespace(p.stem)\n total += len([e for e in entries if not _is_expired(e)])\n _write_meta({\"total_entries\": total, \"namespace_count\": namespace_count})\n```\n\n该函数在 `memory_stats` 操作时被调用。\n\n资料来源：[server.py:167-178]()\n\n## 存储操作实现\n\n### 写入操作 (memory_remember)\n\n```mermaid\ngraph TD\n A[memory_remember 调用] --> B{key 是否存在?}\n B -->|存在| C[更新 existing_entry]\n B -->|不存在| D[创建 new_entry]\n C --> E[更新 accessed_at]\n D --> E\n E --> F[access_count 递增]\n F --> G[写入文件锁]\n G --> H[JSON 序列化]\n H --> I[写入 {namespace}.json]\n I --> J[释放文件锁]\n J --> K[返回成功响应]\n```\n\n资料来源：[server.py:180-230]()\n\n### 读取操作 (memory_recall)\n\n```mermaid\ngraph TD\n A[memory_recall 调用] --> B[获取文件锁 SH]\n B --> C[读取 JSON]\n C --> D{条目存在?}\n D -->|否| E[返回错误]\n D -->|是| F{条目过期?}\n F -->|是| G[删除过期条目]\n F -->|否| H[更新 accessed_at]\n H --> I[access_count 递增]\n G --> J[写入更新]\n I --> J\n J --> K[释放文件锁]\n K --> L[返回记忆数据]\n```\n\n资料来源：[server.py:232-285]()\n\n### 搜索操作 (memory_search)\n\n搜索功能支持模糊匹配，同时搜索键名和值内容：\n\n```python\nquery_lower = query.lower()\nfor entry in entries:\n if query_lower in entry[\"key\"].lower() or query_lower in entry[\"value\"].lower():\n results.append(entry)\n\nresults.sort(key=lambda e: e.get(\"access_count\", 0), reverse=True)\n```\n\n搜索特性：\n- **大小写不敏感**：所有匹配在比较前转换为小写\n- **子串匹配**：支持关键词子串搜索\n- **跨键值搜索**：同时匹配键名和值内容\n- **访问频率排序**：结果按访问次数降序排列\n\n资料来源：[server.py:287-345]()\n\n## 存储限制与配额\n\n### 层级限制\n\n| 层级 | 价格 | 条目限制 | 命名空间限制 |\n|------|------|----------|--------------|\n| Free（免费） | $0 | 1,000 条 | 5 个 |\n| Pro（专业） | $19/月 | 无限 | 无限 |\n\n资料来源：[README.md:106-111]()\n\n### 响应大小限制\n\n系统设置了字符输出限制，防止超大响应导致协议问题：\n\n```python\nCHARACTER_LIMIT = 25_000\n```\n\n超过限制的响应会被截断：\n\n```python\ndef _truncate(text: str, limit: int = CHARACTER_LIMIT) -> str:\n \"\"\"Truncate text if it exceeds the character limit.\"\"\"\n if len(text) > limit:\n return text[: limit - 3] + \"...\"\n return text\n```\n\n资料来源：[server.py:35](), [server.py:143-146]()\n\n## 依赖关系\n\n### Python 标准库依赖\n\n项目仅依赖 Python 标准库和 MCP SDK：\n\n| 模块 | 用途 |\n|------|------|\n| `asyncio` | 异步运行时 |\n| `fcntl` | POSIX 文件锁定 |\n| `json` | JSON 序列化/反序列化 |\n| `pathlib` | 跨平台路径操作 |\n| `datetime` | 时间戳处理 |\n| `re` | 命名空间名称规范化 |\n\n资料来源：[server.py:1-18]()\n\n### MCP SDK 依赖\n\n```python\n# requirements.txt\nmcp>=1.0.0\n```\n\n资料来源：[requirements.txt]()\n\n## 设计原则\n\n### 本地优先\n\n所有数据存储在用户本地机器上，不依赖云服务或外部 API。这确保了：\n\n- **零延迟**：本地文件 I/O 速度极快\n- **数据主权**：用户完全掌控自己的数据\n- **离线可用**：无需网络连接即可工作\n- **隐私保护**：数据不会离开用户的设备\n\n资料来源：[README.md:99-101]()\n\n### 简洁性\n\n采用类 Redis 的键值存储设计，而非复杂的向量数据库。这符合 AI 代理的实际需求——记住关键信息，而非大规模语义搜索。\n\n资料来源：[README.md:97-99]()\n\n## 故障处理\n\n### 错误响应格式\n\n所有错误以统一格式返回：\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"具体错误信息\",\n \"isError\": true\n}\n```\n\n错误响应支持 Markdown 和 JSON 两种格式，由调用方指定：\n\n```python\ndef _error(message: str, fmt: Optional[str] = None) -> str:\n result = {\"status\": \"error\", \"error\": message, \"isError\": True}\n return _format_response(result, fmt)\n```\n\n资料来源：[server.py:151-153]()\n\n### 异常捕获\n\n工具调用层统一捕获所有异常并返回结构化错误：\n\n```python\ntry:\n # ... 执行工具逻辑\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n资料来源：[server.py:360-368]()\n\n---\n\n\n\n## 使用场景与最佳实践\n\n### 相关页面\n\n相关主题：[核心功能详解](#page-4), [开发指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n \n\n# 使用场景与最佳实践\n\n本文档详细说明 Agent Memory MCP 的典型使用场景及对应的最佳实践指导，帮助开发者充分利用持久化内存系统的能力。\n\n## 核心使用场景概述\n\nAgent Memory MCP 设计用于解决 AI Agent 在会话间的上下文丢失问题。当 Agent 在不同会话间切换时，所有对话上下文都会重置为零。Agent Memory MCP 通过提供持久化、可搜索的内存存储，使 Agent 能够记住关键信息、用户偏好和中间计算结果。\n\n资料来源：[README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 场景一：跨会话用户偏好管理\n\n### 问题描述\n\n用户在首次对话中提供的偏好信息（如时区、货币、语言等）在会话结束时会被遗忘，导致 Agent 在后续会话中需要重复询问同样的问题，浪费 Token 成本。\n\n### 解决方案\n\n利用 `memory_remember` 存储用户偏好，利用 `memory_recall` 在后续会话中快速检索。\n\n### 实现示例\n\n```python\n# 会话 1：Agent 学习用户偏好\nawait memory_remember(\n key=\"user:timezone\",\n value=\"America/Chicago\",\n namespace=\"preferences\"\n)\nawait memory_remember(\n key=\"user:currency\",\n value=\"USD\",\n namespace=\"preferences\"\n)\n\n# 会话 2（数天后）：Agent 立即回忆偏好\ntz = await memory_recall(key=\"user:timezone\", namespace=\"preferences\")\n# → \"America/Chicago\"\n# 无需再次询问用户\n```\n\n资料来源：[README.md:1-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 时效性考虑\n\n对于用户偏好，建议使用较长的 TTL 或永久存储。关键代码逻辑如下：\n\n```python\n# 使用 30 天 TTL 存储用户偏好\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000 # 30 天\n)\n```\n\n资料来源：[server.py:200-250](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 场景二：研究积累代理\n\n### 问题描述\n\nAgent 在执行研究任务时，需要逐步积累发现的信息。传统方式下，这些信息无法跨会话保留，导致重复研究和上下文窗口浪费。\n\n### 解决方案\n\n创建独立的研究命名空间，系统化存储发现成果。\n\n### 实现示例\n\n```python\n# Agent 存储研究发现的竞品信息\nawait memory_remember(\n key=\"competitor:acme:api_pricing\",\n value=\"Acme API Pro: $49/mo for 10k calls. Enterprise: $199/mo. No free tier.\",\n namespace=\"research\",\n ttl_seconds=86400 * 7 # 保留 7 天\n)\n\n# Agent 存储另一个竞品的定价信息\nawait memory_remember(\n key=\"competitor:stripe:pricing\",\n value=\"Stripe charges 2.9% + $0.30 per transaction for US cards\",\n namespace=\"research\"\n)\n\n# 后续：搜索所有竞品相关内容\nfindings = await memory_search(\n query=\"competitor pricing\",\n namespace=\"research\"\n)\n```\n\n资料来源：[README.md:50-80](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 搜索机制说明\n\n`memory_search` 执行不区分大小写的子字符串匹配，同时搜索键名和值内容。返回结果按访问次数排序，高频访问的条目优先级更高。\n\n```python\n# 模糊搜索示例\nawait memory_search(\n query=\"stripe\",\n namespace=\"research\"\n)\n# 可匹配 key=\"competitor:stripe:pricing\" 或 value 包含 \"stripe\" 的条目\n```\n\n## 场景三：Agent 工作区（Scratchpad）\n\n### 问题描述\n\n复杂任务需要 Agent 在执行过程中记录中间状态、分步骤待办事项或调试信息。这些信息仅在当前任务周期内有用。\n\n### 解决方案\n\n使用专门的任务命名空间作为工作区，支持读写和清理。\n\n### 实现示例\n\n```python\n# Agent 使用内存作为工作区\nawait memory_remember(\n key=\"scratch:task:refactor-auth\",\n value=\"Step 1: Extract auth middleware. Step 2: Add token refresh. Step 3: Update tests.\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 检索当前任务状态\nstate = await memory_recall(\n key=\"scratch:task:refactor-auth\",\n namespace=\"agent:code-reviewer\"\n)\n\n# 定期清理已完成的任务数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n# → \"Cleared 156 entries from 'agent:code-reviewer'\"\n```\n\n资料来源：[README.md:80-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 命名空间设计建议\n\n| 命名空间模式 | 用途 | TTL 建议 |\n|------------|------|----------|\n| `preferences` | 用户偏好 | 长 TTL 或永久 |\n| `research` | 研究发现 | 中等 TTL |\n| `agent:{agent-id}` | Agent 工作区 | 任务周期 |\n| `session:{session-id}` | 会话临时数据 | 会话结束清理 |\n\n## 场景四：周期性数据清理\n\n### 问题描述\n\n长期运行的 Agent 会积累大量过期或无效的数据，影响存储效率和检索性能。\n\n### 解决方案\n\n利用 `memory_clear_namespace` 定期清理命名空间，或使用 TTL 自动过期。\n\n### 最佳实践\n\n```python\n# Agent 清理旧的研究数据\nawait memory_clear_namespace(namespace=\"agent:code-reviewer\")\n# → \"Cleared 156 entries from 'agent:code-reviewer'\"\n\n# 检查当前存储统计\nstats = await memory_stats()\n# 返回：总条目数、命名空间数、最旧/最新条目、过期条目数\n```\n\n资料来源：[README.md:95-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 工具注解与语义\n\nAgent Memory MCP 为每个工具提供语义注解，帮助 Agent 理解工具行为：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n### 注解含义\n\n- **readOnlyHint**: 工具是否仅读取数据\n- **destructiveHint**: 工具是否执行删除操作\n- **idempotentHint**: 工具重复执行是否产生相同结果\n- **openWorldHint**: 工具是否与外部世界交互\n\n资料来源：[server.py:100-150](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 存储架构与数据模型\n\n### 存储位置\n\n所有数据持久化存储在 `~/.agent-memory/` 目录：\n\n```\n~/.agent-memory/\n├── {namespace}.json # 每个命名空间一个文件\n└── _meta.json # 全局统计数据\n```\n\n资料来源：[README.md:120-140](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n### 条目数据结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n### 访问计数机制\n\n每次调用 `memory_recall` 都会更新 `accessed_at` 时间戳并递增 `access_count`，这使得：\n\n1. 搜索结果按相关性排序（高频访问条目优先）\n2. 可以分析记忆条目的使用频率\n3. 便于识别长期未使用的陈旧数据\n\n资料来源：[server.py:250-300](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 并发安全机制\n\nAgent Memory MCP 使用 POSIX 文件锁 `fcntl.flock()` 实现线程安全：\n\n```mermaid\ngraph TD\n A[Agent 进程 1] -->|写入| L[文件锁]\n B[Agent 进程 2] -->|等待| L\n C[Agent 进程 N] -->|等待| L\n L -->|解锁| A\n L -->|锁定| B\n B -->|解锁| B\n L -->|锁定| C\n```\n\n这允许多个 Agent 进程安全地并发读写内存存储。\n\n资料来源：[server.py:80-100](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 响应格式控制\n\n所有工具支持 `format` 参数指定返回格式：\n\n```python\n# 获取 Markdown 格式输出（人类可读）\nresult = await memory_stats(format=\"markdown\")\n\n# 获取 JSON 格式输出（程序化使用）\nresult = await memory_stats(format=\"json\")\n```\n\n### JSON 格式响应示例\n\n```json\n{\n \"status\": \"ok\",\n \"total_entries\": 847,\n \"active_entries\": 835,\n \"expired_entries\": 12,\n \"total_size\": \"2.4 MB\",\n \"namespaces\": 5,\n \"oldest_entry\": \"2026-04-15 (27 days ago)\",\n \"newest_entry\": \"just now\"\n}\n```\n\n资料来源：[server.py:300-350](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n\n## 定价层级与限制\n\n| 层级 | 价格 | 限制 |\n|------|-------|------|\n| **免费版** | $0 | 1,000 条目，5 个命名空间 |\n| **专业版** | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n资料来源：[README.md:150-160](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 设计原则\n\nAgent Memory MCP 遵循以下核心设计原则：\n\n1. **简洁优于复杂** — 类似 Redis 的键值存储，而非向量数据库。Agent 只需记住关键信息。\n2. **本地优先** — 数据保留在本地机器上。无云服务、无 API 密钥、无延迟。\n3. **自描述性** — 工具响应默认采用人类可读的 Markdown 格式，JSON 格式供程序调用。\n4. **容错性** — 延迟 TTL 过期、非严格搜索、优雅的错误处理。\n\n资料来源：[README.md:110-115](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n\n## 最佳实践总结\n\n### 命名空间策略\n\n- 按项目、用户或领域组织命名空间\n- 使用清晰、一致的命名约定（如 `agent:{name}`、`user:{id}`）\n- 定期清理不再需要的命名空间\n\n### TTL 设置指南\n\n| 数据类型 | TTL 建议 | 示例 |\n|---------|---------|------|\n| 用户偏好 | 永久或长 TTL | 30-90 天 |\n| 研究发现 | 中等 TTL | 7-30 天 |\n| 工作区数据 | 短 TTL 或清理 | 1-7 天 |\n| 会话数据 | 会话结束清理 | 无 TTL |\n\n### 键命名规范\n\n- 使用冒号分隔层级：`user:preferences:theme`\n- 保持键名简洁但具描述性\n- 避免在键名中包含敏感信息\n\n### 性能优化\n\n- 批量相似操作使用同一命名空间\n- 定期调用 `memory_stats` 监控存储使用\n- 及时清理过期数据以减少存储开销\n\n---\n\n\n\n## 开发指南\n\n### 相关页面\n\n相关主题：[部署指南与常见问题](#page-10), [安装与配置](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [smithery.yaml](https://github.com/Rumblingb/agent-memory-mcp/blob/main/smithery.yaml)\n \n\n# 开发指南\n\n本文档为 Agent Memory MCP 项目的完整开发指南，涵盖项目架构、工具实现、数据存储机制、测试方法以及部署配置。通过本指南，开发者可以深入理解系统设计理念，快速上手二次开发或集成工作。\n\n## 1. 项目概述\n\nAgent Memory MCP 是一个基于 Model Context Protocol (MCP) 的持久化键值存储服务器，专为 AI Agent 设计。该项目解决了 AI Agent 在会话之间丢失上下文的核心问题，提供持久化、可搜索、带 TTL（生存时间）的记忆存储能力。\n\n项目核心特性包括：\n\n- 7 个结构化工具支持完整的记忆管理\n- Namespace 命名空间隔离机制\n- TTL 自动过期与延迟清理\n- 模糊搜索（子串匹配）\n- 访问计数追踪\n- 基于 `fcntl.flock()` 的线程安全并发访问\n- 零外部依赖（仅依赖 `mcp` 包）\n- JSON 文件存储，数据保留在本地 `~/.agent-memory/`\n\n资料来源：[server.py:1-30]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph AI_Agent[\"AI Agent (Claude/GPT/Codex)\"]\n A[remember / recall / search / forget]\n end\n \n subgraph MCP_Protocol[\"MCP 协议层 (stdio JSON-RPC)\"]\n B[Tool Call 请求]\n C[JSON-RPC 响应]\n end\n \n subgraph Server[\"Agent Memory MCP Server\"]\n D[KV Store Engine]\n E[TTL Manager]\n F[Search Engine
substring match]\n end\n \n subgraph Storage[\"数据持久化层\"]\n G[\"~/.agent-memory/\"]\n H[\"{namespace}.json\"]\n I[\"_meta.json\"]\n end\n \n A -->|MCP Protocol| B\n B --> D\n D --> E\n E --> F\n D --> H\n D --> I\n F --> G\n C -->|响应结果| A\n```\n\n架构采用经典的三层设计：协议层处理 MCP 通信、业务层实现核心逻辑、存储层负责数据持久化。`fcntl.flock()` 文件锁确保多个 Agent 进程可以安全地并发读写。\n\n资料来源：[README.md:架构图]()\n\n### 2.2 核心组件说明\n\n| 组件 | 文件位置 | 职责 | 依赖 |\n|------|----------|------|------|\n| MCP Server | `server.py` | 注册工具、处理请求路由 | `mcp.server` |\n| KV Store Engine | `server.py` | 键值存储 CRUD 操作 | `json`, `pathlib` |\n| TTL Manager | `server.py` | 过期检查与延迟清理 | `datetime`, `time` |\n| Search Engine | `server.py` | 子串匹配搜索 | `re` (正则) |\n| File Locker | `server.py` | 并发访问控制 | `fcntl` |\n\n资料来源：[server.py:28-60]()\n\n## 3. 项目结构\n\n```\nagent-memory-mcp/\n├── server.py # 主服务器实现（核心业务逻辑）\n├── requirements.txt # 依赖声明\n├── README.md # 项目文档\n├── LICENSE # MIT 许可证\n└── smithery.yaml # Smithery.ai 部署配置\n```\n\n核心代码全部集中在 `server.py` 单文件中，采用模块化函数设计，便于维护和理解。\n\n资料来源：[requirements.txt]()\n\n## 4. 环境配置与安装\n\n### 4.1 系统要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 需要结构化并发支持 |\n| mcp | ≥1.0.0 | MCP Python SDK |\n| 操作系统 | POSIX 兼容 | 需要 `fcntl` 支持 |\n\n### 4.2 安装步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install mcp\n\n# 或使用 requirements.txt\npip install -r requirements.txt\n```\n\n资料来源：[README.md:安装章节]()\n\n### 4.3 存储目录\n\n首次运行时，系统自动创建存储目录：\n\n```python\nSTORAGE_DIR = Path.home() / \".agent-memory\"\n```\n\n数据存储结构如下：\n\n| 文件 | 内容 |\n|------|------|\n| `{namespace}.json` | 每个命名空间的记忆条目数组 |\n| `_meta.json` | 全局统计和索引信息 |\n\n资料来源：[server.py:54-56]()\n\n## 5. 工具实现详解\n\n### 5.1 工具注册机制\n\n所有工具通过 MCP Server 的装饰器模式注册：\n\n```python\n@server.list_tools()\nasync def list_tools() -> List[Tool]:\n return [Tool(...), Tool(...), ...]\n```\n\n路由分发通过 `call_tool` 装饰器实现：\n\n```python\n@server.call_tool()\nasync def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:\n if name == \"memory_remember\":\n text = memory_remember(**arguments, fmt=fmt)\n elif name == \"memory_recall\":\n text = memory_recall(**arguments, fmt=fmt)\n # ... 其他工具\n```\n\n资料来源：[server.py:320-345]()\n\n### 5.2 工具清单与参数\n\n#### 5.2.1 memory_remember\n\n存储键值对到指定命名空间。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 唯一键标识符 |\n| `value` | string | ✅ | - | 要存储的值 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n| `ttl_seconds` | integer | ❌ | - | TTL 秒数 |\n\n**Tool Annotations:**\n```python\nToolAnnotations(\n readOnlyHint=False,\n destructiveHint=False,\n idempotentHint=False,\n openWorldHint=False\n)\n```\n\n资料来源：[server.py:工具定义区域]()\n\n#### 5.2.2 memory_recall\n\n根据键检索值及其元数据。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要检索的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n\n**返回值结构：**\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n资料来源：[server.py:170-200]()\n\n#### 5.2.3 memory_forget\n\n删除指定的键值对。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `key` | string | ✅ | - | 要删除的键 |\n| `namespace` | string | ❌ | `\"default\"` | 命名空间 |\n\n#### 5.2.4 memory_search\n\n跨命名空间模糊搜索。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | ✅ | - | 搜索关键词或子串 |\n| `namespace` | string | ❌ | - | 限定命名空间（空则搜索全部） |\n| `limit` | integer | ❌ | 10 | 最大返回结果数 |\n\n搜索特性：\n- 大小写不敏感\n- 同时匹配 key 和 value\n- 按访问次数排序\n\n#### 5.2.5 memory_list_namespaces\n\n列出所有命名空间及其条目计数。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 输出格式：`markdown` 或 `json` |\n\n#### 5.2.6 memory_clear_namespace\n\n清空指定命名空间的所有条目。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `namespace` | string | ✅ | - | 要清空的命名空间 |\n\n#### 5.2.7 memory_stats\n\n获取全局存储统计信息。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `format` | string | ❌ | `\"markdown\"` | 输出格式：`markdown` 或 `json` |\n\n资料来源：[server.py:工具定义区域]()\n\n### 5.3 工具注解系统\n\nMCP 协议支持工具注解，用于客户端优化行为：\n\n| 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |\n|------|-------------|-----------------|----------------|---------------|\n| `memory_remember` | false | false | false | false |\n| `memory_recall` | true | false | true | false |\n| `memory_forget` | false | true | true | false |\n| `memory_search` | true | false | true | false |\n| `memory_list_namespaces` | true | false | true | false |\n| `memory_clear_namespace` | false | true | false | false |\n| `memory_stats` | true | false | true | false |\n\n资料来源：[README.md:Tool Annotations]()\n\n## 6. 数据模型\n\n### 6.1 记忆条目结构\n\n```json\n{\n \"key\": \"user:theme\",\n \"value\": \"dark\",\n \"created_at\": \"2026-05-12T10:30:00Z\",\n \"accessed_at\": \"2026-05-12T14:22:00Z\",\n \"expires_at\": \"2026-06-11T10:30:00Z\",\n \"access_count\": 47\n}\n```\n\n字段说明：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `key` | string | 全局唯一标识符 |\n| `value` | string | 存储的实际内容 |\n| `created_at` | ISO8601 string | 创建时间 |\n| `accessed_at` | ISO8601 string | 最后访问时间 |\n| `expires_at` | ISO8601 string 或 null | TTL 过期时间（可选） |\n| `access_count` | integer | 访问计数器 |\n\n资料来源：[server.py:记忆条目结构]()\n\n### 6.2 元数据文件结构\n\n```json\n{\n \"total_entries\": 142,\n \"namespace_count\": 5\n}\n```\n\n资料来源：[server.py:元数据写入]()\n\n## 7. 存储实现细节\n\n### 7.1 文件锁定机制\n\n```python\n@contextmanager\ndef _locked(namespace: str):\n lock_path = _namespace_path(namespace).with_suffix(\".lock\")\n with lock_path.open(\"w\") as lock_file:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)\n try:\n yield\n finally:\n fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)\n```\n\n使用 POSIX 文件锁 `fcntl.flock()` 实现排他锁，确保多进程并发安全。\n\n资料来源：[server.py:文件锁定实现]()\n\n### 7.2 命名空间安全处理\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n使用正则表达式过滤非法字符，防止路径穿越攻击。\n\n资料来源：[server.py:命名空间路径安全处理]()\n\n### 7.3 TTL 过期检查\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n if \"expires_at\" not in entry or entry[\"expires_at\"] is None:\n return False\n expires = datetime.fromisoformat(entry[\"expires_at\"])\n return datetime.now(timezone.utc) > expires\n```\n\n采用延迟清理策略，仅在访问时检查过期，避免后台清理线程开销。\n\n资料来源：[server.py:TTL检查逻辑]()\n\n## 8. 测试与调试\n\n### 8.1 本地测试\n\n```bash\n# 使用 MCP Inspector 测试\nnpx @modelcontextprotocol/inspector python3 server.py\n\n# 运行单元测试\npython3 -m pytest tests/\n```\n\n资料来源：[README.md:开发章节]()\n\n### 8.2 MCP Client 配置\n\n**通用配置 (config.yaml):**\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n**Claude Desktop:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n**VS Code / Cursor:**\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:MCP Client配置]()\n\n## 9. 部署配置\n\n### 9.1 Smithery.ai 部署\n\n项目提供 Smithery.ai 平台的一键部署配置：\n\n```yaml\nname: agent-memory-mcp\nversion: 1.0.0\ndescription: Persistent key-value memory for AI agents with TTL, namespaces, and search.\n\nruntime:\n type: python\n entrypoint: server.py\n requirements: requirements.txt\n\ncapabilities:\n tools:\n - memory_remember\n - memory_recall\n - memory_forget\n - memory_search\n - memory_list_namespaces\n - memory_clear_namespace\n - memory_stats\n\npricing:\n free:\n max_entries: 1000\n pro:\n price: 19.00\n currency: USD\n interval: month\n max_entries: unlimited\n stripe_link: https://buy.stripe.com/PLACEHOLDER\n\nmetadata:\n author: Nous Research\n license: MIT\n repository: https://github.com/nousresearch/agent-memory-mcp\n tags:\n - memory\n - storage\n - agents\n - persistence\n - kv-store\n```\n\n资料来源：[smithery.yaml]()\n\n## 10. 响应格式化\n\n### 10.1 格式化策略\n\n系统支持两种响应格式，通过 `format` 参数控制：\n\n| 格式 | 适用场景 | 示例 |\n|------|----------|------|\n| `markdown` | 人类可读 | `## ✅ Success\\n**key:** value` |\n| `json` | 程序化处理 | `{\"status\": \"ok\", \"key\": \"value\"}` |\n\n### 10.2 错误处理\n\n所有工具都包装在统一的异常处理中：\n\n```python\ntry:\n # 工具执行\nexcept Exception as exc:\n err_text = _error(f\"Internal error in {name}: {exc}\", fmt)\n return CallToolResult(\n content=[TextContent(type=\"text\", text=err_text)],\n isError=True,\n )\n```\n\n输出长度限制在 25,000 字符以内，防止大响应导致的问题。\n\n资料来源：[server.py:异常处理和输出限制]()\n\n## 11. 设计原则\n\n项目遵循以下核心设计原则：\n\n1. **简洁优于复杂** — 类似 Redis 的 KV 存储，而非向量数据库。Agent 只需要记住事情。\n2. **本地优先** — 数据保存在本地机器上。无云服务、无 API 密钥、无延迟。\n3. **自描述** — 工具响应默认是人类可读的 markdown，JSON 用于程序化调用。\n4. **容错性** — 延迟 TTL 过期、非严格搜索、优雅的错误处理。\n\n资料来源：[README.md:设计原则]()\n\n## 12. 扩展开发指南\n\n### 12.1 添加新工具\n\n在 `server.py` 中添加新工具需要完成以下步骤：\n\n1. 在 `list_tools()` 中定义 `Tool` 对象\n2. 在 `call_tool()` 中添加路由分支\n3. 实现对应的处理函数\n4. 添加单元测试\n\n```python\n# 1. 定义工具\nTool(\n name=\"memory_new_tool\",\n description=\"新工具描述\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {...},\n \"required\": [...]\n },\n annotations=ToolAnnotations(\n readOnlyHint=True,\n destructiveHint=False,\n idempotentHint=True,\n openWorldHint=False,\n ),\n)\n\n# 2. 路由分发\nelif name == \"memory_new_tool\":\n text = memory_new_tool(**arguments, fmt=fmt)\n\n# 3. 实现函数\ndef memory_new_tool(key: str, fmt: str = \"markdown\") -> str:\n # 业务逻辑\n return _success({\"result\": \"...\"}, fmt)\n```\n\n### 12.2 修改存储后端\n\n当前实现使用 JSON 文件存储。如需切换到其他后端（如 SQLite），需要重写以下函数：\n\n- `_read_namespace()`\n- `_write_namespace()`\n- `_locked()`\n- `_recalc_meta()`\n\n保持接口签名不变，上层业务逻辑无需修改。\n\n## 13. 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 官方仓库 | https://github.com/nousresearch/agent-memory-mcp |\n| Nous Research | https://nousresearch.com |\n| 相关项目 - Agent Cost Tracker MCP | https://github.com/Rumblingb/agent-cost-tracker-mcp |\n| 相关项目 - Search Proxy MCP | https://github.com/Rumblingb/search-proxy-mcp |\n| 相关项目 - AgentPassport API | https://github.com/Rumblingb/agentpassport-api |\n\n---\n\n\n\n## 部署指南与常见问题\n\n### 相关页面\n\n相关主题：[安装与配置](#page-2), [开发指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [server.py](https://github.com/Rumblingb/agent-memory-mcp/blob/main/server.py)\n- [README.md](https://github.com/Rumblingb/agent-memory-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/Rumblingb/agent-memory-mcp/blob/main/requirements.txt)\n- [index.html](https://github.com/Rumblingb/agent-memory-mcp/blob/main/index.html)\n \n\n# 部署指南与常见问题\n\n## 概述\n\n本页面提供 Agent Memory MCP 的完整部署指南与常见问题解答。该项目是一个基于 Model Context Protocol (MCP) 的持久化键值存储系统，专为 AI 代理设计，支持命名空间隔离、TTL 过期机制、模糊搜索和访问计数追踪。资料来源：[server.py:1-30]()\n\n## 系统要求\n\n| 要求项 | 规格 |\n|--------|------|\n| Python 版本 | 3.10+ |\n| 操作系统 | macOS、Linux、Windows |\n| 依赖包 | mcp >= 1.0.0 |\n| 网络 | 仅本地通信，无需外网 |\n\n资料来源：[requirements.txt:1]()\n\n## 部署方式\n\n### 方式一：pip 安装（推荐）\n\n通过 Python 包管理器直接安装：\n\n```bash\npip install agent-memory-mcp\n```\n\n安装完成后可直接使用 `python3 -m agent_memory_mcp` 启动服务。资料来源：[index.html]()\n\n### 方式二：源码安装\n\n适用于需要自定义修改或参与开发的情况：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Rumblingb/agent-memory-mcp.git\ncd agent-memory-mcp\n\n# 安装依赖\npip install mcp\n\n# 或使用 requirements.txt\npip install -r requirements.txt\n\n# 启动服务\npython3 server.py\n```\n\n资料来源：[README.md:89-99]()\n\n### 方式三：MCP Inspector 测试\n\n在开发阶段，可使用 MCP Inspector 进行调试：\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md:101-102]()\n\n## MCP 客户端配置\n\n### Claude Desktop\n\n在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/agent-memory-mcp/server.py\"]\n }\n }\n}\n```\n\n资料来源：[README.md:117-123]()\n\n### VS Code / Cursor\n\n在 `.cursor/mcp.json` 或 VS Code 的 MCP 设置中添加：\n\n```json\n{\n \"mcpServers\": {\n \"agent-memory\": {\n \"command\": \"python3\",\n \"args\": [\"server.py\"],\n \"cwd\": \"/path/to/agent-memory-mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:125-132]()\n\n### 通用 YAML 配置\n\n```yaml\nmcpServers:\n agent-memory:\n command: python3\n args:\n - /path/to/agent-memory-mcp/server.py\n description: Persistent key-value memory for AI agents\n```\n\n## 存储架构\n\n### 数据存储位置\n\n所有数据存储在用户主目录下的隐藏目录 `~/.agent-memory/` 中：\n\n| 文件 | 用途 |\n|------|------|\n| `{namespace}.json` | 各命名空间的记忆条目数组 |\n| `_meta.json` | 全局统计和索引信息 |\n\n资料来源：[server.py:47-49]()\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[agent-memory Server]\n B --> C{操作类型}\n C -->|remember| D[写入 JSON 文件]\n C -->|recall| E[读取并更新访问计数]\n C -->|search| F[模糊匹配搜索]\n C -->|forget| G[删除条目]\n D --> H[~/.agent-memory/]\n E --> H\n F --> H\n G --> H\n```\n\n### 命名空间隔离机制\n\n每个命名空间对应独立的 JSON 文件，通过命名空间路径函数进行隔离：\n\n```python\ndef _namespace_path(namespace: str) -> Path:\n # Sanitize the namespace so it can't escape the directory.\n safe = re.sub(r\"[^a-zA-Z0-9_.\\-]\", \"_\", namespace)\n if not safe:\n safe = DEFAULT_NAMESPACE\n return STORAGE_DIR / f\"{safe}.json\"\n```\n\n关键安全措施：命名空间名只能包含 `a-zA-Z0-9_.-` 字符，其他字符会被替换为下划线，防止目录遍历攻击。资料来源：[server.py:58-65]()\n\n## 工具函数使用指南\n\n### 1. memory_remember — 存储记忆\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 记忆的唯一标识键 |\n| `value` | string | ✅ | 要存储的值 |\n| `namespace` | string | ❌ | 命名空间，默认 `\"default\"` |\n| `ttl_seconds` | integer | ❌ | 自动过期秒数 |\n\n**示例：**\n\n```python\n# 带 TTL 的用户偏好存储（30天过期）\nawait memory_remember(\n key=\"user:theme\",\n value=\"dark\",\n namespace=\"preferences\",\n ttl_seconds=2592000\n)\n\n# 永久存储研究数据\nawait memory_remember(\n key=\"competitor:pricing:stripe\",\n value=\"Stripe charges 2.9% + $0.30 per transaction\",\n namespace=\"research\"\n)\n```\n\n资料来源：[README.md:135-145]()\n\n### 2. memory_recall — 检索记忆\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `key` | string | ✅ | 要检索的键名 |\n| `namespace` | string | ❌ | 命名空间，默认 `\"default\"` |\n\n**返回元数据：**\n\n| 字段 | 说明 |\n|------|------|\n| `value` | 存储的值 |\n| `created_at` | 创建时间戳 |\n| `accessed_at` | 最后访问时间 |\n| `expires_at` | TTL 过期时间（如有设置） |\n| `access_count` | 访问次数统计 |\n\n资料来源：[README.md:147-156]()\n\n### 3. memory_forget — 删除记忆\n\n```python\nawait memory_forget(\n key=\"user:old_preference\",\n namespace=\"preferences\"\n)\n```\n\n### 4. memory_search — 模糊搜索\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `query` | string | ✅ | 搜索关键词或子字符串 |\n| `namespace` | string | ❌ | 限定命名空间搜索 |\n| `limit` | integer | ❌ | 最大返回数量，默认 10 |\n| `format` | string | ❌ | 输出格式：`markdown` 或 `json` |\n\n```python\n# 跨所有命名空间搜索\nresults = await memory_search(query=\"competitor pricing\")\n\n# 限定命名空间搜索\nresults = await memory_search(\n query=\"api\",\n namespace=\"research\",\n limit=20\n)\n```\n\n搜索特性：大小写不敏感，同时匹配键名和值内容，结果按访问次数排序。资料来源：[server.py:275-295]()\n\n### 5. memory_list_namespaces — 列出命名空间\n\n```python\n# 返回所有命名空间及其活跃/过期条目计数\nnamespaces = await memory_list_namespaces()\n```\n\n### 6. memory_clear_namespace — 清除命名空间\n\n```python\n# 永久删除指定命名空间的所有条目\nawait memory_clear_namespace(namespace=\"research:old\")\n# → \"Cleared 156 entries from 'research:old'\"\n```\n\n**注意：** 此操作不可撤销。资料来源：[README.md:177-179]()\n\n### 7. memory_stats — 全局统计\n\n```python\n# 获取存储统计信息\nstats = await memory_stats(format=\"markdown\")\n```\n\n**返回字段：**\n\n| 字段 | 说明 |\n|------|------|\n| `total_entries` | 活跃条目总数 |\n| `total_size_bytes` | 存储文件总大小（字节） |\n| `total_size_human` | 人类可读大小 |\n| `namespace_count` | 命名空间数量 |\n| `oldest_entry` | 最早条目时间 |\n| `newest_entry` | 最新条目时间 |\n| `free_tier_limit` | 免费配额限制（1000条） |\n\n资料来源：[server.py:345-370]()\n\n## 常见问题排查\n\n### 问题一：导入错误 \"ModuleNotFoundError: No module named 'mcp'\"\n\n**原因：** 未安装 MCP 依赖包。\n\n**解决方案：**\n\n```bash\npip install mcp\n```\n\n或者使用项目提供的 requirements.txt：\n\n```bash\npip install -r requirements.txt\n```\n\n资料来源：[requirements.txt:1]()\n\n### 问题二：存储目录权限错误\n\n**症状：** `PermissionError: [Errno 13] Permission denied`\n\n**原因：** 无法在 `~/.agent-memory/` 创建文件。\n\n**解决方案：**\n\n```bash\n# 检查并修复目录权限\nls -la ~ | grep agent-memory\nchmod 755 ~/.agent-memory\n```\n\n存储目录由以下代码自动创建：\n\n```python\ndef _ensure_storage() -> None:\n \"\"\"Create the storage directory if it doesn't exist.\"\"\"\n STORAGE_DIR.mkdir(parents=True, exist_ok=True)\n```\n\n资料来源：[server.py:52-54]()\n\n### 问题三：并发访问数据不一致\n\n**症状：** 写入的数据在读取时丢失或损坏。\n\n**原因：** 未使用正确的并发控制机制。\n\n**解决方案：** Agent Memory MCP 使用 `fcntl.flock()` 实现文件级锁，确保多进程安全访问。确保所有访问都通过 MCP 服务器进行，而非直接操作 JSON 文件。资料来源：[README.md:203-205]()\n\n### 问题四：TTL 过期条目未自动清理\n\n**症状：** 过期条目仍然出现在搜索结果中。\n\n**原因：** 系统采用懒清理策略，仅在访问时检查过期状态。\n\n**解决方案：** 这是设计决策，不影响功能。过期条目会在下次 `recall` 或 `search` 时被自动过滤。如需主动清理，可调用 `memory_list_namespaces` 查看各命名空间状态。\n\n过期检测逻辑：\n\n```python\ndef _is_expired(entry: Dict[str, Any]) -> bool:\n \"\"\"Check if an entry has expired based on its TTL.\"\"\"\n expires_at = entry.get(\"expires_at\")\n if not expires_at:\n return False\n expires_time = datetime.fromisoformat(expires_at)\n return datetime.now(timezone.utc) > expires_time\n```\n\n资料来源：[server.py:120-127]()\n\n### 问题五：中文或特殊字符无法正确存储\n\n**症状：** 存储的中文字符在检索时变成乱码。\n\n**原因：** 字符编码问题。\n\n**解决方案：** 确保 JSON 文件使用 UTF-8 编码。Python 的 `json` 模块默认使用 UTF-8，无需额外配置。如在终端显示乱码，请确保终端编码设置为 UTF-8。\n\n### 问题六：数据文件过大\n\n**症状：** `~/.agent-memory/` 目录占用过多磁盘空间。\n\n**解决方案：**\n\n1. 定期清理过期或无用命名空间：\n\n```python\n# 清理特定命名空间\nawait memory_clear_namespace(namespace=\"temp:sessions\")\n\n# 查看统计信息\nstats = await memory_stats()\n```\n\n2. 手动删除不使用的 JSON 文件：\n\n```bash\nrm ~/.agent-memory/old_namespace.json\n```\n\n资料来源：[server.py:380-385]()\n\n## 线程安全机制\n\nAgent Memory MCP 通过 POSIX 文件锁 `fcntl.flock()` 实现并发安全：\n\n```mermaid\ngraph LR\n A[进程 A] -->|LOCK_EX| C[文件锁]\n B[进程 B] -->|等待| C\n C -->|解锁| D[完成读写]\n D -->|UNLOCK| E[锁释放]\n B -->|获锁| D\n```\n\n所有文件操作都在锁保护区域内执行，确保同一时间只有一个进程可以写入。资料来源：[README.md:203-205]()\n\n## 响应格式\n\n工具支持两种输出格式，通过 `format` 参数指定：\n\n| 格式 | 用途 | 示例 |\n|------|------|------|\n| `markdown` | 人类可读，默认 | `## ✅ Success\\n**key:** value` |\n| `json` | 程序化处理 | `{\"status\": \"ok\", \"key\": \"value\"}` |\n\n```python\n# 获取 JSON 格式结果\nresult = await memory_recall(\n key=\"user:theme\",\n namespace=\"preferences\",\n format=\"json\"\n)\n```\n\n资料来源：[server.py:310-335]()\n\n## 开发测试\n\n运行项目测试套件：\n\n```bash\npython3 -m pytest tests/\n```\n\n使用 MCP Inspector 进行交互式测试：\n\n```bash\nnpx @modelcontextprotocol/inspector python3 server.py\n```\n\n资料来源：[README.md:101-104]()\n\n## 定价与限制\n\n| 套餐 | 价格 | 限制 |\n|------|------|------|\n| 免费版 | $0 | 1,000 条目，5 个命名空间 |\n| Pro 版 | $19/月 | 无限条目，无限命名空间，优先支持 |\n\n注意：免费版限制为功能性提示，非技术强制限制。数据始终存储在本地，不会因达到限制而丢失。资料来源：[index.html]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph AI层\n A[Claude/GPT/Codex] \n end\n \n subgraph MCP协议层\n B[MCP Protocol
stdio JSON-RPC]\n end\n \n subgraph 服务层\n C[Agent Memory
MCP Server]\n D[KV 存储引擎]\n E[TTL 管理器]\n F[搜索引擎
子字符串匹配]\n end\n \n subgraph 存储层\n G[~/.agent-memory/]\n H[namespace.json]\n I[_meta.json]\n end\n \n A -->|remember/recall/search| B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n E --> G\n F --> G\n G --> H\n G --> I\n```\n\n资料来源：[README.md:195-215]()\n\n## 参考链接\n\n- 项目仓库：https://github.com/Rumblingb/agent-memory-mcp\n- Nous Research：https://nousresearch.com\n- 相关项目：\n - [Agent Cost Tracker MCP](https://github.com/Rumblingb/agent-cost-tracker-mcp)\n - [Search Proxy MCP](https://github.com/Rumblingb/search-proxy-mcp)\n - [AgentPassport API](https://github.com/Rumblingb/agentpassport-api)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Rumblingb/agent-memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agent-memory-mcp` 与安装入口 `mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | repo=agent-memory-mcp; install=mcp\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：Rumblingb/agent-memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agent-memory-mcp` 与安装入口 `mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | repo=agent-memory-mcp; install=mcp\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1236240815 | https://github.com/Rumblingb/agent-memory-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# agent-memory-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-memory-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCP server providing persistent key-value memory for AI agents with TTL and search 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：核心功能详解。围绕“核心功能详解”模拟一次用户任务，不展示安装或运行结果。\n5. page-7：数据存储机制。围绕“数据存储机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“核心功能详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-7\n输入：用户提供的“数据存储机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“核心功能详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-7：Step 5 必须围绕“数据存储机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Rumblingb/agent-memory-mcp\n- https://github.com/Rumblingb/agent-memory-mcp#readme\n- README.md\n- server.py\n- requirements.txt\n- pyproject.toml\n- smithery.yaml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-memory-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：Rumblingb/agent-memory-mcp\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install mcp\n```\n\n来源：https://github.com/Rumblingb/agent-memory-mcp#readme\n\n## 来源\n\n- repo: https://github.com/Rumblingb/agent-memory-mcp\n- docs: https://github.com/Rumblingb/agent-memory-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_040c2cda697b48e08165081bce8e4198"
}