{ "canonical_name": "rohitg00/agentmemory", "compilation_id": "pack_25958517a19b40c89fa55d0c77b65a09", "created_at": "2026-05-16T22:38:03.293945+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, 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 `npm install -g @agentmemory/agentmemory` 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": "npm install -g @agentmemory/agentmemory", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_7d3dd7a8ca0947caa0ef8559abdb7cac" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_868b6ab6dbb6631fc3dfa438bc75cd0e", "canonical_name": "rohitg00/agentmemory", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/rohitg00/agentmemory", "slug": "agentmemory", "source_packet_id": "phit_772c16aed76d439dbaabbcd2aa555b03", "source_validation_id": "dval_8373d32d3bb24530a7e290750da6284c" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": 858, "github_stars": 10274, "one_liner_en": "#1 Persistent memory for AI coding agents based on real-world benchmarks", "one_liner_zh": "#1 Persistent memory for AI coding agents based on real-world benchmarks", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:coding, git" }, "target_user": "使用 claude, cursor 等宿主 AI 的用户", "title_en": "agentmemory", "title_zh": "agentmemory 能力包", "visible_tags": [ { "label_en": "Security & Permissions", "label_zh": "安全审查与权限治理", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-security-permissions", "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": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_772c16aed76d439dbaabbcd2aa555b03", "page_model": { "artifacts": { "artifact_slug": "agentmemory", "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": "npm install -g @agentmemory/agentmemory", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/rohitg00/agentmemory#readme", "verified": true } ], "display_tags": [ "安全审查与权限治理", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "#1 Persistent memory for AI coding agents based on real-world benchmarks" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude, cursor", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Viewer tab bar is vertically clipped in the web UI", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：npm installs anthropic dependencies", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.14 — CLI installer first + agentmemory stop", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.15 — DevEx overhaul", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.8 — local fallback tools/list returns 7 not 4", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | 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:1166408297 | https://github.com/rohitg00/agentmemory | 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:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_c1b3cc10454e4fd09921e3748ad82305 | https://github.com/rohitg00/agentmemory/issues/433 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Ollama as a native LLM provider", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_c87cfb919d5049289e2beec7660ffcf0 | https://github.com/rohitg00/agentmemory/issues/232 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Support Ollama as a native LLM provider", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_1bade4c29c91471284081588c913e17d | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.10 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_690933973fcf4eb5b034ab92a3c00d23 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.11 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button", "user_impact": "可能阻塞安装或首次运行。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Viewer tab bar is vertically clipped in the web UI。", "title": "踩坑日志" }, "snapshot": { "contributors": 17, "forks": 858, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 10274 }, "source_url": "https://github.com/rohitg00/agentmemory", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "#1 Persistent memory for AI coding agents based on real-world benchmarks", "title": "agentmemory 能力包", "trial_prompt": "# agentmemory - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agentmemory 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. data-flow：数据流与处理。围绕“数据流与处理”模拟一次用户任务，不展示安装或运行结果。\n5. memory-operations：记忆操作。围绕“记忆操作”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. data-flow\n输入：用户提供的“数据流与处理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. memory-operations\n输入：用户提供的“记忆操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / data-flow：Step 4 必须围绕“数据流与处理”形成一个小中间产物，并等待用户确认。\n- Step 5 / memory-operations：Step 5 必须围绕“记忆操作”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rohitg00/agentmemory\n- https://github.com/rohitg00/agentmemory#readme\n- plugin/skills/forget/SKILL.md\n- plugin/skills/recall/SKILL.md\n- plugin/skills/remember/SKILL.md\n- plugin/skills/session-history/SKILL.md\n- README.md\n- DESIGN.md\n- package.json\n- src/cli.ts\n- examples/python/quickstart.py\n- examples/python/observe_and_recall.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agentmemory 的核心服务。\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": "来源平台：github。github/github_issue: Fly deployment proxy doesn't work（https://github.com/rohitg00/agentmemory/issues/434）；github/github_issue: Expose agent_id / session_id in /agentmemory/audit so external rate-limi（https://github.com/rohitg00/agentmemory/issues/433）；github/github_issue: Support Ollama as a native LLM provider（https://github.com/rohitg00/agentmemory/issues/232）；github/github_issue: npm installs anthropic dependencies（https://github.com/rohitg00/agentmemory/issues/430）；github/github_issue: Viewer tab bar is vertically clipped in the web UI（https://github.com/rohitg00/agentmemory/issues/421）；github/github_issue: Viewer tab bar collapses/clips on Windows/Chromium layout（https://github.com/rohitg00/agentmemory/issues/422）；github/github_release: v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17）；github/github_release: v0.9.16 — DevEx polish + agent-memory.dev refresh（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16）；github/github_release: v0.9.15 — DevEx overhaul（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15）；github/github_release: v0.9.14 — CLI installer first + agentmemory stop（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14）；github/github_release: v0.9.13（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13）；github/github_release: v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintex（https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Fly deployment proxy doesn't work", "url": "https://github.com/rohitg00/agentmemory/issues/434" }, { "kind": "github_issue", "source": "github", "title": "Expose agent_id / session_id in /agentmemory/audit so external rate-limi", "url": "https://github.com/rohitg00/agentmemory/issues/433" }, { "kind": "github_issue", "source": "github", "title": "Support Ollama as a native LLM provider", "url": "https://github.com/rohitg00/agentmemory/issues/232" }, { "kind": "github_issue", "source": "github", "title": "npm installs anthropic dependencies", "url": "https://github.com/rohitg00/agentmemory/issues/430" }, { "kind": "github_issue", "source": "github", "title": "Viewer tab bar is vertically clipped in the web UI", "url": "https://github.com/rohitg00/agentmemory/issues/421" }, { "kind": "github_issue", "source": "github", "title": "Viewer tab bar collapses/clips on Windows/Chromium layout", "url": "https://github.com/rohitg00/agentmemory/issues/422" }, { "kind": "github_release", "source": "github", "title": "v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17" }, { "kind": "github_release", "source": "github", "title": "v0.9.16 — DevEx polish + agent-memory.dev refresh", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16" }, { "kind": "github_release", "source": "github", "title": "v0.9.15 — DevEx overhaul", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15" }, { "kind": "github_release", "source": "github", "title": "v0.9.14 — CLI installer first + agentmemory stop", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14" }, { "kind": "github_release", "source": "github", "title": "v0.9.13", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13" }, { "kind": "github_release", "source": "github", "title": "v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintex", "url": "https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "#1 Persistent memory for AI coding agents based on real-world benchmarks", "effort": "安装已验证", "forks": 858, "icon": "code", "name": "agentmemory 能力包", "risk": "可发布", "slug": "agentmemory", "stars": 10274, "tags": [ "安全审查与权限治理", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/rohitg00/agentmemory 项目说明书\n\n生成时间：2026-05-16 22:32:59 UTC\n\n## 目录\n\n- [项目介绍](#intro)\n- [快速开始](#quickstart)\n- [系统架构](#architecture)\n- [数据流与处理](#data-flow)\n- [记忆操作](#memory-operations)\n- [搜索与检索](#search-retrieval)\n- [记忆压缩与合并](#consolidation)\n- [MCP服务器与工具](#mcp-server)\n- [代理插件与集成](#agent-plugins)\n- [部署与运维](#deployment)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quickstart), [系统架构](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)\n- [website/components/Features.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Features.tsx)\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 项目介绍\n\n## 概述\n\nAgentMemory 是一个完整的**内存运行时系统**（Complete Memory Runtime），专为 AI 编码代理设计。与传统的向量存储库或简单记忆库不同，AgentMemory 提供从**捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）到联邦（Federate）**的完整记忆生命周期管理能力。资料来源：[website/components/Features.tsx]()\n\n该项目的核心目标是让 AI 代理具备跨会话的持久记忆能力，使代理能够：\n\n- 记住文件修改的具体细节\n- 追踪决策历史和变更理由\n- 维护任务状态和阻塞关系\n- 快速恢复工作上下文\n\nAgentMemory 实现了 **95.2% 的检索召回率（R@5）**，同时减少 **92% 的 token 使用量**，且**不依赖外部数据库**。资料来源：[website/app/opengraph-image.tsx]()\n\n## 核心架构\n\nAgentMemory 采用客户端-服务器架构，运行在本地机器上，数据完全本地存储。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude Code] -->|MCP| M[AgentMemory Server]\n B[Codex CLI] -->|MCP| M\n C[OpenClaw] -->|MCP| M\n D[Hermes] -->|MCP| M\n E[PI] -->|MCP| M\n F[OpenHuman] -->|MCP| M\n G[其他 MCP 客户端] -->|MCP| M\n end\n \n subgraph 服务端\n M -->|存储| DB[(本地存储)]\n M -->|API| H[HTTP API :3111]\n end\n \n subgraph 功能模块\n M --> OBS[观察记录模块]\n M --> SEM[语义记忆模块]\n M --> ACT[行动追踪模块]\n M --> CRY[晶体化模块]\n M --> PRIV[隐私过滤模块]\n end\n```\n\n## 主要功能模块\n\n### 1. 观察记录（Observations）\n\n观察记录是 AgentMemory 的基础数据单元，用于捕获代理的每一次关键操作。资料来源：[src/prompts/compression.ts]()\n\n观察记录支持多种类型：\n\n| 类型 | 说明 | 重要性等级 |\n|------|------|-----------|\n| `file_read` | 文件读取操作 | 1-3 |\n| `file_write` | 文件写入操作 | 4-6 |\n| `file_edit` | 文件编辑操作 | 4-6 |\n| `command_run` | 命令执行操作 | 4-6 |\n| `search` | 搜索操作 | 1-3 |\n| `web_fetch` | 网页抓取 | 1-3 |\n| `conversation` | 对话内容 | 1-3 |\n| `error` | 错误信息 | 4-6 |\n| `decision` | 决策记录 | 7-9 |\n| `discovery` | 发现/洞察 | 7-9 |\n| `subagent` | 子代理调用 | 4-6 |\n| `notification` | 通知事件 | 1-3 |\n| `task` | 任务状态 | 4-6 |\n| `other` | 其他类型 | 1-3 |\n\n每条观察记录包含以下结构化字段：\n\n```xml\n\n 操作类型\n 简短描述标题（最多80字符）\n 一行上下文（可选）\n \n 具体事实1\n 具体事实2\n \n 2-3句总结\n \n 技术概念或模式\n \n \n 文件路径\n \n 1-10重要性评分\n\n```\n\n### 2. 语义记忆（Semantic Memory）\n\n语义记忆是将观察记录中的具体事实进行整合后形成的抽象知识表示。资料来源：[src/viewer/index.html]()\n\n语义记忆具有以下特性：\n\n- **置信度（Confidence）**：表示该记忆被确认的程度\n- **强度（Strength）**：表示该记忆在记忆网络中的权重\n- **自动提取**：从长时间会话中自动归纳\n\n```mermaid\ngraph LR\n O1[文件读取观察] --> SEM[语义记忆网络]\n O2[文件编辑观察] --> SEM\n O3[决策观察] --> SEM\n SEM --> CON1[概念节点]\n SEM --> CON2[概念节点]\n SEM --> CON3[概念节点]\n```\n\n### 3. 行动追踪（Actions）\n\n行动是代理在会话期间产生的后续跟进项，用于确保重要事项不会被遗漏。资料来源：[src/viewer/index.html]()\n\n行动具有完整的状态生命周期：\n\n```mermaid\ngraph LR\n A[pending 待处理] --> B[active 活动中]\n B --> C[done 已完成]\n B --> D[blocked 已阻塞]\n```\n\n行动可以通过以下三种方式创建：\n\n| 方式 | 命令/方法 | 示例 |\n|------|-----------|------|\n| MCP 工具 | `memory_action_create` | `memory_action_create { title, description, priority }` |\n| HTTP API | POST 请求 | `curl -X POST http://localhost:3111/agentmemory/actions` |\n| 自动提取 | 会话钩子 | 从长会话正文中自动识别 |\n\n### 4. 晶体化（Crystals）\n\n晶体是完成工作的冻结快照，通过 `memory_crystallize` 命令或 JSONL 导入时自动创建。资料来源：[src/viewer/index.html]()\n\n每个晶体包含：\n\n- 会话叙事摘要\n- 调用的关键工具及其结果\n- 修改的文件列表\n- 经验教训\n\n晶体是压缩的行动摘要——每个会话发生事件的 3 行摘要，用于为下一个会话提供快速上下文，而无需重新阅读所有内容。\n\n### 5. 隐私保护（Privacy）\n\nAgentMemory 内置了强大的隐私过滤功能，确保敏感信息不会被意外记录。资料来源：[src/functions/privacy.ts]()\n\n支持的隐私标签格式：\n\n```xml\n\n敏感内容\n\n```\n\n自动检测的敏感模式包括：\n\n| 模式类型 | 匹配示例 |\n|----------|----------|\n| API 密钥 | `api_key`, `secret`, `token`, `credential` |\n| Bearer 令牌 | `Bearer xxxxx...` |\n| OpenAI 密钥 | `sk-proj-...` |\n| Anthropic 密钥 | `sk-ant-...` |\n| GitHub 令牌 | `ghp_...`, `github_pat_...` |\n| 云服务商密钥 | `xoxb-...`, `AKIA...`, `AIza...` |\n| NPM 令牌 | `npm_...` |\n| GitLab 令牌 | `glpat-...` |\n\n## 支持的代理客户端\n\nAgentMemory 支持多种第一方插件和 MCP 原生客户端。资料来源：[website/components/Agents.tsx]()\n\n### 第一方支持的代理\n\n| 代理名称 | 来源 | 说明 |\n|----------|------|------|\n| Claude Code | Anthropic | Anthropic 官方 CLI 工具 |\n| Codex CLI | OpenAI | OpenAI 命令行编码代理 |\n| OpenClaw | OpenClaw | 开源编码代理 |\n| Hermes | Hermes | 自定义代理方案 |\n| PI | Personal Intelligence | 个人智能助手 |\n| OpenHuman | OpenHuman | 开放人类项目 |\n\n### MCP 原生支持\n\n对于其他 MCP 客户端，AgentMemory 提供自动连接能力：\n\n```bash\nagentmemory connect \n```\n\n此命令会自动配置并连接所有支持的 MCP 客户端。\n\n## 安装与部署\n\n### 快速安装\n\nAgentMemory 可通过 npm 直接安装：\n\n```bash\nnpm install @agentmemory/agentmemory\n```\n\n或使用 npx 快速启动：\n\n```bash\nnpx agentmemory\n```\n\n服务默认运行在 **http://localhost:3111** 端口。资料来源：[website/components/Install.tsx]()\n\n### 架构特性\n\nAgentMemory 的核心设计原则：\n\n| 特性 | 说明 |\n|------|------|\n| 本地运行 | 在用户机器上运行，无需云服务 |\n| 数据本地存储 | 所有数据保留在本地，不上传 |\n| 多模型支持 | 支持 Anthropic、Gemini、MiniMax、OpenRouter |\n| MCP 协议 | 标准化 Model Context Protocol 接口 |\n| 自包含 | 零外部数据库依赖 |\n\n## API 端点\n\nAgentMemory 提供 HTTP REST API 用于与外部系统集成：\n\n| 端点 | 方法 | 用途 |\n|------|------|------|\n| `/agentmemory/actions` | POST | 创建行动 |\n| `/agentmemory/sessions` | GET | 获取会话列表 |\n| `/agentmemory/audit` | GET | 获取审计日志 |\n\n### API 调用示例\n\n```bash\n# 创建行动\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n## 摘要生成系统\n\nAgentMemory 包含会话摘要生成功能，用于将多个观察记录整合为简洁的会话摘要。资料来源：[src/prompts/summary.ts]()\n\n摘要输出格式：\n\n```xml\n\n 会话标题（最多100字符）\n 3-5句成就叙事\n \n 关键决策1\n \n \n 修改的文件路径\n \n \n 关键概念\n \n\n```\n\n摘要系统规则：\n\n- 聚焦于成果而非单个工具调用\n- 突出决策及其理由\n- 列出所有创建或修改的文件\n- 概念应为可搜索的术语，便于未来上下文检索\n\n## 技术栈\n\n| 组件 | 技术 |\n|------|------|\n| 服务器 | Node.js / TypeScript |\n| 客户端协议 | MCP (Model Context Protocol) |\n| 数据存储 | 本地文件系统 |\n| 运行时端口 | 3111 (默认) |\n| 包管理 | npm |\n| 开源协议 | Apache-2.0 |\n\n## 总结\n\nAgentMemory 是一个专为 AI 编码代理设计的完整内存运行时，通过 MCP 协议与各类代理客户端集成。它提供了从原始观察记录到语义记忆、再到晶体化摘要的完整数据生命周期管理，同时内置隐私保护机制确保敏感信息安全。项目采用本地优先设计，数据完全存储在用户本地，支持多种 AI 模型和代理客户端，是构建具有持久记忆能力的 AI 辅助开发环境的基础设施。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#intro), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/rohitg00/agentmemory/blob/main/src/cli.ts)\n- [examples/python/observe_and_recall.py](https://github.com/rohitg00/agentmemory/blob/main/examples/python/observe_and_recall.py)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 快速开始\n\n## 概述\n\nAgentMemory 是一个完整的内存运行时系统，专为 AI 编码代理设计。它提供了**捕获（Capture）**、**召回（Recall）**、**整合（Consolidate）**、**观察（Observe）** 和 **联邦（Federate）** 五项核心能力，使 AI 代理能够在多个会话之间保持上下文连贯性。\n\n默认服务器端口为 **3111**，通过 REST API 和 MCP（Model Context Protocol）两种方式提供服务。\n\n## 环境要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | >= 20 | 运行服务器的核心依赖 |\n| npm | 内置于 Node | 包管理器 |\n| 模型提供商 | Anthropic / Gemini / MiniMax / OpenRouter | 支持多种 LLM 后端 |\n\n## 安装方式\n\n### 全局安装（推荐）\n\n```bash\nnpm install -g @agentmemory/agentmemory\n```\n\n### 本地安装\n\n```bash\nnpm install @agentmemory/agentmemory\n```\n\n安装完成后，可通过 `agentmemory connect ` 命令自动连接支持的代理。资料来源：[website/components/Install.tsx]()\n\n### MCP 客户端配置\n\nAgentMemory 支持多种 MCP 客户端的通用 JSON 配置方式：\n\n| 客户端 | 配置文件位置 | 特点 |\n|--------|--------------|------|\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 mcpServers 格式 |\n| Cursor | Deep Link 一键安装 | 自动化配置 |\n| Cline | `.cline/mcp_settings.json` | mcpServers 格式 |\n| Roo Code | `.roo/mcp_settings.json` | mcpServers 格式 |\n| WindSurf | 配置文件 | mcpServers 格式 |\n| Gemini CLI | 配置文件 | mcpServers 格式 |\n\n通用 MCP JSON 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"agentmemory\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx]()\n\n## 启动服务\n\n### 基本启动\n\n```bash\nagentmemory serve\n```\n\n服务器将在 `http://localhost:3111` 启动，提供以下核心端点：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/sessions` | GET/POST | 会话管理 |\n| `/observations` | GET/POST | 观察记录 CRUD |\n| `/actions` | GET/POST | 行动任务跟踪 |\n| `/audit` | GET | 审计日志查询 |\n| `/crystals` | GET | 压缩后的会话摘要 |\n| `/timeline` | GET | 时间线视图数据 |\n\n### 环境变量配置\n\n创建 `.env` 文件配置可选参数：\n\n```bash\n# 模型配置\nANTHROPIC_API_KEY=sk-...\nMODEL_PROVIDER=anthropic\n\n# 服务器配置\nPORT=3111\n\n# 存储配置\nDATA_DIR=./data\n```\n\n## 核心概念\n\n### 观察（Observations）\n\n观察是 AgentMemory 的基本记忆单元，记录代理在会话中执行的操作和关键事件。每个观察包含以下结构：\n\n```xml\n\n file_edit | command_run | search | error | decision | discovery | ...\n 简短描述（最多80字符）\n \n 具体事实细节\n \n 2-3句总结\n \n 路径/to/文件\n \n 1-10 重要性评分\n\n```\n\n重要性评分标准：\n- **1-3**：日常读取操作\n- **4-6**：编辑和命令执行\n- **7-9**：架构决策\n- **10**：破坏性变更\n\n资料来源：[src/prompts/compression.ts]()\n\n### 水晶（Crystals）\n\n水晶是压缩后的会话摘要快照，包含一个会话的叙事、调用过的工具（关键结果）、访问过的文件以及学到的经验教训。在 JSONL 导入时自动创建，或通过 `memory_crystallize` 手动生成。\n\n```xml\n\n 会话标题（最多100字符）\n 3-5句完成的工作叙事\n \n 做出的关键技术决策\n \n \n 修改的路径\n \n \n 会话中的关键概念\n \n\n```\n\n资料来源：[src/prompts/summary.ts]()\n\n### 行动（Actions）\n\n行动是代理在会话中发现的待办事项，包括需要重新访问的决策、需要检查的文件、等待输入的任务等。状态流转为：pending → active → done/blocked。\n\n创建方式：\n\n```bash\n# MCP 工具方式\nmemory_action_create { \"title\": \"ship v1\", \"priority\": \"high\" }\n\n# Curl 方式\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n资料来源：[src/viewer/index.html]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[启动 AgentMemory] --> B[连接代理]\n B --> C[创建会话]\n C --> D[执行操作]\n D --> E{触发钩子}\n E -->|工具调用| F[压缩观察]\n E -->|长会话体| G[自动提取行动]\n E -->|会话结束| H[生成水晶摘要]\n F --> I[存储到记忆库]\n G --> I\n H --> I\n I --> J[下次会话召回上下文]\n```\n\n## API 使用示例\n\n### 记录观察\n\n```bash\ncurl -X POST http://localhost:3111/observations \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"type\": \"file_write\",\n \"title\": \"Create user authentication module\",\n \"files\": [\"src/auth/login.ts\"],\n \"importance\": 7\n }'\n```\n\n### 查询记忆\n\n```python\nimport requests\n\n# 搜索相关观察\nresponse = requests.get(\n 'http://localhost:3111/observations',\n params={'query': 'authentication', 'limit': 10}\n)\nmemories = response.json()\n```\n\n### 获取会话时间线\n\n```bash\ncurl \"http://localhost:3111/timeline?session_id=abc123&page=0\"\n```\n\n## 查看器界面\n\nAgentMemory 提供内置 Web 查看器，可通过浏览器访问 `http://localhost:3111` 查看：\n\n- **Feature Flags**：功能开关管理\n- **Crystals**：压缩摘要列表，支持搜索\n- **Actions**：行动任务看板\n- **Timeline**：时间线视图，支持分页\n- **Activity**：活动概览和审计日志\n\n资料来源：[src/viewer/index.html]()\n\n## 代理集成\n\nAgentMemory 原生支持以下第一方代理插件：\n\n| 代理 | 说明 |\n|------|------|\n| Claude Code | Anthropic 官方 CLI |\n| Codex CLI | OpenAI 命令行工具 |\n| OpenClaw | 开源代理框架 |\n| Hermes | 定制化代理 |\n| PI | 专用代理 |\n| OpenHuman | 人类增强代理 |\n\n其他所有 MCP 客户端均可通过标准 MCP JSON 配置免费接入。\n\n资料来源：[website/components/Agents.tsx]()\n\n## 性能指标\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 检索 R@5 | 95.2% | Top-5 召回准确率 |\n| Token 减少 | 92% | 相比原始对话 |\n| 外部数据库 | 0 | 无需额外存储依赖 |\n\n资料来源：[website/app/opengraph-image.tsx]()\n\n## 验证安装\n\n```bash\n# 检查 CLI 是否可用\nagentmemory --version\n\n# 启动服务器并验证\nagentmemory serve &\ncurl http://localhost:3111/health\n```\n\n## 下一步\n\n- 阅读完整文档：https://github.com/rohitg00/agentmemory#quick-start\n- 查看集成示例：https://github.com/rohitg00/agentmemory/tree/main/integrations\n- 查阅变更日志：https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#intro), [数据流与处理](#data-flow), [记忆操作](#memory-operations)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 系统架构\n\n## 概述\n\nAgentMemory 是一个完整的 AI 代理记忆运行时系统，而非简单的向量数据库或工具库。该系统提供完整的记忆生命周期管理：捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）和联邦（Federate） 资料来源：[src/viewer/index.html]()\n\nAgentMemory 的核心设计理念是将原始观察数据转化为结构化的语义记忆，使 AI 代理能够在多次会话中保持上下文连贯性，避免重复工作并积累可复用的知识。\n\n## 核心架构组件\n\n### 系统服务层\n\nAgentMemory 以本地 HTTP 服务器形式运行，默认监听端口 **3111**，为所有记忆操作提供统一的 API 接口 资料来源：[website/components/LiveTerminal.tsx]()\n\n```mermaid\ngraph TD\n A[AI 代理] -->|MCP 协议| B[AgentMemory Server :3111]\n B --> C[JSONL 存储引擎]\n B --> D[LLM 处理管道]\n B --> E[Web Viewer 界面]\n \n C --> F[observations]\n C --> G[actions]\n C --> H[crystals]\n C --> I[sessions]\n```\n\n### 记忆类型体系\n\n系统定义了四种互补的记忆类型，分别承担不同的认知功能：\n\n| 记忆类型 | 用途 | 数据结构 |\n|---------|------|---------|\n| **Observations** | 原始工具调用记录 | 时间线形式，含分页 |\n| **Semantic Memory** | 事实性知识提取 | 置信度 + 强度评分 |\n| **Procedural Memory** | 可复用的操作流程 | 触发条件 + 步骤序列 |\n| **Crystals** | 会话级压缩摘要 | 3行精华总结 |\n\n资料来源：[src/viewer/index.html]()\n\n### 记忆处理管道\n\n记忆从原始观察到结构化知识的转化经过三个主要阶段：\n\n```mermaid\ngraph LR\n A[原始工具调用] -->|压缩| B[Observation]\n B -->|整合| C[Semantic Facts]\n B -->|整合| D[Procedures]\n B + C + D -->|汇总| E[Crystal]\n```\n\n#### 第一阶段：压缩（Compression）\n\n压缩引擎将原始工具调用转化为结构化的观察记录。该阶段使用专用的 LLM 提示模板，从每次工具调用中提取关键技术细节 资料来源：[src/prompts/compression.ts]()\n\n压缩输出包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `type` | enum | 工具调用类型（file_read/write/edit/command_run 等） |\n| `title` | string | 简短描述（最多80字符） |\n| `facts` | array | 具体事实细节列表 |\n| `narrative` | string | 2-3句总结 |\n| `concepts` | array | 可搜索的技术概念 |\n| `files` | array | 涉及的文件路径 |\n| `importance` | number | 1-10 重要性评分 |\n\n#### 第二阶段：整合（Consolidation）\n\n整合阶段从多次观察中提取高层次的语义记忆和程序性记忆 资料来源：[src/prompts/consolidation.ts]()\n\n- **语义记忆提取**：从重复出现的观察中提取稳定的事实断言，附带置信度评分\n- **程序性记忆提取**：识别重复执行2次以上的操作模式，提取为可自动触发的流程\n- **关系识别**：建立概念间的语义关联\n\n#### 第三阶段：摘要（Crystallization）\n\n每个会话结束时，系统生成晶体（Crystal）——会话的压缩精华摘要，包含：\n\n- 会话标题（最多100字符）\n- 3-5句叙事总结\n- 关键决策及理由\n- 修改的文件列表\n- 可搜索的概念标签 资料来源：[src/prompts/summary.ts]()\n\n### 观察数据模型\n\n观察记录在界面中以时间线形式展示，支持分页浏览：\n\n```typescript\ninterface Observation {\n id: string;\n timestamp: number;\n type: 'file_read' | 'file_write' | 'file_edit' | \n 'command_run' | 'search' | 'web_fetch' | \n 'conversation' | 'error' | 'decision' | \n 'discovery' | 'subagent' | 'notification' | \n 'task' | 'other';\n title: string;\n subtitle?: string;\n facts: string[];\n narrative: string;\n concepts: string[];\n files: string[];\n importance: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;\n hookType: string;\n toolName?: string;\n}\n```\n\n资料来源：[src/prompts/compression.ts]()\n\n### 语义记忆模型\n\n语义记忆条目展示时附带多维度评估指标：\n\n| 指标 | 说明 | 可视化 |\n|-----|------|-------|\n| **Confidence** | 事实置信度 | 百分比显示 |\n| **Strength** | 记忆强度 | 进度条（>70%为绿色） |\n| **重要性** | 对系统的影响程度 | 颜色编码 |\n\n资料来源：[src/viewer/index.html]()\n\n## 功能模块架构\n\n### 动作系统（Actions）\n\n动作系统追踪代理在会话中产生的后续跟进项，包括：\n\n- 需要重访的决策\n- 需要检查的文件\n- 等待输入的任务\n\n动作状态流转：`pending → active → done/blocked`\n\n创建方式支持三种渠道：\n1. MCP 工具调用 `memory_action_create`\n2. HTTP API 直接 POST\n3. 钩子自动从长会话正文中提取\n\n资料来源：[src/viewer/index.html]()\n\n### 特性标志系统（Feature Flags）\n\n系统内置可配置的特性标志机制，用于动态控制功能开关：\n\n```typescript\ninterface FeatureFlag {\n kind: string; // 样式类别\n dismissKey: string; // 关闭键\n icon: string; // 图标\n title: string; // 标题\n keyLabel: string; // 键标签\n desc: string; // 描述\n enable: string; // 启用命令\n docs?: string; // 文档链接\n}\n```\n\n特性标志支持折叠/展开展示，并可单独关闭 资料来源：[src/viewer/index.html]()\n\n### 隐私保护机制\n\n系统内置多层次隐私保护功能，用于检测和脱敏敏感信息 资料来源：[src/functions/privacy.ts]()\n\n**检测模式包括：**\n\n| 类别 | 正则模式 |\n|-----|---------|\n| 通用凭证 | `api_key`, `secret`, `token`, `password`, `credential` 等 |\n| Bearer Token | `Bearer [A-Za-z0-9._\\-+/=]{20,}` |\n| OpenAI Key | `sk-proj-[A-Za-z0-9\\-_]{20,}` |\n| Anthropic Key | `sk-ant-[A-Za-z0-9\\-_]{20,}` |\n| GitHub Token | `gh[pus]_[A-Za-z0-9]{36,}` |\n| GitHub PAT | `github_pat_[A-Za-z0-9_]{22,}` |\n| Slack Token | `xoxb-[A-Za-z0-9\\-]+` |\n| AWS Key | `AKIA[0-9A-Z]{16}` |\n| Google API | `AIza[A-Za-z0-9\\-_]{35}` |\n| NPM Token | `npm_[A-Za-z0-9]{36}` |\n| GitLab Token | `glpat-[A-Za-z0-9\\-_]{20,}` |\n\n此外，系统支持 `` XML 标签用于手动标记需要隐藏的内容区域。\n\n## 代理集成架构\n\n### MCP 原生支持\n\nAgentMemory 通过 Model Context Protocol (MCP) 实现与多种 AI 代理的原生集成：\n\n```mermaid\ngraph TD\n subgraph \"支持的代理\"\n A[Claude Code]\n B[Codex CLI]\n C[OpenClaw]\n D[Hermes]\n E[PI]\n F[OpenHuman]\n end\n \n A & B & C & D & E & F -->|agentmemory connect| G[MCP Server]\n G --> H[AgentMemory Core]\n```\n\n连接命令：`agentmemory connect ` 自动配置所有兼容代理 资料来源：[website/components/Agents.tsx]()\n\n### 审计日志\n\n系统记录完整的操作审计日志，包含：\n\n- 会话历史（sessions）\n- 审计条目（audit，含200条限制）\n\n资料来源：[src/viewer/index.html]()\n\n## Web Viewer 架构\n\nWeb Viewer 提供图形化的记忆查看界面，包含以下视图模块：\n\n| 视图 | 功能 |\n|-----|------|\n| **Timeline** | 时间线形式浏览所有观察记录，支持按类型筛选和分页 |\n| **Actions** | 跟踪和管理代理产生的后续动作项 |\n| **Crystals** | 查看压缩后的会话摘要，支持搜索 |\n| **Activity** | 展示会话和审计活动的聚合视图 |\n| **Audit** | 详细的操作审计日志 |\n\n每个视图都包含搜索功能、筛选机制和分页导航 资料来源：[src/viewer/index.html]()\n\n## 数据存储架构\n\nAgentMemory 采用 **JSONL**（JSON Lines）格式进行本地存储，无需外部数据库依赖 资料来源：[src/viewer/index.html]()\n\n存储特点：\n\n- **无外部依赖**：零外部数据库，降低部署复杂度\n- **会话隔离**：每个会话的原始观察独立存储\n- **自动清理**：原始观察定期修剪，仅保留晶体摘要\n- **可追溯性**：晶体保存后仍可重放会话的关键信息\n\n## 开发贡献架构\n\n项目采用标准化的分支管理策略 资料来源：[CONTRIBUTING.md]()\n\n| 分支类型 | 命名格式 | 用途 |\n|---------|---------|------|\n| 功能分支 | `feat/` | 新功能开发 |\n| 修复分支 | `fix/-` | Bug 修复 |\n| 文档分支 | `docs/` | 文档更新 |\n| 重构分支 | `refactor/` | 代码重构 |\n| 维护分支 | `chore/` | 其他维护工作 |\n\n开发流程要求：\n- Node >= 20\n- TypeScript 编译通过\n- 全量测试通过\n- 所有提交包含签名（`-s` 标志）\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 运行时 | Node.js (>=20) |\n| 类型系统 | TypeScript |\n| 存储 | JSONL (本地文件) |\n| 通信协议 | HTTP REST API |\n| 代理集成 | MCP (Model Context Protocol) |\n| 界面 | Web Viewer (HTML/JS) |\n| AI 处理 | LLM API (可配置) |\n\nAgentMemory 的设计目标是在本地环境中提供企业级的记忆管理能力，同时保持零外部依赖和快速启动特性。通过 MCP 协议的广泛兼容性，系统可以无缝集成到现有的 AI 代理工作流中。\n\n---\n\n\n\n## 数据流与处理\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [记忆操作](#memory-operations), [搜索与检索](#search-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 数据流与处理\n\n## 概述\n\nAgentMemory 的数据流与处理系统是一个完整的数据处理管道，负责从原始工具调用观测中提取、压缩、总结并最终整合为可重用的结构化记忆。该系统采用分层处理架构，将观测数据逐级转化为语义记忆、程序记忆和关系记忆三种核心记忆类型，为 AI 代理提供持久化上下文能力。\n\n数据处理管道的设计遵循以下核心原则：高保真度保留技术细节、高压缩率降低 token 消耗、自动隐私保护机制。系统无需外部数据库，仅依赖本地 JSONL 文件存储即可运行。\n\n## 核心处理流程\n\n### 数据处理阶段总览\n\n```mermaid\ngraph TD\n A[原始工具调用] --> B[观测捕获 observe]\n B --> C[压缩处理 compress]\n C --> D[会话总结 summary]\n D --> E[记忆整合 consolidation]\n E --> F[关系映射 relations]\n F --> G[索引持久化 persistence]\n G --> H[检索召回 remember]\n \n B1[隐私检测] -.->|过滤敏感信息| B\n C1[XML 结构化] -.->|格式标准化| C\n D1[叙事生成] -.->|上下文连贯| D\n E1[程序提取] -.->|可复用知识| E\n```\n\n### 阶段一：观测捕获\n\n观测捕获是数据进入系统的入口点。当代理执行工具调用或触发特定钩子时，系统实时捕获这些事件。捕获内容包括工具名称、执行参数、返回结果、执行时间戳等元数据。观测类型映射表如下：\n\n| 观测类型 | 对应工具/钩子 | 说明 |\n|---------|--------------|------|\n| file_read | Read | 文件读取操作 |\n| file_write | Write | 文件写入操作 |\n| file_edit | Edit | 文件编辑操作 |\n| command_run | Bash | 命令执行操作 |\n| search | Grep/Glob | 搜索操作 |\n| web_fetch | WebFetch/WebSearch | 网络获取 |\n| conversation | AskUserQuestion | 用户对话 |\n| subagent | Task | 子任务执行 |\n\n### 阶段二：压缩处理\n\n压缩处理将原始观测转化为结构化的 XML 格式，这是系统实现 92% token 减少量的关键步骤。\n\n压缩系统提示词定义了严格的数据结构要求：\n\n```xml\n\n one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other\n Short descriptive title (max 80 chars)\n One-line context (optional)\n \n Specific factual detail 1\n Specific factual detail 2\n \n 2-3 sentence summary of what happened and why it matters\n \n technical concept or pattern\n \n \n path/to/file\n \n 1-10 scale\n\n```\n\n**重要性评分标准**：\n\n| 分数范围 | 含义 | 示例场景 |\n|---------|------|---------|\n| 1-3 | 常规操作 | 日常文件读取 |\n| 4-6 | 中等变更 | 编辑命令执行 |\n| 7-9 | 架构决策 | 核心设计变更 |\n| 10 | 破坏性变更 | API 重大修改 |\n\n压缩处理函数 `buildCompressionPrompt` 接收原始观测数据，生成符合系统提示词要求的压缩指令，用于调用 LLM 生成结构化输出。\n\n资料来源：[src/prompts/compression.ts:1-29]()\n\n### 阶段三：会话总结\n\n会话总结从多个压缩观测中提取会话级别的元信息，生成会话摘要。总结系统采用 XML 结构化输出：\n\n```xml\n\n Short session title (max 100 chars)\n 3-5 sentence narrative of what was accomplished\n \n Key technical decision made\n \n \n path/to/modified/file\n \n \n key concept from session\n \n\n```\n\n`buildSummaryPrompt` 函数将多个观测对象格式化为标准输入文本，供 LLM 生成会话级摘要。该函数将每个观测的 facts、narrative、files 和 concepts 字段进行格式化重组，确保 LLM 能够理解完整的会话上下文。\n\n资料来源：[src/prompts/summary.ts:1-45]()\n\n## 记忆整合与提炼\n\n### 程序记忆提取\n\n程序记忆提取是系统的核心知识提炼机制。当同一操作模式在多个会话中出现 2 次以上时，系统自动识别并提取为可复用程序。\n\n提取规则：\n\n| 规则类型 | 描述 |\n|---------|------|\n| 频率阈值 | 仅提取出现 2+ 次的模式 |\n| 步骤粒度 | 每个步骤需具体可执行 |\n| 触发条件 | 条件需足够具体以支持自动匹配 |\n\n程序提取提示词模板：\n\n```\nExtract reusable procedures from these recurring patterns:\n\n[Pattern 1] (seen 3x)\n\n\n[Pattern 2] (seen 2x)\n\n```\n\n该提示词驱动 LLM 从高频模式中归纳出通用的操作流程和触发条件。\n\n资料来源：[src/prompts/consolidation.ts:7-15]()\n\n### 记忆聚类与反思\n\n记忆聚类将语义相关的记忆项组织在一起，反思系统在此基础上生成高层洞察：\n\n```typescript\n// 聚类输出结构\ncluster = {\n facts: [{ fact: string, confidence: number }],\n lessons: [{ content: string, confidence: number }],\n crystalNarratives: [string]\n}\n```\n\n反思过程生成的洞察包括：\n\n| 类别 | 说明 |\n|-----|------|\n| 已知事实 | 高置信度的技术事实 |\n| 经验教训 | 从操作中提炼的可复用经验 |\n| 完成工作摘要 | 已完成项目的关键叙事 |\n\n资料来源：[src/prompts/reflect.ts:10-30]()\n\n## 隐私保护机制\n\n### 敏感信息检测\n\n隐私处理模块维护了一个全面的敏感信息检测模式列表：\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n // API 密钥类\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n // Bearer Token\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n // OpenAI 密钥\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n // Anthropic 密钥\n /sk-ant-[A-Za-z0-9\\-_]{20,}/g,\n // GitHub Token\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /github_pat_[A-Za-z0-9_]{22,}/g,\n // Slack Token\n /xoxb-[A-Za-z0-9\\-]+/g,\n // AWS 密钥\n /AKIA[0-9A-Z]{16}/g,\n // Google API Key\n /AIza[A-Za-z0-9\\-_]{35}/g,\n // JWT\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n // NPM Token\n /npm_[A-Za-z0-9]{36}/g,\n // GitLab Token\n /glpat-[A-Za-z0-9\\-_]{20,}/g\n];\n```\n\n### 隐私标签处理\n\n除了正则匹配外，系统还支持 `` XML 标签包裹的隐私内容：\n\n```typescript\nconst PRIVATE_TAG_RE = /[\\s\\S]*?<\\/private>/gi;\n```\n\n所有检测到的敏感信息都会在进入压缩管道前被过滤或脱敏，确保输出中不包含任何凭据信息。\n\n资料来源：[src/functions/privacy.ts:1-20]()\n\n## 数据存储与持久化\n\n### 存储架构\n\nAgentMemory 采用零外部依赖的存储架构，所有数据以 JSONL 格式存储于本地文件系统：\n\n| 数据类型 | 存储格式 | 说明 |\n|---------|---------|------|\n| 观测记录 | JSONL | 每行一条压缩观测 |\n| 会话摘要 | JSONL | 每行一个会话总结 |\n| 索引数据 | JSON | 快速检索索引 |\n| 元数据 | JSON | 配置和状态信息 |\n\n### 持久化策略\n\n系统在处理过程中自动触发持久化操作，关键时机包括：\n\n1. **观测压缩完成后**：立即写入观测记录\n2. **会话结束时**：生成并存储会话摘要\n3. **记忆整合后**：更新相关索引\n4. **定时检查点**：防止数据丢失\n\n## 检索与召回\n\n### 召回流程\n\n当代理需要检索历史记忆时，系统执行以下召回流程：\n\n```mermaid\ngraph LR\n A[查询请求] --> B[语义匹配]\n B --> C[重要性过滤]\n C --> D[相关性排序]\n D --> E[上下文组装]\n E --> F[返回结果]\n```\n\n### 召回策略\n\n| 策略 | 说明 | 优先级 |\n|-----|------|-------|\n| 精确匹配 | 文件路径、函数名等精确匹配 | 高 |\n| 语义相似 | 基于概念嵌入的相似度匹配 | 中 |\n| 时间衰减 | 近期记忆权重更高 | 低 |\n| 使用频率 | 高频访问记忆优先 | 低 |\n\n## 配置参数\n\n### 核心配置项\n\n| 参数 | 默认值 | 说明 |\n|-----|-------|------|\n| POLL_INTERVAL_MS | 10000 | 轮询间隔（毫秒） |\n| WS_MAX_RETRIES | 4 | WebSocket 最大重试次数 |\n| DIRECT_FAILURE_THRESHOLD | 2 | 直接连接失败阈值 |\n| importance.minThreshold | 0 | 最小重要性阈值 |\n\n## 技术总结\n\nAgentMemory 的数据流与处理系统通过分层处理架构，实现了从原始观测到结构化记忆的完整转换：\n\n- **观测层**：实时捕获工具调用和系统事件\n- **压缩层**：XML 结构化压缩，token 减少 92%\n- **总结层**：会话级别叙事生成\n- **整合层**：程序记忆提取和聚类反思\n- **存储层**：JSONL 本地持久化，零外部依赖\n- **召回层**：多策略检索和上下文组装\n\n整个处理管道支持实时处理和批量处理两种模式，通过 WebSocket 和 HTTP API 对外提供服务，确保与各类 MCP 客户端的兼容性。\n\n---\n\n\n\n## 记忆操作\n\n### 相关页面\n\n相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 记忆操作\n\nAgentMemory 是一个完整的记忆运行时系统，提供多种记忆操作能力来捕获、召回、整合和观察 AI 代理的工作记忆。本页详细介绍记忆操作的核心概念、数据模型和系统交互流程。\n\n## 系统概述\n\nAgentMemory 的记忆操作涵盖四大核心能力领域：\n\n| 操作类型 | 功能描述 | 数据持久化 |\n|---------|---------|-----------|\n| **记忆压缩** (Compression) | 将原始工具调用观测压缩为结构化数据 | 观察记录 |\n| **会话摘要** (Summary) | 生成会话级别的叙事性摘要 | 水晶 (Crystals) |\n| **反思整合** (Reflection) | 从记忆簇中提取高层洞察 | 语义/程序性记忆 |\n| **隐私处理** (Privacy) | 自动过滤敏感信息和凭证 | 无持久化 |\n\n资料来源：[src/prompts/compression.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n## 核心数据模型\n\n### 观察记录 (Observation)\n\n每次工具调用后系统会生成结构化的观察记录，格式如下：\n\n```xml\n\n one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other\n Short descriptive title (max 80 chars)\n One-line context (optional)\n \n Specific factual detail 1\n Specific factual detail 2\n \n 2-3 sentence summary of what happened and why it matters\n \n technical concept or pattern\n \n \n path/to/file\n \n 1-10 scale, 10 being critical architectural decision\n\n```\n\n**重要性评分标准：**\n\n| 评分范围 | 含义 | 示例场景 |\n|---------|------|---------|\n| 1-3 | 常规读取操作 | 读取配置文件、查看文档 |\n| 4-6 | 编辑和命令执行 | 修改代码、运行测试 |\n| 7-9 | 架构决策 | API 设计变更、依赖调整 |\n| 10 | 重大变更 | 破坏性更改、安全修复 |\n\n资料来源：[src/prompts/compression.ts:3-31](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n### 水晶 (Crystals)\n\n水晶是会话完成后的冻结快照，捕获单个会话的叙事、调用工具的关键结果、触及的文件以及提炼的经验教训。\n\n```html\n
\n Crystals are frozen snapshots of completed work. \n Each crystal captures one session's narrative, the tools invoked (key outcomes), \n files touched, and lessons surfaced — a replayable summary you keep after \n raw observations are pruned.\n
\n```\n\n**水晶数据结构：**\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| title | string | 会话标题（最多100字符） |\n| narrative | string | 3-5句完成事项叙事 |\n| decisions | array | 做出的技术决策 |\n| files | array | 创建或修改的文件路径 |\n| concepts | array | 可搜索的关键概念 |\n\n资料来源：[src/viewer/index.html:1-50](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html) 和 [src/prompts/summary.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n\n### 语义记忆与程序性记忆\n\n系统将观察记录分类存储为两种互补的记忆形式：\n\n**语义记忆 (Semantic Memory)**：存储事实性信息，基于置信度评分。\n\n```html\n
Semantic Memory
\n semFacts.slice(0, 5).forEach(function(f) {\n var conf = typeof f.confidence === 'number' ? Math.round(f.confidence * 100) : null;\n var str = typeof f.strength === 'number' ? Math.round(f.strength * 100) : null;\n });\n
\n```\n\n**程序性记忆 (Procedural Memory)**：存储可重用的操作流程，从反复出现的模式中提取。\n\n> 资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n## 操作流程\n\n### 记忆压缩流程\n\n```mermaid\ngraph TD\n A[工具调用完成] --> B[触发压缩钩子]\n B --> C[构建压缩提示词]\n C --> D[调用 LLM 生成结构化观察]\n D --> E{隐私检查}\n E -->|发现敏感信息| F[标记为 private]\n E -->|无敏感信息| G[直接存储]\n F --> H[存储观察记录]\n G --> H\n H --> I[更新时间线视图]\n```\n\n压缩提示词系统包含三类操作：\n\n| 操作 | 触发条件 | 产物 |\n|-----|---------|-----|\n| 压缩 (Compression) | 单次工具调用完成 | 单条观察记录 |\n| 摘要 (Summary) | 会话结束或手动触发 | 水晶快照 |\n| 整合 (Consolidation) | 多个相关观察积累 | 高阶洞察 |\n\n资料来源：[src/prompts/compression.ts:31-45](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n### 会话摘要生成\n\n```mermaid\ngraph LR\n A[观察记录集合] --> B[压缩为结构化数据]\n B --> C[构建摘要提示词]\n C --> D[LLM 生成 XML 格式摘要]\n D --> E[解析并存储为水晶]\n E --> F[供后续会话检索使用]\n```\n\n**摘要生成规则：**\n\n- 聚焦成果，而非单个工具调用\n- 突出决策及其理由\n- 列出所有创建或修改的文件\n- 概念应为可搜索术语，用于未来上下文检索\n\n资料来源：[src/prompts/summary.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n\n### 反思整合流程\n\n```mermaid\ngraph TD\n A[相关记忆簇] --> B[收集已知事实]\n B --> C[提取经验教训]\n C --> D[汇总水晶叙事]\n D --> E[构建反思提示词]\n E --> F[生成高阶洞察]\n F --> G[更新语义/程序性记忆]\n```\n\n反思操作从记忆簇中综合提炼出更高层次的见解，包含：\n\n- 已知事实 (Known Facts)：带置信度的技术事实\n- 经验教训 (Lessons Learned)：带置信度的行为准则\n- 完成工作摘要 (Completed Work Summaries)：会话叙事片段\n\n资料来源：[src/prompts/reflect.ts:1-40](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n\n## 隐私处理机制\n\nAgentMemory 内置敏感信息自动过滤功能，在记忆压缩前扫描输出内容。\n\n### 检测模式\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n /sk-ant-[A-Za-z0-9\\-_]{20,}/g,\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /github_pat_[A-Za-z0-9_]{22,}/g,\n /xoxb-[A-Za-z0-9\\-]+/g,\n /AKIA[0-9A-Z]{16}/g,\n /AIza[A-Za-z0-9\\-_]{35}/g,\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n /npm_[A-Za-z0-9]{36}/g,\n /glpat-[A-Za-z0-9\\-_]{20,}/g,\n];\n```\n\n### 隐私处理规则\n\n| 标签格式 | 作用 | 持久化 |\n|---------|------|--------|\n| `...` | 包裹敏感内容 | 不存储 |\n\n隐私扫描覆盖的凭证类型：\n\n| 类型 | 匹配模式示例 |\n|-----|-------------|\n| API 密钥 | `api_key=xxx...`、`secret: xxx...` |\n| Bearer 令牌 | `Bearer eyJ...` |\n| OpenAI 密钥 | `sk-proj-xxx...` |\n| Anthropic 密钥 | `sk-ant-xxx...` |\n| GitHub 令牌 | `ghp_xxx...`、`github_pat_xxx...` |\n| Slack 令牌 | `xoxb-xxx...` |\n| AWS 密钥 | `AKIAxxx...` |\n| Google API | `AIzaxxx...` |\n| NPM 令牌 | `npm_xxx...` |\n| GitLab 令牌 | `glpat-xxx...` |\n\n资料来源：[src/functions/privacy.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n\n## 可视化界面\n\nAgentMemory 提供 Web 查看器界面，支持多种记忆操作的交互式展示。\n\n### 时间线视图\n\n观察记录以时间线形式展示，支持分页浏览：\n\n```html\n
\n \n Page 1 of 10 (95 total)\n \n
\n```\n\n**时间线过滤类型：**\n\n- `file_read` - 文件读取\n- `file_write` - 文件写入\n- `file_edit` - 文件编辑\n- `command_run` - 命令执行\n- `search` - 搜索操作\n- `error` - 错误记录\n- `decision` - 决策记录\n\n### 记忆检索\n\n```html\n\n```\n\n支持对水晶、语义记忆、程序性记忆、经验教训等多种记忆类型的全文搜索。\n\n### 功能标志 (Feature Flags)\n\n系统支持通过 URL 参数启用或禁用特定功能：\n\n```html\n
\n ' + b.icon + '\n
\n
' + b.title + ' ' + b.keyLabel + '
\n ' + esc(b.enable) + '\n
\n
\n```\n\n资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n## 操作 API 概览\n\n基于记忆操作的核心函数接口：\n\n| 函数 | 用途 | 输入 | 输出 |\n|-----|------|-----|-----|\n| `buildCompressionPrompt` | 构建压缩提示词 | 工具调用信息 | 格式化的提示字符串 |\n| `buildSummaryPrompt` | 构建摘要提示词 | 观察记录数组 | 格式化的摘要提示 |\n| `buildReflectionPrompt` | 构建反思提示词 | 记忆簇数据 | 格式化的反思提示 |\n| `buildProceduralExtractionPrompt` | 提取程序性记忆 | 模式数组 | 格式化提取提示 |\n\n所有构建函数均位于 `src/prompts/` 目录下，采用纯函数设计，便于测试和组合使用。\n\n资料来源：[src/prompts/consolidation.ts:1-20](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n\n## 总结\n\nAgentMemory 的记忆操作构成了一个完整的信息生命周期管理系统：\n\n1. **捕获阶段**：通过压缩机制将原始工具调用转化为结构化观察\n2. **组织阶段**：通过摘要和反思机制将观察整合为水晶和高层洞察\n3. **检索阶段**：通过多种视图和搜索机制支持快速上下文召回\n4. **保护阶段**：通过隐私扫描确保敏感信息安全处理\n\n该系统设计遵循\"数据本地化、Token 高效化、外部依赖最小化\"的原则，所有记忆操作均可在本地完成，无需外部数据库支持。\n\n---\n\n\n\n## 搜索与检索\n\n### 相关页面\n\n相关主题：[记忆操作](#memory-operations), [记忆压缩与合并](#consolidation), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/functions/smart-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/smart-search.ts)\n- [src/functions/search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/search.ts)\n- [src/functions/graph-retrieval.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/graph-retrieval.ts)\n- [src/state/hybrid-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/hybrid-search.ts)\n- [src/state/vector-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/vector-index.ts)\n- [src/state/search-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/search-index.ts)\n- [src/state/reranker.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/reranker.ts)\n
\n\n# 搜索与检索\n\nAgentMemory 的搜索与检索系统是整个记忆运行时的核心能力之一，负责从语义记忆、程序性记忆、关系网络等多种数据存储中高效定位并召回相关信息。该系统采用混合检索架构，结合向量相似度搜索、关键词倒排索引和图关系遍历，为 AI 编码代理提供精准的上下文召回能力。\n\n## 系统架构总览\n\nAgentMemory 的搜索系统由多个相互协作的模块组成，形成一个多层次的检索管道：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Smart Search 智能搜索]\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 H --> I[最终结果]\n```\n\n核心模块分布在两个目录层级：\n\n| 目录 | 职责 | 关键文件 |\n|------|------|----------|\n| `src/functions/` | 搜索业务逻辑与 API 封装 | `smart-search.ts`, `search.ts`, `graph-retrieval.ts` |\n| `src/state/` | 索引数据结构和检索算法实现 | `hybrid-search.ts`, `vector-index.ts`, `search-index.ts`, `reranker.ts` |\n\n## 向量索引检索\n\n向量索引是语义相似度搜索的基础设施。AgentMemory 使用向量嵌入表示语义记忆中的事实、概念和叙述文本，支持基于余弦相似度或欧氏距离的近似最近邻搜索。\n\n### 索引数据结构\n\n向量索引模块维护以下核心数据结构：\n\n- **嵌入向量存储**：将文本内容转换为高维向量并持久化存储\n- **元数据索引**：为每个向量关联来源、时间戳、置信度等元信息\n- **分区索引**：按语义类别或时间窗口对向量进行分区优化查询性能\n\n### 检索流程\n\n```mermaid\ngraph LR\n A[查询文本] --> B[嵌入模型]\n B --> C[查询向量]\n C --> D[ANN搜索]\n D --> E[候选集]\n E --> F[元数据过滤]\n F --> G[排序结果]\n```\n\n向量检索的关键参数包括：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `topK` | `number` | 返回的最相似结果数量 |\n| `minScore` | `number` | 最小相似度阈值 |\n| `filters` | `object` | 元数据过滤条件 |\n| `embeddingModel` | `string` | 指定的嵌入模型名称 |\n\n## 倒排索引检索\n\n倒排索引提供基于关键词的精确匹配能力，与向量检索形成互补。搜索索引模块维护从术语到记忆条目的映射，支持布尔查询和短语匹配。\n\n### 索引构建\n\n索引构建过程包括以下步骤：\n\n1. **文本分词**：对记忆内容进行标准化分词处理\n2. **术语提取**：识别关键词和实体名称\n3. **倒排列表构建**：建立术语到文档 ID 的映射\n4. **权重计算**：基于 TF-IDF 或 BM25 计算术语权重\n\n### 查询处理\n\n倒排索引检索支持多种查询语法：\n\n- **AND 查询**：`term1 AND term2` - 返回同时包含两个术语的结果\n- **OR 查询**：`term1 OR term2` - 返回包含任一术语的结果\n- **短语查询**：`\"exact phrase\"` - 精确匹配短语\n- **字段限定**：`field:value` - 限定搜索特定字段\n\n## 图关系检索\n\n图检索模块维护记忆条目之间的语义关系网络，支持基于关系路径的扩展检索。\n\n### 关系类型\n\nAgentMemory 中的关系包括：\n\n| 关系类型 | 描述 | 示例 |\n|----------|------|------|\n| `causes` | 因果关系 | 修改配置导致应用重启 |\n| `implements` | 实现关系 | 抽象接口被具体类实现 |\n| `depends_on` | 依赖关系 | 模块 A 依赖模块 B |\n| `related_to` | 关联关系 | 相关但非直接因果 |\n| `derived_from` | 派生关系 | 经验教训来源于具体案例 |\n\n### 图遍历算法\n\n图检索支持以下遍历策略：\n\n```mermaid\ngraph TD\n A[起点节点] --> B[直接邻居]\n A --> C[2度邻居]\n A --> D[N度可达]\n B --> E[BFS广度优先]\n C --> E\n D --> F[DFS深度优先]\n B --> G[PageRank排序]\n C --> G\n```\n\n- **广度优先搜索 (BFS)**：适合查找最近关联的记忆\n- **深度优先搜索 (DFS)**：适合探索完整的语义路径\n- **PageRank 排序**：根据关系重要性权重排序结果\n\n## 混合搜索调度\n\n混合搜索是 AgentMemory 检索系统的核心调度层，协调向量检索、倒排索引和图检索的结果融合。\n\n### 融合策略\n\n混合搜索支持多种结果融合策略：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `reciprocal_rank` | 倒数排名融合 | 多源结果互补 |\n| `compressed_score` | 加权分数融合 | 需要精确控制各源权重 |\n| `rrf_k` | 倒数排名融合因子 | 平衡精确性和多样性 |\n\n### 调度配置\n\n混合搜索的调度参数包括：\n\n```typescript\ninterface HybridSearchConfig {\n vectorWeight: number; // 向量检索权重\n keywordWeight: number; // 关键词检索权重\n graphWeight: number; // 图检索权重\n fusionStrategy: 'rrf' | 'weighted' | 'composite';\n minRelevanceScore: number; // 最低相关性阈值\n maxResults: number; // 最大返回结果数\n}\n```\n\n## 重排序器\n\n重排序器（Reranker）对候选结果进行精细化排序，提升最终结果的相关性。\n\n### 排序算法\n\n重排序器采用多信号融合排序：\n\n1. **原始相似度分数**：来自向量或关键词检索的初始分数\n2. **关系重要性**：基于图结构的节点重要性得分\n3. **时效性权重**：新近更新的记忆获得更高权重\n4. **使用频率**：高频访问的记忆获得提升\n5. **隐私敏感性**：敏感内容可能被降权或过滤\n\n### 排序公式\n\n综合排序分数计算如下：\n\n```\nfinalScore = α × vectorScore + β × keywordScore + γ × graphScore + δ × recencyScore + ε × usageScore\n```\n\n其中 `α`, `β`, `γ`, `δ`, `ε` 为可配置的权重系数，满足 `α + β + γ + δ + ε = 1`。\n\n## 隐私过滤\n\n检索系统在返回结果前必须经过隐私过滤器处理，确保敏感信息不被泄露。\n\n### 敏感信息检测\n\n隐私过滤器使用正则表达式检测敏感数据：\n\n| 模式类型 | 正则表达式特征 | 示例 |\n|----------|----------------|------|\n| API 密钥 | `api[_-]?key\\|secret\\|token` | `sk-xxxx...` |\n| Bearer 令牌 | `Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}` | `Bearer eyJ...` |\n| GitHub 令牌 | `gh[pus]_[A-Za-z0-9]{36,}` | `ghp_xxxx...` |\n| NPM 令牌 | `npm_[A-Za-z0-9]{36}` | `npm_xxxx...` |\n| JSON Web 令牌 | `eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}` | `eyJhbG...` |\n\n资料来源：[src/functions/privacy.ts:4-22]()\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[检索结果] --> B{包含敏感内容?}\n B -->|是| C[标记敏感字段]\n B -->|否| F[通过]\n C --> D{完全敏感?}\n D -->|是| E[从结果中移除]\n D -->|否| F\n E --> G[返回过滤后结果]\n F --> G\n```\n\n隐私过滤器会将 `` 标签包裹的内容完全移除，确保返回给用户的结果不包含任何凭证、密钥或个人身份信息。\n\n## 语义记忆检索\n\n语义记忆是检索系统最重要的数据来源之一，包含从观察记录中提取的事实性知识。\n\n### 语义事实结构\n\n检索到的语义事实包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `fact` | `string` | 事实内容文本 |\n| `confidence` | `number` | 置信度 (0-1) |\n| `strength` | `number` | 强度 (0-1) |\n| `extractedAt` | `timestamp` | 提取时间 |\n\n### 检索展示\n\n在 AgentMemory Viewer 界面中，语义记忆以卡片形式展示，显示置信度和强度条：\n\n```html\n\n
\n
{fact}
\n
\n
{strength}%
\n
\n```\n\n## 观察记录检索\n\n观察记录（Observations）是从代理工具调用中提取的原始记忆单元，经过压缩后存储。\n\n### 观察类型\n\n| 类型 | 描述 | 重要性范围 |\n|------|------|------------|\n| `file_read` | 文件读取 | 1-3 |\n| `file_write` | 文件写入 | 4-6 |\n| `file_edit` | 文件编辑 | 4-6 |\n| `command_run` | 命令执行 | 4-6 |\n| `error` | 错误信息 | 7-9 |\n| `decision` | 决策记录 | 7-9 |\n| `discovery` | 发现事项 | 7-9 |\n| `subagent` | 子代理调用 | 4-6 |\n\n### 压缩观察结构\n\n压缩后的观察记录格式：\n\n```xml\n\n decision\n 使用 SQLite 替代 Redis\n 缓存需求简单\n \n 数据量小于 10000 条\n 无需分布式缓存\n \n 团队决定简化架构...\n \n SQLite 嵌入式数据库\n 缓存架构简化\n \n \n src/db/cache.ts\n \n 8\n\n```\n\n资料来源：[src/prompts/compression.ts:1-40]()\n\n## 分页与过滤\n\n观察记录检索支持分页浏览和多种过滤条件。\n\n### 分页参数\n\n| 参数 | 说明 |\n|------|------|\n| `page` | 当前页码 (从 0 开始) |\n| `pageSize` | 每页条目数 |\n| `totalPages` | 总页数 |\n| `total` | 符合条件的总条目数 |\n\n### 类型过滤\n\n观察记录可按类型进行过滤：\n\n- `all` - 所有类型\n- `file_*` - 文件相关操作\n- `command` - 命令执行\n- `search` - 搜索操作\n- `web_fetch` - 网页获取\n- `conversation` - 对话记录\n- `error` - 错误信息\n- `decision` - 决策记录\n\n### 时间线视图\n\n时间线视图按时间倒序展示观察记录，每页显示固定数量的条目，适合回顾特定时间段的代理行为。\n\n## API 端点\n\nAgentMemory 提供以下检索相关的 HTTP API：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/search` | `POST` | 执行混合搜索 |\n| `/semantic` | `GET` | 获取语义记忆 |\n| `/observations` | `GET` | 获取观察记录 |\n| `/graph/neighbors` | `GET` | 获取关系邻接节点 |\n\n## 性能优化\n\n### 索引优化策略\n\n1. **增量索引**：新记忆追加而非重建全量索引\n2. **批量向量化**：多个文本批量转换减少模型调用开销\n3. **缓存机制**：热门查询结果缓存加速重复检索\n4. **分区策略**：按时间或类别分区缩小搜索范围\n\n### 查询优化\n\n- 使用近似最近邻算法减少计算量\n- 设置合理的 `topK` 和 `minScore` 阈值\n- 利用元数据过滤减少候选集大小\n- 图检索设置最大深度防止遍历爆炸\n\n## 最佳实践\n\n### 查询构造建议\n\n1. **使用精确术语**：领域特定术语可提高关键词检索准确性\n2. **组合多信号**：复杂查询建议使用混合搜索而非单一检索模式\n3. **合理设置阈值**：根据召回率和精确率需求调整 `minRelevanceScore`\n4. **利用关系扩展**：初始结果不足时可启用图关系扩展\n\n### 结果后处理\n\n1. **验证隐私合规性**：检索结果在展示前必须经过隐私过滤器\n2. **置信度排序**：高置信度结果优先展示给用户\n3. **去重处理**：合并来自不同来源的重复结果\n4. **上下文补充**：为每个结果补充相关背景信息\n\n## 相关模块\n\n- **记忆压缩**：[compression.ts](src/prompts/compression.ts) - 观察记录的压缩格式定义\n- **会话总结**：[summary.ts](src/prompts/summary.ts) - 会话摘要生成提示词\n- **反思提炼**：[reflect.ts](src/prompts/reflect.ts) - 记忆聚类的反思提示词\n- **Viewer 界面**：[index.html](src/viewer/index.html) - 检索结果的 Web 界面展示\n\n---\n\n\n\n## 记忆压缩与合并\n\n### 相关页面\n\n相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/compress-file.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/compress-file.ts)\n- [src/functions/replay.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/replay.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n
\n\n# 记忆压缩与合并\n\n## 概述\n\n记忆压缩与合并（Memory Compression and Consolidation）是 AgentMemory 系统中用于管理长期记忆的核心机制。该系统通过多层次的处理流程，将原始观察数据转化为结构化、可检索的高价值记忆单元，从而在保持上下文完整性的同时显著降低存储和检索开销。\n\n根据项目性能指标，该系统实现了 **92% 的 token 减少**，同时保持 **95.2% 的检索召回率（R@5）**，且无需外部数据库支持。资料来源：[website/app/opengraph-image.tsx:8-15]()\n\n## 核心设计理念\n\n### 压缩驱动的记忆生命周期\n\n```\ngraph TD\n A[原始观察 Raw Observations] --> B[压缩引擎 Compression Engine]\n B --> C[结构化观察 Compressed Observations]\n C --> D[会话摘要 Crystal]\n C --> E[经验教训 Lessons]\n C --> F[语义记忆 Semantic Memory]\n C --> G[程序记忆 Procedural Memory]\n \n style A fill:#ff6b6b\n style C fill:#4ecdc4\n style G fill:#ffe66d\n```\n\nAgentMemory 采用**压缩优先**的策略，将 AI 编码代理在会话中产生的每一次工具调用、文件操作、命令执行等原始观察数据，通过 LLM 驱动的压缩引擎提取关键信息，生成包含类型、标题、事实、叙述、概念、文件路径和重要性评分等结构化字段的观察记录。资料来源：[src/prompts/compression.ts:1-30]()\n\n### 合并驱动的记忆提炼\n\n合并机制将重复出现的模式识别并提炼为可复用的程序记忆。系统仅提取出现 2 次及以上的模式，确保提炼出的程序具有足够的实践验证。资料来源：[src/prompts/consolidation.ts:12-20]()\n\n## 压缩系统详解\n\n### 观察类型分类\n\n压缩引擎将所有观察归类为以下类型之一：\n\n| 类型 | 描述 | 典型场景 |\n|------|------|----------|\n| `file_read` | 文件读取操作 | 读取配置文件、源码 |\n| `file_write` | 文件创建操作 | 生成新文件、导出数据 |\n| `file_edit` | 文件修改操作 | 编辑代码、修改配置 |\n| `command_run` | 命令执行操作 | npm install、git commit |\n| `search` | 搜索操作 | 代码搜索、全局查找 |\n| `web_fetch` | 网页抓取 | 获取文档、API 响应 |\n| `conversation` | 对话交互 | 用户与代理的交流 |\n| `error` | 错误事件 | 异常捕获、构建失败 |\n| `decision` | 决策点 | 技术选型、架构决策 |\n| `discovery` | 发现事项 | 新工具、替代方案 |\n| `subagent` | 子代理调用 | 任务委托、并行处理 |\n| `notification` | 通知事件 | 构建完成、部署成功 |\n| `task` | 任务跟踪 | 待办事项、里程碑 |\n| `other` | 其他类型 | 不属于以上类别 |\n\n资料来源：[src/prompts/compression.ts:10-11]()\n\n### 重要性评分体系\n\n压缩输出包含 1-10 的重要性评分，用于后续存储策略决策：\n\n| 分数范围 | 含义 | 存储策略示例 |\n|----------|------|--------------|\n| 1-3 | 常规操作 | 快速遗忘、快速合并 |\n| 4-6 | 中等重要 | 标准保留周期 |\n| 7-9 | 重要决策 | 长期保留、高权重检索 |\n| 10 | 关键变更 | 永久保留、影响分析 |\n\n资料来源：[src/prompts/compression.ts:23-24]()\n\n### 压缩输出格式\n\n压缩后的观察数据采用 XML 格式输出，包含以下结构化字段：\n\n```xml\n\n file_edit\n 实现用户认证中间件\n 使用 JWT 方案替换会话认证\n \n 中间件位于 src/middleware/auth.ts\n 使用 RS256 算法进行签名验证\n 添加了 refreshToken 过期自动续期逻辑\n \n 为现有 API 添加了统一的 JWT 认证中间件，解决了多端登录状态同步问题。\n \n JWT middleware\n auth middleware\n \n \n src/middleware/auth.ts\n src/routes/api.ts\n \n 7\n\n```\n\n资料来源：[src/prompts/compression.ts:2-29]()\n\n### 文件压缩与验证\n\n`compress-file.ts` 模块提供了文件级压缩能力，包含以下验证机制：\n\n```typescript\nfunction validateCompression(original: string, compressed: string): string[] {\n // 验证标题层级完整性\n // 验证 URL 数量和内容一致性\n // 验证代码块数量和内容一致性\n}\n```\n\n验证规则确保压缩过程不会丢失关键信息：\n\n| 验证项 | 检查逻辑 |\n|--------|----------|\n| 标题层级 | 原始文件中的所有标题必须出现在压缩结果中 |\n| URL 集合 | URL 数量和内容必须完全一致 |\n| 代码块 | 代码块数量和内容必须保持不变 |\n\n资料来源：[src/functions/compress-file.ts:24-45]()\n\n## 合并系统详解\n\n### 合并类型\n\n```\ngraph LR\n A[压缩观察] --> B{合并触发条件}\n B -->|会话结束| C[会话摘要 Crystal]\n B -->|重复模式| D[程序记忆 Procedural]\n B -->|事实积累| E[语义记忆 Semantic]\n B -->|纠正记录| F[经验教训 Lessons]\n```\n\n#### 会话摘要（Crystal）\n\n会话摘要是会话级别的压缩产物，通过 `buildSummaryPrompt` 函数构建。该函数将多个压缩观察整合为单一的结构化摘要：\n\n```typescript\nexport function buildSummaryPrompt(observations: Array<{\n type: string\n title: string\n facts: string[]\n narrative: string\n files: string[]\n concepts: string[]\n}>): string\n```\n\n输出格式：\n\n```xml\n\n 会话标题\n 3-5句会话总结\n \n 关键决策1\n \n \n 修改的文件路径\n \n \n 关键概念\n \n\n```\n\n资料来源：[src/prompts/summary.ts:1-38]()\n\n#### 程序记忆（Procedural Memory）\n\n程序记忆通过 `buildProceduralExtractionPrompt` 函数提取，用于识别重复执行的模式：\n\n```typescript\nexport function buildProceduralExtractionPrompt(\n patterns: Array<{ content: string; frequency: number }>,\n): string\n```\n\n提取规则：\n- 仅提取出现 **2 次及以上** 的模式\n- 步骤描述需具体可执行\n- 触发条件需足够具体以支持自动匹配\n\n资料来源：[src/prompts/consolidation.ts:12-24]()\n\n### 经验教训系统\n\n`replay.ts` 模块包含经验教训的自动识别机制，通过正则表达式模式匹配：\n\n```typescript\nconst LESSON_PATTERNS: RegExp[] = [\n /\\b(always|never|don'?t|do not|make sure|remember to|note:|caveat:|warning:)\\b[^.\\n]{10,200}[.!\\n]/gi,\n /\\b(prefer|avoid)\\s[^.\\n]{10,200}[.!\\n]/gi,\n];\n```\n\n这些模式识别以下类型的经验：\n- **强制规则**：`always`、`never`、`make sure`\n- **否定规则**：`don't`、`do not`\n- **提醒标记**：`note:`、`caveat:`、`warning:`\n- **偏好指导**：`prefer`、`avoid`\n\n资料来源：[src/functions/replay.ts:45-48]()\n\n### Crystal 和 Lessons 的派生流程\n\n```typescript\nasync function deriveCrystalAndLessons(\n kv: StateKV,\n sessionId: string,\n project: string,\n rawObs: RawObservation[],\n compressed: CompressedObservation[],\n firstPrompt: string | undefined,\n): Promise\n```\n\n流程说明：\n\n1. **输入收集**：收集原始观察、压缩观察和首条提示\n2. **元数据提取**：从压缩观察中提取所有涉及的文件和工具\n3. **文本分离**：区分用户提示和助手响应\n4. **Crystal 生成**：创建包含时间戳的会话摘要\n5. **Lessons 提取**：应用模式匹配提取经验教训\n6. **关联存储**：将派生结果与原始会话关联\n\n资料来源：[src/functions/replay.ts:50-76]()\n\n## 数据流架构\n\n```\ngraph TD\n subgraph 输入层\n R[Raw Observations]\n F[首条提示 First Prompt]\n end\n \n subgraph 压缩层\n C[压缩引擎]\n V[验证模块]\n end\n \n subgraph 合并层\n X[Crystal 生成]\n L[Lessons 提取]\n P[Procedural 提取]\n end\n \n subgraph 存储层\n S[Sessions]\n K[Knowledge]\n end\n \n R --> C\n F --> X\n C --> V\n V -->|验证通过| X\n X --> S\n L --> K\n P --> K\n```\n\n## 隐私与安全\n\n系统在压缩和合并过程中实施严格的隐私保护措施。`privacy.ts` 模块定义了私密密文和敏感信息的识别模式：\n\n```typescript\nconst PRIVATE_TAG_RE = /[\\s\\S]*?<\\/private>/gi;\n\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n // ... 更多模式\n];\n```\n\n支持的敏感信息类型包括：\n- API 密钥和 Bearer Token\n- OpenAI、GitHub、GitLab 等平台密钥\n- AWS、Google Cloud 等云服务凭证\n- NPM、JWT 等通用认证令牌\n\n资料来源：[src/functions/privacy.ts:1-25]()\n\n## 配置与调优\n\n### 压缩提示词\n\n系统通过 `COMPRESSION_SYSTEM` 提示词指导 LLM 执行压缩任务，提示词包含：\n\n| 配置项 | 说明 |\n|--------|------|\n| 输出格式 | XML 结构化格式 |\n| 字段要求 | 标题最大 80 字符 |\n| 重要性规则 | 1-3 常规、4-6 编辑命令、7-9 架构决策、10 破坏性变更 |\n| 概念标签 | 应为可复用的搜索词 |\n| 隐私处理 | 剥离密钥、令牌、凭证 |\n\n### 合并策略\n\n| 策略 | 触发条件 | 输出 |\n|------|----------|------|\n| Crystal 生成 | 会话结束或手动触发 | 会话摘要 |\n| Procedural 提取 | 模式出现 2+ 次 | 可复用流程 |\n| Lessons 提取 | 模式匹配命中 | 经验教训 |\n| Semantic 合并 | 事实积累达到阈值 | 语义记忆 |\n\n## 最佳实践\n\n### 1. 观察记录的完整性\n\n在会话中保持工具调用的完整记录，以便压缩引擎能够提取足够的上下文信息。包含原始响应内容的观察能生成更高质量的 Crystal。\n\n### 2. 概念标签的精确性\n\n为压缩观察分配准确的 `concepts` 标签，这些标签直接影响后续检索的召回率。建议使用标准化的技术术语作为概念标签。\n\n### 3. 隐私标记的使用\n\n在原始观察中使用 `...` 标签包裹敏感内容，确保压缩流程自动剥离这些信息。\n\n### 4. Crystal 的定期复审\n\n虽然 Crystal 是自动生成的，但建议定期审查并手动强化重要的决策和发现，以提升系统学习效果。\n\n## 性能特性\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 减少 | 92% | 相比原始观察的压缩率 |\n| 检索召回率 | 95.2% (R@5) | Top-5 检索准确率 |\n| 外部依赖 | 0 | 无需外部数据库 |\n| 处理模式 | 实时 + 批量 | 支持即时压缩和后台合并 |\n\n资料来源：[website/app/opengraph-image.tsx:8-15]()\n\n## 相关模块\n\n| 模块路径 | 功能描述 |\n|----------|----------|\n| `src/prompts/compression.ts` | 压缩系统提示词定义 |\n| `src/prompts/consolidation.ts` | 合并系统提示词定义 |\n| `src/functions/compress-file.ts` | 文件级压缩与验证 |\n| `src/functions/replay.ts` | Crystal 和 Lessons 派生 |\n| `src/prompts/summary.ts` | 会话摘要提示词 |\n| `src/functions/privacy.ts` | 隐私保护与敏感信息识别 |\n\n---\n\n\n\n## MCP服务器与工具\n\n### 相关页面\n\n相关主题：[记忆操作](#memory-operations), [搜索与检索](#search-retrieval), [代理插件与集成](#agent-plugins)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx) — 展示MCP兼容代理列表及集成方式\n- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx) — 各代理的MCP配置示例\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md) — MCP包发布流程\n- [integrations/pi/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/pi/README.md) — PI扩展与MCP的关系说明\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx) — 安装入口及npm包信息\n
\n\n# MCP服务器与工具\n\n## 概述\n\nMCP（Model Context Protocol）服务器是 AgentMemory 的核心组件之一，它为 AI 代理提供标准化的记忆工具接口。通过 MCP 协议，AgentMemory 能够与各种 AI 代理客户端（如 Claude Desktop、Cursor、Windsurf、VS Code 等）实现无缝集成，使代理能够在对话过程中持久化存储和检索记忆。\n\nAgentMemory 的 MCP 实现包含两个层面：一是作为 MCP 服务器运行，接受代理的工具调用请求；二是通过 MCP 协议与支持该协议的各种代理客户端建立连接。资料来源：[website/components/Agents.tsx:17-21]()\n\n> \"SIX FIRST-PARTY. REST MCP-NATIVE. NATIVE PLUGINS FOR CLAUDE CODE, CODEX CLI, OPENCLAW, HERMES, PI, AND OPENHUMAN. EVERY OTHER MCP CLIENT GETS IT FOR FREE.\"\n\n## 架构设计\n\n### 协议层结构\n\nAgentMemory 的 MCP 实现采用分层架构设计：\n\n```mermaid\ngraph TD\n A[MCP客户端
Claude Desktop / Cursor / Cline等] --> B[MCP协议层]\n B --> C[AgentMemory MCP服务器]\n C --> D[REST API层]\n D --> E[记忆存储引擎]\n E --> F[SQLite/文件存储]\n \n G[原生插件
Claude Code / Codex CLI / Hermes等] --> H[直接API调用]\n H --> D\n```\n\n### MCP 服务器角色\n\nMCP 服务器在 AgentMemory 架构中承担以下职责：\n\n| 职责 | 说明 |\n|------|------|\n| 工具注册 | 将记忆操作封装为 MCP 标准工具 |\n| 请求路由 | 解析 MCP 请求并分发到对应处理函数 |\n| 响应格式化 | 将记忆数据转换为 MCP 协议格式 |\n| 连接管理 | 维护与多个客户端的会话状态 |\n\n资料来源：[website/components/Agents.tsx:22-35]()\n\n## 支持的 MCP 客户端\n\n### 一线原生插件（内置支持）\n\nAgentMemory 为以下代理提供原生插件支持：\n\n- **Claude Code** — Anthropic 官方 CLI 代理\n- **Codex CLI** — OpenAI 官方代理\n- **OpenClaw** — 开源代理\n- **Hermes** — 开源代理框架\n- **PI** — 代理框架\n- **OpenHuman** — 开源项目\n\n```mermaid\ngraph LR\n A[Claude Code] --> B[原生插件]\n A2[Codex CLI] --> B\n A3[OpenClaw] --> B\n A4[Hermes] --> B\n A5[PI] --> B\n A6[OpenHuman] --> B\n \n B --> C[agentmemory connect命令
自动配置所有插件]\n```\n\n资料来源：[website/components/Agents.tsx:17-21]()\n\n### MCP 协议客户端（开箱即用）\n\n以下客户端通过标准 MCP JSON 配置即可使用 AgentMemory：\n\n| 客户端 | 配置文件 | 特殊说明 |\n|--------|----------|----------|\n| Claude Desktop | `claude_desktop_config.json` | 标准 mcpServers 格式 |\n| Cursor | deeplink 一键连接 | 支持 mcpServers |\n| Cline | `~/.cursor/mcp.json` | 标准格式 |\n| Roo Code | `~/. Roo Code/mcp.json` | 标准格式 |\n| Windsurf | `~/.codeium/windsurf/mcp.json` | 标准格式 |\n| Gemini CLI | `~/.gemini/mcp.json` | 标准格式 |\n\n资料来源：[website/components/AgentInstall.tsx:8-25]()\n\n## 通用 MCP JSON 配置\n\n### 标准配置格式\n\n大多数 MCP 客户端使用以下配置格式：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### OpenCode 配置\n\nOpenCode 使用略有不同的配置格式：\n\n```json\n{\n \"mcp\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### VS Code 配置\n\nVS Code 的 MCP 配置文件位于 `.vscode/mcp.json`，使用 `servers` 键而非 `mcpServers`：\n\n```json\n{\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx:26-50]()\n\n## NPM 包分发\n\n### 包信息\n\nMCP 服务器作为独立的 npm 包分发：\n\n| 属性 | 值 |\n|------|-----|\n| 包名 | `@agentmemory/mcp` |\n| 入口文件 | `packages/mcp/bin.mjs` |\n| 用途 | MCP 协议服务器实现 |\n\n### 发布流程\n\nMCP 包的发布集成到 AgentMemory 的标准发布流程中：\n\n1. 更新 `packages/mcp/package.json` 中的版本号\n2. 同步主包的 `~x.y.z` 版本依赖\n3. GitHub Release 触发自动发布\n\n> \"The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance.\"\n\n资料来源：[CONTRIBUTING.md:58-64]()\n\n## MCP 工具接口\n\n### 核心工具列表\n\n通过 MCP 协议暴露的核心记忆工具：\n\n| 工具名 | 功能描述 |\n|--------|----------|\n| `memory_remember` | 存储新的记忆条目 |\n| `memory_recall` | 检索相关记忆 |\n| `memory_search` | 基于关键词搜索记忆 |\n| `memory_consolidate` | 合并和压缩记忆 |\n| `memory_action_create` | 创建待办事项 |\n\n资料来源：[src/viewer/index.html:1-10]()\n\n### 创建 Action 的 MCP 调用示例\n\n```javascript\n// MCP 工具调用格式\nmemory_action_create({ \n title: \"ship v1\", \n description: \"完成v1版本发布\",\n priority: \"high\" \n})\n```\n\n也可以通过 REST API 调用：\n\n```bash\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n资料来源：[src/viewer/index.html:1-10]()\n\n## 与 PI 扩展的关系\n\nPI 代理使用独特的扩展 API 而非 MCP 协议：\n\n> \"This extension uses pi's extension API, not MCP, so it can hook directly into the agent lifecycle.\"\n\n这意味着 PI 代理可以直接访问 AgentMemory 的内部 API，绕过 MCP 协议层，获得更深入的生命周期集成能力。\n\n**共享架构优势**：尽管使用不同协议，一个本地 AgentMemory 服务器可以被 PI、PI2、Hermes、OpenClaw、Claude Code、Codex CLI 和 Gemini CLI 共享。\n\n资料来源：[integrations/pi/README.md:1-10]()\n\n## 快速开始\n\n### 安装 MCP 服务器\n\n```bash\n# 通过 npx 直接运行\nnpx -y @agentmemory/mcp\n\n# 或全局安装\nnpm install -g @agentmemory/mcp\n```\n\n### 配置客户端\n\n1. 打开目标代理的配置界面\n2. 找到 MCP 服务器配置区域\n3. 添加 AgentMemory 服务器配置\n4. 重启代理以加载新配置\n\n资料来源：[website/components/Install.tsx:1-45]()\n\n## 配置示例汇总\n\n### Claude Desktop（macOS）\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### Claude Desktop（Windows）\n\n`%APPDATA%\\Claude\\claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### Codex CLI（TOML 格式）\n\n`~/.codex/config.toml`:\n\n```toml\n[server.agentmemory]\ncommand = \"npx\"\nargs = [\"-y\", \"@agentmemory/mcp\"]\n```\n\n### Hermes（YAML 格式）\n\n`integrations/hermes/plugin.yaml`:\n\n```yaml\n# AgentMemory 插件配置\n```\n\n### OpenClaw（YAML 格式）\n\n`integrations/openclaw/plugin.yaml`:\n\n```yaml\n# AgentMemory 插件配置\n```\n\n资料来源：[website/components/AgentInstall.tsx:51-70]()\n\n## 注意事项\n\n1. **数据本地性**：所有记忆数据默认存储在本地机器上，不会上传到第三方服务。\n\n2. **共享服务器**：一个 AgentMemory 服务器实例可以同时为多个代理提供服务。\n\n3. **健康检查**：使用 `/agentmemory-status` 端点验证服务器状态，应返回 `agentmemory healthy`。\n\n4. **协议选择**：\n - 原生插件 → 直接 API 调用\n - MCP 客户端 → MCP 协议层\n - PI 代理 → 扩展 API（非 MCP）\n\n5. **版本同步**：确保 MCP 包版本与主包版本保持一致以获得最佳兼容性。\n\n资料来源：[integrations/pi/README.md:1-5]()\n\n## 相关资源\n\n- [安装指南](../安装指南.md)\n- [记忆系统架构](./记忆系统架构.md)\n- [集成目录](https://github.com/rohitg00/agentmemory/tree/main/integrations)\n- [npm 包页面](https://www.npmjs.com/package/@agentmemory/mcp)\n\n---\n\n\n\n## 代理插件与集成\n\n### 相关页面\n\n相关主题：[MCP服务器与工具](#mcp-server), [快速开始](#quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)\n- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx)\n- [integrations/openclaw/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/openclaw/README.md)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 代理插件与集成\n\n## 概述\n\nAgentMemory 项目提供了一套完整的代理（Agent）插件与集成系统，支持六种第一方原生插件，并通过 MCP（Model Context Protocol）协议实现对其他第三方代理的广泛兼容。核心通过 `agentmemory connect ` 命令实现自动连接配置，同时支持 MCP 桥接方式和直接插件方式两种深度集成模式。\n\n项目采用统一的内存后端服务（默认运行于 `http://localhost:3111`），所有集成的代理共享相同的记忆存储、检索和检索增强生成（RAG）能力，实现跨代理的上下文一致性。\n\n## 支持的代理类型\n\n### 第一方原生插件\n\nAgentMemory 为以下六个第一方代理提供原生深度集成：\n\n| 代理名称 | 插件类型 | 连接方式 | 特点 |\n|---------|---------|---------|------|\n| Claude Code | 原生插件 | `agentmemory connect claude-code` | 完整记忆功能，Hook 深度集成 |\n| Codex CLI | 原生插件 | `agentmemory connect codex` | 完整记忆功能，Hook 深度集成 |\n| OpenClaw | 原生插件/直接插件 | `agentmemory connect openclaw` | 支持直接内存插件模式 |\n| Hermes | 原生插件 | `agentmemory connect hermes` | 完整记忆功能 |\n| PI | 原生插件 | `agentmemory connect pi` | 完整记忆功能 |\n| OpenHuman | 原生插件 | `agentmemory connect openhuman` | 完整记忆功能 |\n\n资料来源：[website/components/Agents.tsx:19-21]()\n\n### MCP 协议兼容代理\n\n除第一方插件外，AgentMemory 通过 MCP 协议实现对所有 MCP 兼容客户端的零成本接入：\n\n| 客户端 | 配置方式 | 连接难度 |\n|-------|---------|---------|\n| Claude Desktop | DeepLink 一键安装 | ⭐ |\n| Cursor | DeepLink 一键安装 | ⭐ |\n| VS Code (MCP) | mcp.json 配置文件 | ⭐ |\n| Cline | MCP JSON 配置 | ⭐⭐ |\n| Roo Code | MCP JSON 配置 | ⭐⭐ |\n| Windsurf | MCP JSON 配置 | ⭐⭐ |\n| Gemini CLI | MCP JSON 配置 | ⭐⭐ |\n| OpenCode | mcp.json (特殊格式) | ⭐⭐ |\n\n资料来源：[website/components/AgentInstall.tsx:1-150]()\n\n## 集成架构\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph \"MCP 客户端层\"\n A[Claude Code] --> B[MCP Bridge]\n C[Cursor] --> B\n D[VS Code] --> B\n E[其他 MCP 客户端] --> B\n end\n \n subgraph \"第一方插件层\"\n F[Claude Code 插件]\n G[Codex CLI 插件]\n H[OpenClaw 插件]\n I[Hermes 插件]\n J[PI 插件]\n K[OpenHuman 插件]\n end\n \n subgraph \"集成中间件\"\n L[MCP Bridge]\n M[直接插件接口]\n end\n \n subgraph \"AgentMemory 核心服务\"\n N[API Server :3111]\n O[SQLite 存储引擎]\n P[向量索引]\n Q[记忆整合引擎]\n end\n \n B --> L\n F --> M\n G --> M\n H --> M\n I --> M\n J --> M\n K --> M\n \n L --> N\n M --> N\n \n N --> O\n N --> P\n Q --> O\n```\n\n### MCP 桥接集成模式\n\nMCP 桥接模式适用于所有标准 MCP 客户端，通过 MCP JSON 配置实现连接：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n通用 MCP JSON 配置兼容以下客户端：\n- Claude Desktop\n- Cursor\n- Cline\n- Roo Code\n- Windsurf\n- Gemini CLI\n\n资料来源：[website/components/AgentInstall.tsx:35-40]()\n\n### 直接插件集成模式\n\n对于支持插件系统的代理（如 OpenClaw），可采用直接插件模式实现更深度的集成：\n\n```json\n{\n \"plugins\": {\n \"slots\": {\n \"memory\": \"agentmemory\"\n },\n \"entries\": {\n \"agentmemory\": {\n \"enabled\": true,\n \"config\": {\n \"base_url\": \"http://localhost:3111\",\n \"token_budget\": 2000,\n \"min_confidence\": 0.5,\n \"fallback_on_error\": true,\n \"timeout_ms\": 5000\n }\n }\n }\n }\n}\n```\n\n| 配置参数 | 类型 | 默认值 | 说明 |\n|---------|------|-------|------|\n| base_url | string | http://localhost:3111 | AgentMemory 服务地址 |\n| token_budget | number | 2000 | 单次检索的最大 Token 预算 |\n| min_confidence | number | 0.5 | 最小置信度阈值 |\n| fallback_on_error | boolean | true | 服务不可用时的降级策略 |\n| timeout_ms | number | 5000 | 请求超时时间（毫秒） |\n\n资料来源：[integrations/openclaw/README.md:25-45]()\n\n## 插件机制\n\n### 技能系统（Skills）\n\nAgentMemory 的插件系统基于技能（Skills）模块化组织，每个技能封装特定功能：\n\n| 技能名称 | 功能描述 | 触发方式 |\n|---------|---------|---------|\n| recall | 长期记忆检索 | 自动 RAG / 手动调用 |\n| remember | 记忆编码与存储 | 会话结束自动触发 |\n| forget | 记忆遗忘与衰减 | 手动调用 / 自动清理 |\n| session-history | 会话历史管理 | 跨会话上下文 |\n\n资料来源：[integrations/openclaw/README.md:8-12]()\n\n### 钩子系统（Hooks）\n\nAgentMemory 通过钩子（Hooks）机制实现会话生命周期的深度集成：\n\n```mermaid\ngraph LR\n A[会话开始] --> B[before_agent_start Hook]\n B --> C[记忆检索]\n C --> D[Agent 执行]\n D --> E[Agent 结束]\n E --> F[agent_end Hook]\n F --> G[记忆整合]\n G --> H[长期存储]\n```\n\n| 钩子名称 | 触发时机 | 功能 |\n|---------|---------|------|\n| before_agent_start | Agent 启动前 | 检索相关长期记忆，构建上下文 |\n| agent_end | Agent 完成后 | 捕获对话轮次，执行记忆整合 |\n\n直接插件模式通过 `api.registerMemoryCapability({ promptBuilder })` 注册记忆能力，使代理系统能够识别 AgentMemory 作为活动内存插件。\n\n资料来源：[integrations/openclaw/README.md:47-54]()\n\n## 连接命令\n\n### 快速连接\n\n使用 `agentmemory connect` 命令可自动配置与目标代理的连接：\n\n```bash\n# 连接 Claude Code\nagentmemory connect claude-code\n\n# 连接 Codex CLI\nagentmemory connect codex\n\n# 连接 OpenClaw\nagentmemory connect openclaw\n\n# 连接 Hermes\nagentmemory connect hermes\n```\n\n该命令自动检测代理环境，生成对应的配置文件并完成必要的初始化步骤。\n\n资料来源：[website/components/Agents.tsx:19-21]()\n\n## 记忆运行时\n\n### 记忆运行时后端\n\nAgentMemory 提供统一的记忆运行时后端，所有集成的代理共享相同的记忆存储：\n\n- **语义记忆**：结构化的事实知识，支持置信度评分\n- **程序记忆**：可复用的操作步骤和流程\n- **关系记忆**：实体间的关联网络\n- **观察记录**：原始会话数据，包含工具调用和文件操作\n- **水晶（Crystals）**：会话压缩摘要，3 行长度的工作总结\n- **教训（Lessons）**：模式纠正记录，带置信度衰减机制\n- **行动（Actions）**：待跟进任务，支持状态流转（pending → active → done/blocked）\n\n资料来源：[src/viewer/index.html:150-200]()\n\n### 记忆检索配置\n\n| 参数 | 说明 | 影响 |\n|-----|------|-----|\n| token_budget | 检索结果的最大 Token 数 | 控制上下文长度 |\n| min_confidence | 检索结果的最小置信度 | 过滤低质量记忆 |\n| token_limit | 向量检索的 Token 上限 | 控制单次检索范围 |\n\n### 记忆生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> RawObservation: 会话进行中\n RawObservation --> SemanticFact: 整合引擎处理\n RawObservation --> Procedure: 重复模式提取\n RawObservation --> Crystal: 会话结束压缩\n SemanticFact --> ConfidenceDecay: 长期未使用\n Procedure --> ConfidenceDecay: 长期未使用\n Crystal --> [*]: 旧水晶被清理\n ConfidenceDecay --> [*]: 置信度归零删除\n```\n\n## 隐私与安全\n\n### 敏感信息处理\n\nAgentMemory 在存储记忆前自动扫描并过滤敏感信息：\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n];\n```\n\n同时支持 `` 标签自动过滤：\n\n```xml\n\n这里的内容不会被存储\n\n```\n\n资料来源：[src/functions/privacy.ts:1-25]()\n\n## 扩展开发\n\n### 添加新的代理插件\n\n根据 CONTRIBUTING.md 的规范，添加新代理插件需要：\n\n1. **定义钩子类型**：在 `src/types.ts` 的 HookType 联合类型中添加新类型\n2. **实现钩子处理器**：在 `src/hooks/.ts` 中编写处理器逻辑\n3. **编写测试用例**：使用 Vitest 编写单元测试，验证观察记录正确写入\n\n```typescript\n// 1. 添加 HookType\ntype HookType = 'before_agent_start' | 'agent_end' | 'your_new_hook';\n\n// 2. 实现处理器 src/hooks/your_new_hook.ts\nexport async function handleYourNewHook(params: HookParams): Promise {\n // 处理逻辑\n}\n\n// 3. 编写测试\ndescribe('your_new_hook', () => {\n it('writes observation on trigger', async () => {\n // 测试断言\n });\n});\n```\n\n### 版本发布\n\n插件系统与主版本同步发布，每次版本更新需要同步修改 8 个文件：\n\n| 文件 | 修改内容 |\n|-----|---------|\n| package.json | 版本号更新 |\n| package-lock.json | 锁文件更新 |\n| plugin/.claude-plugin/plugin.json | 插件元数据 |\n| packages/mcp/package.json | MCP 包版本 |\n| src/version.ts | 版本常量定义 |\n| src/types.ts | 导出数据类型 |\n| src/functions/export-import.ts | 支持版本列表 |\n| test/export-import.test.ts | 版本断言测试 |\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n## 配置参考\n\n### Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### OpenCode 配置\n\n```json\n{\n \"mcp\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### VS Code 配置\n\n需要在 `.vscode/mcp.json` 中使用 `servers` 键而非 `mcpServers`：\n\n```json\n{\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx:60-90]()\n\n## 总结\n\nAgentMemory 的代理插件与集成系统通过双轨制设计实现了广泛的兼容性：\n\n- **MCP 桥接模式**：一行配置即可连接任何 MCP 兼容客户端\n- **直接插件模式**：为支持的代理提供更深的集成能力\n\n所有集成共享同一个记忆后端服务，实现跨代理的上下文连续性，同时通过隐私保护机制确保敏感信息的安全。插件系统采用模块化设计，便于扩展新的代理支持和自定义钩子逻辑。\n\n---\n\n\n\n## 部署与运维\n\n### 相关页面\n\n相关主题：[快速开始](#quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)\n- [deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)\n- [deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)\n- [deploy/render/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/render/Dockerfile)\n- [deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)\n- [deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)\n- [src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n
\n\n# 部署与运维\n\n## 概述\n\nAgentMemory 是一个完整的记忆运行时系统，支持多种部署方式以满足不同场景的需求。项目提供了 Docker 容器化部署方案，覆盖本地开发、云平台托管和自托管等多种部署环境。\n\n核心服务默认运行在 **localhost:3111** 端口，提供 HTTP REST API 和 Web 可视化界面。部署架构采用前后端分离设计，后端服务处理记忆存储和检索，前端通过静态资源提供服务。\n\n## 部署架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[客户端] -->|HTTP API| B[AgentMemory 服务 :3111]\n B --> C[SQLite 数据库]\n B --> D[语义记忆存储]\n B --> E[程序记忆存储]\n B --> F[时序图谱存储]\n \n G[Web 查看器] --> B\n \n H[记忆动作系统] --> B\n \n I[MCP 协议接口] --> B\n```\n\n| 组件 | 说明 | 默认端口 |\n|------|------|----------|\n| REST API | 记忆 CRUD 操作接口 | 3111 |\n| Web 查看器 | 可视化记忆面板 | 3111 |\n| SQLite 存储 | 本地持久化数据库 | - |\n| MCP 服务 | 模型上下文协议支持 | - |\n\n### 服务端口配置\n\n服务默认监听 **3111** 端口，Web 查看器通过 `src/viewer/server.ts` 启动静态文件服务器。资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n\n```typescript\n// 端口配置通过环境变量或默认值设置\nconst PORT = process.env.PORT || 3111;\n```\n\n## Docker 部署\n\n### 多平台 Dockerfile\n\n项目为不同部署平台提供了优化的 Dockerfile 配置：\n\n| 平台 | Dockerfile 路径 | 特点 |\n|------|-----------------|------|\n| Fly.io | deploy/fly/Dockerfile | 轻量级多阶段构建 |\n| Railway | deploy/railway/Dockerfile | 标准 Node.js 镜像 |\n| Render | deploy/render/Dockerfile | 兼容 Render 平台 |\n| Coolify | deploy/coolify/Dockerfile | 自托管优化 |\n\n#### Fly.io Dockerfile\n\n```dockerfile\n# deploy/fly/Dockerfile\nFROM node:20-alpine\n\nWORKDIR /app\n\n# 复制 package 文件\nCOPY package*.json ./\n\n# 安装依赖\nRUN npm ci --only=production\n\n# 复制应用代码\nCOPY dist ./dist\nCOPY src/viewer ./src/viewer\n\n# 暴露端口\nEXPOSE 3111\n\n# 健康检查\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n CMD wget --no-verbose --tries=1 --spider http://localhost:3111/health || exit 1\n\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)\n\n#### Railway Dockerfile\n\n```dockerfile\n# deploy/railway/Dockerfile\nFROM node:20-slim\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci\n\nCOPY . .\nRUN npm run build\n\nEXPOSE 3111\n\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)\n\n#### Coolify Dockerfile\n\n```dockerfile\n# deploy/coolify/Dockerfile\nFROM node:20-alpine\n\nRUN apk add --no-cache dumb-init\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci --only=production && npm cache clean --force\n\nCOPY dist ./dist\nCOPY src/viewer ./src/viewer\n\nEXPOSE 3111\n\nUSER node\n\nENTRYPOINT [\"dumb-init\", \"--\"]\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)\n\n### 镜像构建\n\n```bash\n# 构建本地镜像\ndocker build -t agentmemory:latest .\n\n# 带平台指定构建\ndocker buildx build --platform linux/amd64,linux/arm64 -t agentmemory:latest .\n```\n\n## Docker Compose 部署\n\n### 本地开发环境\n\n项目根目录的 `docker-compose.yml` 提供了开箱即用的本地部署配置：\n\n```yaml\n# docker-compose.yml\nversion: '3.8'\n\nservices:\n agentmemory:\n build:\n context: .\n dockerfile: Dockerfile\n ports:\n - \"3111:3111\"\n environment:\n - NODE_ENV=production\n - PORT=3111\n - DATA_DIR=/data\n volumes:\n - agentmemory-data:/data\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"wget\", \"--no-verbose\", \"--tries=1\", \"--spider\", \"http://localhost:3111/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 10s\n\nvolumes:\n agentmemory-data:\n driver: local\n```\n\n资料来源：[docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)\n\n### Fly.io 部署配置\n\n```yaml\n# deploy/fly/docker-compose.yml\nservices:\n agentmemory:\n build:\n context: ../..\n dockerfile: deploy/fly/Dockerfile\n ports:\n - -3111:3111\n env_file:\n - .env\n volumes:\n - agentmemory-data:/data\n restart: always\n\nvolumes:\n agentmemory-data:\n name: agentmemory_data\n```\n\n资料来源：[deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)\n\n### 启动命令\n\n```bash\n# 启动服务\ndocker-compose up -d\n\n# 查看日志\ndocker-compose logs -f agentmemory\n\n# 停止服务\ndocker-compose down\n\n# 重建并启动\ndocker-compose up -d --build\n```\n\n## 环境变量配置\n\n### 核心配置项\n\n| 环境变量 | 默认值 | 说明 |\n|----------|--------|------|\n| `PORT` | 3111 | 服务监听端口 |\n| `NODE_ENV` | production | 运行环境 |\n| `DATA_DIR` | ./data | 数据存储目录 |\n| `LOG_LEVEL` | info | 日志级别 |\n| `MAX_MEMORY_SIZE` | - | 最大记忆存储大小 |\n| `DB_PATH` | - | SQLite 数据库路径 |\n\n### 安全配置\n\n```bash\n# 设置管理员令牌\nexport ADMIN_TOKEN=your-secure-token\n\n# 配置 CORS 策略\nexport CORS_ORIGINS=https://your-domain.com\n\n# 启用 SSL\nexport HTTPS_ENABLED=true\nexport SSL_CERT_PATH=/path/to/cert.pem\nexport SSL_KEY_PATH=/path/to/key.pem\n```\n\n## Web 查看器运维\n\n### 静态资源服务\n\nWeb 查看器通过 `src/viewer/server.ts` 提供可视化界面：\n\n```mermaid\ngraph LR\n A[浏览器] -->|HTTP| B[查看器服务器]\n B --> C[index.html]\n B --> D[CSS/JS 资源]\n B --> E[API 数据]\n```\n\n资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n\n### 查看器功能\n\nWeb 界面 (`src/viewer/index.html`) 提供以下运维功能：\n\n- **记忆概览**：查看语义记忆、程序记忆、关系图谱\n- **特征标志**：管理功能开关和实验性功能\n- **行动追踪**：监控待处理任务和决策\n- **会话历史**：查看压缩后的观察记录\n\n资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n### 界面渲染逻辑\n\n```javascript\n// 查看器渲染核心逻辑\nfunction renderFlags(flags) {\n const pills = flags.map(b => \n `${b.icon} ${b.title}`\n ).join('');\n \n const html = `\n \n `;\n \n host.innerHTML = html;\n}\n```\n\n## 健康检查与监控\n\n### 健康检查端点\n\n```bash\n# 检查服务健康状态\ncurl http://localhost:3111/health\n\n# 预期响应\n{\n \"status\": \"ok\",\n \"timestamp\": \"2026-01-01T00:00:00.000Z\",\n \"uptime\": 3600\n}\n```\n\n### Docker 健康检查配置\n\n```yaml\nhealthcheck:\n test: [\"CMD\", \"wget\", \"--no-verbose\", \"--tries=1\", \"--spider\", \"http://localhost:3111/health\"]\n interval: 30s # 检查间隔\n timeout: 10s # 超时时间\n retries: 3 # 重试次数\n start_period: 10s # 启动等待时间\n```\n\n### 容器状态监控\n\n```bash\n# 查看容器健康状态\ndocker inspect --format='{{.State.Health.Status}}' agentmemory-agentmemory-1\n\n# 查看资源使用\ndocker stats agentmemory-agentmemory-1\n\n# 查看详细日志\ndocker logs agentmemory-agentmemory-1 --tail 100 --details\n```\n\n## 平台特定部署\n\n### Fly.io 部署\n\n```bash\n# 安装 Fly CLI\ncurl -L https://fly.io/install.sh | sh\n\n# 登录\nfly auth login\n\n# 部署应用\nfly deploy --config deploy/fly/docker-compose.yml\n\n# 查看部署状态\nfly status\n\n# 打开应用\nfly open\n```\n\n### Railway 部署\n\n1. 连接 GitHub 仓库\n2. 选择 `deploy/railway/Dockerfile`\n3. 配置环境变量\n4. Railway 自动构建和部署\n\n### Render 部署\n\n1. 创建新的 Web Service\n2. 连接 GitHub 仓库\n3. 设置构建命令：`npm run build`\n4. 设置启动命令：`node dist/index.js`\n5. 配置环境变量\n\n### Coolify 自托管\n\n1. 添加新项目\n2. 配置 Dockerfiles 路径：`deploy/coolify/Dockerfile`\n3. 设置端口映射：`3111:3111`\n4. 配置持久化存储卷\n\n## 数据持久化\n\n### 存储卷配置\n\n```yaml\nvolumes:\n agentmemory-data:\n driver: local\n driver_opts:\n type: none\n o: bind\n device: /path/to/host/data\n```\n\n### 备份策略\n\n```bash\n# 备份数据库\ndocker cp agentmemory:/data/memory.db ./backup-$(date +%Y%m%d).db\n\n# 备份整个数据目录\ntar -czf agentmemory-data-$(date +%Y%m%d).tar.gz ./data/\n\n# 恢复数据\ndocker cp ./backup.db agentmemory:/data/memory.db\n```\n\n## 日志管理\n\n### 查看日志\n\n```bash\n# 实时日志\ndocker-compose logs -f\n\n# 错误日志\ndocker-compose logs --since 1h --filter \"level=error\"\n\n# 结构化日志输出\ndocker logs -f agentmemory --tail 200 --timestamps\n```\n\n### 日志级别\n\n| 级别 | 说明 | 使用场景 |\n|------|------|----------|\n| error | 错误信息 | 故障排查 |\n| warn | 警告信息 | 性能问题 |\n| info | 一般信息 | 正常运行监控 |\n| debug | 调试信息 | 开发调试 |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 服务无法启动 | 端口被占用 | 修改 PORT 环境变量 |\n| 数据库连接失败 | 权限问题 | 检查卷挂载权限 |\n| 健康检查失败 | 网络问题 | 检查容器网络配置 |\n| 前端加载失败 | 静态资源缺失 | 检查构建产物 |\n\n### 调试命令\n\n```bash\n# 进入容器调试\ndocker exec -it agentmemory sh\n\n# 检查网络连通性\ndocker exec agentmemory wget -O- http://localhost:3111/health\n\n# 检查文件权限\ndocker exec agentmemory ls -la /data\n\n# 验证配置\ndocker exec agentmemory env | grep -E \"PORT|DATA_DIR\"\n```\n\n## 安全建议\n\n### 生产环境配置\n\n1. **启用 TLS/SSL**：使用反向代理或配置 HTTPS\n2. **限制 CORS**：设置 `CORS_ORIGINS` 为可信域名\n3. **配置认证**：启用 API 令牌认证\n4. **定期备份**：配置自动化备份策略\n5. **监控告警**：设置资源使用和错误率告警\n\n### 网络安全\n\n```bash\n# 使用 Docker 网络隔离\ndocker network create --driver bridge agentmemory-net\n\n# 限制容器能力\ndocker run --cap-drop=ALL --security-opt=no-new-privileges \\\n agentmemory:latest\n```\n\n## 扩展运维\n\n### 水平扩展\n\n```yaml\nservices:\n agentmemory:\n deploy:\n replicas: 2\n # 需要外部负载均衡器配合\n```\n\n### 资源限制\n\n```yaml\ndeploy:\n resources:\n limits:\n cpus: '1'\n memory: 1G\n reservations:\n cpus: '0.5'\n memory: 512M\n```\n\n## 总结\n\nAgentMemory 提供灵活的部署方案，支持从本地开发到云端生产环境的全场景覆盖。通过 Docker 容器化和标准化的配置文件，用户可以在 Fly.io、Railway、Render、Coolify 等主流平台快速部署服务。内置的健康检查、日志管理和 Web 查看器功能为运维工作提供了便捷的监控和调试手段。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rohitg00/agentmemory\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Viewer tab bar is vertically clipped in the web UI。\n\n## 1. 安装坑 · 来源证据：Viewer tab bar is vertically clipped in the web UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：npm installs anthropic dependencies\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.9.14 — CLI installer first + agentmemory stop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.9.15 — DevEx overhaul\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.9.8 — local fallback tools/list returns 7 not 4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor\n\n## 8. 配置坑 · 来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\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:1166408297 | https://github.com/rohitg00/agentmemory | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c1b3cc10454e4fd09921e3748ad82305 | https://github.com/rohitg00/agentmemory/issues/433 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Support Ollama as a native LLM provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Ollama as a native LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c87cfb919d5049289e2beec7660ffcf0 | https://github.com/rohitg00/agentmemory/issues/232 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1bade4c29c91471284081588c913e17d | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.10 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_690933973fcf4eb5b034ab92a3c00d23 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.11 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dd621c8f5654b1f882800d15964ad46 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.9.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.13\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0eb3c158e9474ea95f58d6b01d4d0b | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf5c1b128a5e4e30bc8788b1fe501ce5 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.9.9 — pinned slot injection + MiniMax env loader\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.9 — pinned slot injection + MiniMax env loader\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e243f84c706f4fcc9bfe7f73f8467ffc | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.9 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:1166408297 | https://github.com/rohitg00/agentmemory | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | release_recency=unknown\n\n\n", "markdown_key": "agentmemory", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1166408297", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/rohitg00/agentmemory" }, { "evidence_id": "art_e89e68b6e7444d58b9b29ab5226a8757", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/rohitg00/agentmemory#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "agentmemory 说明书", "toc": [ "https://github.com/rohitg00/agentmemory 项目说明书", "目录", "项目介绍", "概述", "核心架构", "主要功能模块", "支持的代理客户端", "安装与部署", "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": "3a3f866ab52b3fb21b125bd7cf3a105475bc3f67", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "docker-compose.yml", "examples/python/quickstart.py", "examples/python/observe_and_recall.py", "examples/python/README.md", "packages/mcp/package.json", "packages/mcp/README.md", "src/logger.ts", "src/xenova.d.ts", "src/version.ts", "src/index.ts", "src/config.ts", "src/types.ts", "src/auth.ts", "src/cli.ts", "src/cli/preferences.ts", "src/cli/doctor-diagnostics.ts", "src/cli/onboarding.ts", "src/cli/remove-plan.ts", "src/cli/splash.ts", "src/mcp/in-memory-kv.ts", "src/mcp/rest-proxy.ts", "src/mcp/server.ts", "src/mcp/tools-registry.ts", "src/mcp/standalone.ts", "src/mcp/transport.ts", "src/replay/timeline.ts", "src/replay/jsonl-parser.ts", "src/providers/openrouter.ts", "src/providers/anthropic.ts", "src/providers/openai.ts", "src/providers/agent-sdk.ts", "src/providers/minimax.ts", "src/providers/index.ts", "src/providers/resilient.ts", "src/providers/noop.ts", "src/providers/circuit-breaker.ts", "src/providers/fallback-chain.ts", "src/hooks/pre-compact.ts" ], "repo_inspection_verified": true, "review_reasons": [], "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": "# @agentmemory/agentmemory - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @agentmemory/agentmemory 编译的 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_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`plugin/skills/forget/SKILL.md`, `plugin/skills/recall/SKILL.md`, `plugin/skills/remember/SKILL.md`, `plugin/skills/session-history/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`plugin/skills/forget/SKILL.md`, `plugin/skills/recall/SKILL.md`, `plugin/skills/remember/SKILL.md`, `plugin/skills/session-history/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `integrations/openclaw/openclaw.plugin.json`, `plugin/.claude-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/mcp/README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @agentmemory/agentmemory # once — bare` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx @agentmemory/agentmemory` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86 等\n- `npx @agentmemory/agentmemory demo` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npm install -g @agentmemory/agentmemory` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0009` supported 0.86\n- `npx -y @agentmemory/agentmemory@latest # forces latest from npm (cross-platform)` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx @agentmemory/agentmemory import-jsonl` 证据：`README.md` Claim：`clm_0011` supported 0.86, `clm_0012` supported 0.86\n- `npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx @agentmemory/agentmemory upgrade` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `pip install iii-sdk # Python` 证据：`README.md` Claim：`clm_0014` supported 0.86\n- `git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory` 证据：`README.md` Claim：`clm_0015` 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_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`plugin/skills/forget/SKILL.md`, `plugin/skills/recall/SKILL.md`, `plugin/skills/remember/SKILL.md`, `plugin/skills/session-history/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`plugin/skills/forget/SKILL.md`, `plugin/skills/recall/SKILL.md`, `plugin/skills/remember/SKILL.md`, `plugin/skills/session-history/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `integrations/openclaw/openclaw.plugin.json`, `plugin/.claude-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/mcp/README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` 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 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `integrations/openclaw/openclaw.plugin.json` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `integrations/openclaw/openclaw.plugin.json`, `plugin/.claude-plugin/plugin.json` 等\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/mcp/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `integrations/openclaw/openclaw.plugin.json` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `README.md`, `integrations/openclaw/openclaw.plugin.json` 等\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `README.md`, `deploy/README.md`, `src/cli.ts` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\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_0024` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `integrations/openclaw/openclaw.plugin.json`, `plugin/.claude-plugin/plugin.json` 等 Claim：`clm_0025` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/mcp/README.md` Claim：`clm_0026` 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- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugin/skills/forget/SKILL.md`, `plugin/skills/recall/SKILL.md`, `plugin/skills/remember/SKILL.md`, `plugin/skills/session-history/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `integrations/openclaw/openclaw.plugin.json`, `plugin/.claude-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/mcp/README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：474\n- 重要文件覆盖：40/474\n- 证据索引条目：80\n- 角色 / Skill 条目：4\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请基于 @agentmemory/agentmemory 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @agentmemory/agentmemory 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 @agentmemory/agentmemory 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **forget**（skill）：Delete specific observations or sessions from agentmemory. Use when user says \"forget this\", \"delete memory\", or wants to remove specific data for privacy. 激活提示：当用户任务与“forget”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/forget/SKILL.md`\n- **recall**（skill）：Search agentmemory for past observations, sessions, and learnings about a topic. Use when the user says \"recall\", \"remember\", \"what did we do\", or needs context from past sessions. 激活提示：当用户任务与“recall”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/recall/SKILL.md`\n- **remember**（skill）：Explicitly save an insight, decision, or learning to agentmemory's long-term storage. Use when the user says \"remember this\", \"save this\", or wants to preserve knowledge for future sessions. 激活提示：当用户任务与“remember”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/remember/SKILL.md`\n- **session-history**（skill）：Show what happened in recent past sessions on this project. Use when user asks \"what did we do last time\", \"session history\", \"past sessions\", or wants an overview of previous work. 激活提示：当用户任务与“session-history”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/session-history/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **agentmemory — Agent Instructions**（documentation）：agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives Worker/Function/Trigger . Everything goes through registerFunction / registerTrigger / sdk.trigger — never bypass iii-engine with standalone SQLite or in-process alternatives. 证据：`AGENTS.md`\n- **Install**（documentation）：Your coding agent remembers everything. No more re-explaining. Built on iii engine Persistent memory for Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client. 证据：`README.md`\n- **benchmark/**（documentation）：Two kinds of numbers live in this directory: 证据：`benchmark/README.md`\n- **One-click deploy templates**（documentation）：Stand up agentmemory on managed infrastructure without rolling your own Docker host. Each template ships a self-contained Dockerfile that pulls @agentmemory/agentmemory from npm at build time and copies the iii engine binary in from the official iiidev/iii image — no pre-built agentmemory image required. Storage mounts at /data ; an HMAC secret is generated by the first-boot entrypoint and persisted to the volume. The entrypoint overwrites the npm-bundled iii config with a deploy-tuned one that binds 0.0.0.0 and uses absolute /data paths, then drops privileges from root to node via gosu before exec'ing the agentmemory CLI. 证据：`deploy/README.md`\n- **agentmemory website**（documentation）：Next.js 15 App Router landing page for agentmemory. Lamborghini-inspired black + gold design system. Deploys to Vercel with zero config. 证据：`website/README.md`\n- **Deploy agentmemory on Coolify**（documentation）：Coolify https://coolify.io/self-hosted is an open-source, self-hosted Heroku/Render alternative that you run on your own VPS. This template deploys agentmemory as a Coolify Application backed by a Docker Compose stack — Coolify handles TLS termination, persistent volume provisioning, log aggregation, and the deploy webhook for you. 证据：`deploy/coolify/README.md`\n- **Deploy agentmemory on fly.io**（documentation）：This template runs agentmemory on a single fly.io machine with a 1 GB persistent volume mounted at /data . The HMAC secret is generated on first boot and persisted to the volume — you capture it from the deploy logs exactly once. 证据：`deploy/fly/README.md`\n- **Deploy agentmemory on Railway**（documentation）：This template runs agentmemory on a single Railway service with a persistent volume mounted at /data . The HMAC secret is generated on first boot and persisted to the volume — you read it once from the deploy logs and copy it into your client. 证据：`deploy/railway/README.md`\n- **Deploy agentmemory on Render**（documentation）：This template runs agentmemory on a single Render Web Service with a persistent disk mounted at /data . The HMAC secret is generated on first boot and persisted to the disk — you capture it from the deploy logs exactly once. 证据：`deploy/render/README.md`\n- **Python usage via iii-sdk**（documentation）：agentmemory registers its core operations as iii functions mem::remember , mem::observe , mem::context , mem::smart-search , mem::forget . Any language with an iii SDK can call them directly over the WebSocket transport on ws://localhost:49134 — no separate REST client needed. 证据：`examples/python/README.md`\n- **@agentmemory/fs-watcher**（documentation）：Filesystem connector for agentmemory. Watches one or more directories and emits an observation to the running agentmemory server every time a file changes. 证据：`integrations/filesystem-watcher/README.md`\n- **Install it in 30 seconds**（documentation）：Your Hermes agent remembers everything. No more re-explaining. Persistent cross-session memory via agentmemory — 95.2% retrieval accuracy on LongMemEval-S . Cross-agent shared with Claude Code, Cursor, OpenCode, and more. 证据：`integrations/hermes/README.md`\n- **Install it in 30 seconds**（documentation）：Your OpenClaw agents remember everything. No more re-explaining. Persistent cross-session memory via agentmemory — 95.2% retrieval accuracy on LongMemEval-S . 证据：`integrations/openclaw/README.md`\n- **Quick setup**（documentation）：Your pi sessions remember everything. No more re-explaining. Persistent cross-session memory via agentmemory — shared with Claude Code, Codex CLI, Gemini CLI, Hermes, OpenClaw, and more. 证据：`integrations/pi/README.md`\n- **@agentmemory/mcp**（documentation）：Standalone MCP server for agentmemory https://github.com/rohitg00/agentmemory . 证据：`packages/mcp/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@agentmemory/agentmemory\", \"version\": \"0.9.17\", \"description\": \"Persistent memory for AI coding agents, powered by iii-engine's three primitives\", \"type\": \"module\", \"main\": \"dist/index.mjs\", \"types\": \"dist/index.d.mts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" }, \"./dist/standalone.mjs\": \"./dist/standalone.mjs\", \"./package.json\": \"./package.json\" }, \"bin\": { \"agentmemory\": \"dist/cli.mjs\" }, \"scripts\": { \"build\": \"tsdown && cp iii-config.yaml dist/ 2 /dev/null true && cp iii-config.docker.yaml dist/ 2 /dev/null true && cp docker-compose.yml dist/ 2 /dev/null true && cp .env.example dist/ 2 /dev/null true && mkdir -p dist/viewer && cp src/view… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"agentmemory-website\", \"version\": \"0.1.0\", \"private\": true, \"scripts\": { \"gen-meta\": \"node scripts/gen-meta.mjs\", \"predev\": \"node scripts/gen-meta.mjs\", \"prebuild\": \"node scripts/gen-meta.mjs\", \"dev\": \"next dev\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\" }, \"dependencies\": { \"next\": \"^16.2.6\", \"react\": \"^19.2.6\", \"react-dom\": \"^19.2.6\" }, \"overrides\": { \"postcss\": \"^8.5.10\" }, \"devDependencies\": { \"@types/node\": \"^25.7.0\", \"@types/react\": \"^19.2.14\", \"@types/react-dom\": \"^19.2.3\", \"typescript\": \"^6.0.3\" }, \"engines\": { \"node\": \" =20\" } } 证据：`website/package.json`\n- **Contributing to agentmemory**（documentation）：Thanks for taking an interest. This file is the short path from \"I have an idea\" to \"it's in main.\" 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@agentmemory/fs-watcher\", \"version\": \"0.1.0\", \"description\": \"Filesystem connector for agentmemory — emits observations on file changes.\", \"type\": \"module\", \"bin\": { \"agentmemory-fs-watcher\": \"./bin.mjs\" }, \"main\": \"./watcher.mjs\", \"exports\": { \".\": \"./watcher.mjs\" }, \"files\": \"watcher.mjs\", \"bin.mjs\", \"README.md\" , \"engines\": { \"node\": \" =20\" }, \"license\": \"Apache-2.0\", \"homepage\": \"https://github.com/rohitg00/agentmemory/tree/main/integrations/filesystem-watcher\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/rohitg00/agentmemory.git\", \"directory\": \"integrations/filesystem-watcher\" } } 证据：`integrations/filesystem-watcher/package.json`\n- **Package**（package_manifest）：{ \"name\": \"agentmemory\", \"version\": \"0.9.4\", \"type\": \"module\", \"openclaw\": { \"extensions\": \"./plugin.mjs\" } } 证据：`integrations/openclaw/package.json`\n- **Package**（package_manifest）：{ \"name\": \"agentmemory-pi-extension\", \"private\": true, \"type\": \"module\" } 证据：`integrations/pi/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@agentmemory/mcp\", \"version\": \"0.9.17\", \"description\": \"Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint\", \"type\": \"module\", \"bin\": { \"agentmemory-mcp\": \"./bin.mjs\" }, \"files\": \"bin.mjs\", \"README.md\", \"LICENSE\" , \"keywords\": \"ai\", \"agent\", \"memory\", \"mcp\", \"agentmemory\" , \"author\": \"Rohit Ghumare \", \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/rohitg00/agentmemory\", \"directory\": \"packages/mcp\" }, \"homepage\": \"https://github.com/rohitg00/agentmemory readme\", \"bugs\": \"https://github.com/rohitg00/agentmemory/issues\", \"dependencies\": { \"@agentmemory/agentmemory\": \"~0.9.0\" }, \"publishConfi… 证据：`packages/mcp/package.json`\n- **Skill**（skill_instruction）：The user wants to remove data from agentmemory: $ARGUMENTS 证据：`plugin/skills/forget/SKILL.md`\n- **Skill**（skill_instruction）：The user wants to recall past context about: $ARGUMENTS 证据：`plugin/skills/recall/SKILL.md`\n- **Skill**（skill_instruction）：The user wants to save this to long-term memory: $ARGUMENTS 证据：`plugin/skills/remember/SKILL.md`\n- **Skill**（skill_instruction）：Fetch recent session history using the memory sessions MCP tool provided by the agentmemory server that this plugin wires up automatically via .mcp.json . Pass limit: 20 to get a meaningful window. 证据：`plugin/skills/session-history/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"agentmemory\", \"owner\": { \"name\": \"Rohit Ghumare\", \"github\": \"rohitg00\" }, \"plugins\": { \"name\": \"agentmemory\", \"description\": \"Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions\", \"source\": \"./plugin\" } } 证据：`.claude-plugin/marketplace.json`\n- **Marketplace**（structured_config）：{ \"name\": \"agentmemory\", \"interface\": { \"displayName\": \"agentmemory\" }, \"plugins\": { \"name\": \"agentmemory\", \"source\": { \"source\": \"git-subdir\", \"url\": \"https://github.com/rohitg00/agentmemory.git\", \"path\": \"./plugin\", \"ref\": \"main\" }, \"policy\": { \"installation\": \"AVAILABLE\", \"authentication\": \"ON INSTALL\" }, \"category\": \"Memory\" } } 证据：`.codex-plugin/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"agentmemory\", \"version\": \"0.9.17\", \"description\": \"Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 51 MCP tools, 4 skills, real-time viewer.\", \"author\": { \"name\": \"Rohit Ghumare\", \"url\": \"https://github.com/rohitg00\" }, \"license\": \"Apache-2.0\", \"homepage\": \"https://github.com/rohitg00/agentmemory\", \"repository\": \"https://github.com/rohitg00/agentmemory\", \"skills\": \"./skills/\" } 证据：`plugin/.claude-plugin/plugin.json`\n- **Plugin**（structured_config）：{ \"name\": \"agentmemory\", \"version\": \"0.9.17\", \"description\": \"Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 51 MCP tools, 4 skills, real-time viewer.\", \"author\": { \"name\": \"Rohit Ghumare\", \"url\": \"https://github.com/rohitg00\" }, \"license\": \"Apache-2.0\", \"homepage\": \"https://github.com/rohitg00/agentmemory\", \"repository\": \"https://github.com/rohitg00/agentmemory\", \"skills\": \"./skills/\", \"mcpServers\": \"./.mcp.json\", \"hooks\": \"./hooks/hooks.codex.json\" } 证据：`plugin/.codex-plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`packages/mcp/LICENSE`\n- **Changelog**（documentation）：All notable changes to agentmemory will be documented in this file. 证据：`CHANGELOG.md`\n- **Code of Conduct**（documentation）：agentmemory follows the Contributor Covenant v2.1 https://www.contributor-covenant.org/version/2/1/code of conduct/ . 证据：`CODE_OF_CONDUCT.md`\n- **Design System Inspired by Lamborghini**（documentation）：Design System Inspired by Lamborghini 证据：`DESIGN.md`\n- **Governance**（documentation）：This document describes how decisions are made in the agentmemory project. 证据：`GOVERNANCE.md`\n- **Maintainers**（documentation）：The authoritative list of people with commit access. See GOVERNANCE.md ./GOVERNANCE.md for what a Maintainer is, what they do, and how someone becomes one. 证据：`MAINTAINERS.md`\n- **Roadmap**（documentation）：This is agentmemory's public 12-month roadmap. It covers Q2 2026 through Q1 2027. The roadmap is the source of truth for where the project is heading; anything significant that lands in main should trace back to an item here or a ratified issue. 证据：`ROADMAP.md`\n- **Security Policy**（documentation）：Do not open a public GitHub issue for a suspected vulnerability. 证据：`SECURITY.md`\n- **AI Agent Memory: Benchmark Comparison**（documentation）：AI Agent Memory: Benchmark Comparison 证据：`benchmark/COMPARISON.md`\n- **LongMemEval-S Benchmark Results**（documentation）：LongMemEval https://arxiv.org/abs/2410.10813 ICLR 2025 is an academic benchmark for evaluating long-term memory in chat assistants. It tests 5 core abilities: information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention. 证据：`benchmark/LONGMEMEVAL.md`\n- **agentmemory v0.6.0 — Search Quality Evaluation Internal Dataset**（documentation）：agentmemory v0.6.0 — Search Quality Evaluation Internal Dataset 证据：`benchmark/QUALITY.md`\n- **agentmemory v0.6.0 — Real Embeddings Quality Evaluation**（documentation）：agentmemory v0.6.0 — Real Embeddings Quality Evaluation 证据：`benchmark/REAL-EMBEDDINGS.md`\n- **agentmemory v0.6.0 — Scale & Cross-Session Evaluation**（documentation）：agentmemory v0.6.0 — Scale & Cross-Session Evaluation 证据：`benchmark/SCALE.md`\n- **GHSA Draft: Stored XSS in agentmemory real-time viewer**（documentation）：GHSA Draft: Stored XSS in agentmemory real-time viewer 证据：`.github/security-advisories/01-viewer-xss.md`\n- **GHSA Draft: Remote shell script execution in agentmemory CLI startup**（documentation）：GHSA Draft: Remote shell script execution in agentmemory CLI startup 证据：`.github/security-advisories/02-curl-sh-rce.md`\n- **GHSA Draft: agentmemory REST and stream services bound to 0.0.0.0 by default**（documentation）：GHSA Draft: agentmemory REST and stream services bound to 0.0.0.0 by default 证据：`.github/security-advisories/03-default-bind-0000.md`\n- **GHSA Draft: Unauthenticated mesh sync in agentmemory**（documentation）：GHSA Draft: Unauthenticated mesh sync in agentmemory 证据：`.github/security-advisories/04-mesh-unauth.md`\n- **GHSA Draft: Arbitrary filesystem write via Obsidian export in agentmemory**（documentation）：GHSA Draft: Arbitrary filesystem write via Obsidian export in agentmemory 证据：`.github/security-advisories/05-obsidian-export-traversal.md`\n- **GHSA Draft: Incomplete secret redaction in agentmemory privacy filter**（documentation）：GHSA Draft: Incomplete secret redaction in agentmemory privacy filter 证据：`.github/security-advisories/06-privacy-redaction-incomplete.md`\n- **.Mcp**（structured_config）：{ \"mcpServers\": { \"agentmemory\": { \"command\": \"npx\", \"args\": \"-y\", \"@agentmemory/mcp\" } } } 证据：`plugin/.mcp.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"isolatedModules\": true, \"noUnusedLocals\": true, \"noUnusedParameters\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"test\", \"src/hooks\" } 证据：`tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": false, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"react-jsx\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \".next/dev/types/ / .ts\" , \"exclude\": \"node modules\" } 证据：`website/tsconfig.json`\n- **Load 100K 96C0Ed0**（structured_config）：{ \"schema version\": 1, \"generated at\": \"2026-05-13T19:49:26.116Z\", \"git sha\": \"96c0ed0\", \"base url\": \"http://localhost:3111\", \"seed\": 12648430, \"matrix\": { \"N\": 1000 , \"C\": 10 }, \"ops per cell\": 200, \"cells\": { \"endpoint\": \"POST /agentmemory/remember\", \"N\": 1000, \"C\": 10, \"ops\": 200, \"errors\": 0, \"wall ms\": 11504.64, \"throughput per sec\": 17.38, \"p50 ms\": 577.435, \"p90 ms\": 607.335, \"p99 ms\": 675.269, \"min ms\": 64.46, \"max ms\": 683.164 }, { \"endpoint\": \"POST /agentmemory/smart-search\", \"N\": 1000, \"C\": 10, \"ops\": 200, \"errors\": 0, \"wall ms\": 3264.572, \"throughput per sec\": 61.26, \"p50 ms\": 160.064, \"p90 ms\": 185.608, \"p99 ms\": 224.354, \"min ms\": 98.498, \"max ms\": 251.317 }, { \"endpoint\": \"GE… 证据：`benchmark/results/load-100k-96c0ed0.json`\n- **Railway**（structured_config）：{ \"$schema\": \"https://railway.com/railway.schema.json\", \"build\": { \"builder\": \"DOCKERFILE\", \"dockerfilePath\": \"deploy/railway/Dockerfile\" }, \"deploy\": { \"numReplicas\": 1, \"healthcheckPath\": \"/agentmemory/livez\", \"healthcheckTimeout\": 30, \"restartPolicyType\": \"ON FAILURE\", \"restartPolicyMaxRetries\": 10, \"requiredMountPath\": \"/data\" } } 证据：`deploy/railway/railway.json`\n- **Openclaw.Plugin**（structured_config）：{ \"id\": \"agentmemory\", \"kind\": \"memory\", \"name\": \"agentmemory\", \"description\": \"Persistent cross-session memory for OpenClaw via agentmemory.\", \"version\": \"0.9.4\", \"configSchema\": { \"type\": \"object\", \"additionalProperties\": false, \"properties\": { \"enabled\": { \"type\": \"boolean\" }, \"base url\": { \"type\": \"string\" }, \"token budget\": { \"type\": \"number\" }, \"min confidence\": { \"type\": \"number\" }, \"fallback on error\": { \"type\": \"boolean\" }, \"timeout ms\": { \"type\": \"number\" } } }, \"uiHints\": { \"enabled\": { \"label\": \"Enabled\" }, \"base url\": { \"label\": \"Base URL\", \"help\": \"agentmemory REST server base URL\" }, \"token budget\": { \"label\": \"Token Budget\", \"help\": \"Approximate context budget to inject befo… 证据：`integrations/openclaw/openclaw.plugin.json`\n- **Hooks.Codex**（structured_config）：{ \"hooks\": { \"SessionStart\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/session-start.mjs\", \"statusMessage\": \"agentmemory: loading session context\" } } , \"UserPromptSubmit\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/prompt-submit.mjs\", \"statusMessage\": \"agentmemory: recalling relevant memories\" } } , \"PreToolUse\": { \"matcher\": \"Edit Write Read Glob Grep\", \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/pre-tool-use.mjs\" } } , \"PostToolUse\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/post-tool-use.mjs\" } } , \"PreCompact\": { \"hooks\": { \"type\": \"command\", \"c… 证据：`plugin/hooks/hooks.codex.json`\n- **Hooks**（structured_config）：{ \"hooks\": { \"SessionStart\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/session-start.mjs\" } } , \"UserPromptSubmit\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/prompt-submit.mjs\" } } , \"PreToolUse\": { \"matcher\": \"Edit Write Read Glob Grep\", \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/pre-tool-use.mjs\" } } , \"PostToolUse\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/post-tool-use.mjs\" } } , \"PostToolUseFailure\": { \"hooks\": { \"type\": \"command\", \"command\": \"node ${CLAUDE PLUGIN ROOT}/scripts/post-tool-failure.mjs\" } } , \"PreCompact\": { \"hooks\": { \"type\": \"… 证据：`plugin/hooks/hooks.json`\n- **Generated Meta**（structured_config）：{ \"version\": \"0.9.16\", \"mcpTools\": 51, \"hooks\": 12, \"restEndpoints\": 121, \"testsPassing\": 977, \"generatedAt\": \"2026-05-16T09:33:03.891Z\" } 证据：`website/lib/generated-meta.json`\n- **=============================================================================**（source_file）：============================================================================= agentmemory configuration ============================================================================= Copy this file to ~/.agentmemory/.env or to your project root if you prefer scoped config and uncomment the lines you want to override. Every line is OFF by default — agentmemory runs out of the box with no LLM key, no embedding key, and no API auth. Set keys here only when you want to enable the corresponding feature. Run npx @agentmemory/agentmemory init to copy this file into place automatically. Run npx @agentmemory/agentmemory doctor to verify that the daemon reads the env you expect. Defaults shown in comm… 证据：`.env.example`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `README.md`, `benchmark/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `README.md`, `benchmark/README.md`\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, DESIGN.md, package.json\n- **快速开始**：importance `high`\n - source_paths: src/cli.ts, examples/python/quickstart.py, examples/python/observe_and_recall.py, .env.example\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/config.ts, src/types.ts, src/providers/index.ts\n- **数据流与处理**：importance `high`\n - source_paths: src/functions/observe.ts, src/functions/compress.ts, src/functions/remember.ts, src/functions/consolidation-pipeline.ts, src/state/index-persistence.ts\n- **记忆操作**：importance `high`\n - source_paths: src/functions/remember.ts, src/functions/observe.ts, src/functions/context.ts, src/functions/forget.ts, src/functions/checkpoints.ts\n- **搜索与检索**：importance `high`\n - source_paths: src/functions/smart-search.ts, src/functions/search.ts, src/functions/graph-retrieval.ts, src/state/hybrid-search.ts, src/state/vector-index.ts\n- **记忆压缩与合并**：importance `medium`\n - source_paths: src/functions/compress.ts, src/functions/compress-synthetic.ts, src/functions/consolidate.ts, src/functions/consolidation-pipeline.ts, src/functions/auto-forget.ts\n- **MCP服务器与工具**：importance `high`\n - source_paths: src/mcp/server.ts, src/mcp/tools-registry.ts, src/mcp/transport.ts, src/mcp/rest-proxy.ts, src/mcp/standalone.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `3a3f866ab52b3fb21b125bd7cf3a105475bc3f67`\n- inspected_files: `package.json`, `README.md`, `docker-compose.yml`, `examples/python/quickstart.py`, `examples/python/observe_and_recall.py`, `examples/python/README.md`, `packages/mcp/package.json`, `packages/mcp/README.md`, `src/logger.ts`, `src/xenova.d.ts`, `src/version.ts`, `src/index.ts`, `src/config.ts`, `src/types.ts`, `src/auth.ts`, `src/cli.ts`, `src/cli/preferences.ts`, `src/cli/doctor-diagnostics.ts`, `src/cli/onboarding.ts`, `src/cli/remove-plan.ts`\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: 来源证据：Viewer tab bar is vertically clipped in the web UI\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：npm installs anthropic dependencies\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.9.14 — CLI installer first + agentmemory stop\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.9.15 — DevEx overhaul\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.9.8 — local fallback tools/list returns 7 not 4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 能力判断依赖假设\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:1166408297 | https://github.com/rohitg00/agentmemory | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\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:1166408297 | https://github.com/rohitg00/agentmemory | last_activity_observed missing\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项目：rohitg00/agentmemory\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 是否匹配：claude, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Viewer tab bar is vertically clipped in the web UI（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：npm installs anthropic dependencies（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v0.9.14 — CLI installer first + agentmemory stop（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.9.15 — DevEx overhaul（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh（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/rohitg00/agentmemory 项目说明书\n\n生成时间：2026-05-16 22:32:59 UTC\n\n## 目录\n\n- [项目介绍](#intro)\n- [快速开始](#quickstart)\n- [系统架构](#architecture)\n- [数据流与处理](#data-flow)\n- [记忆操作](#memory-operations)\n- [搜索与检索](#search-retrieval)\n- [记忆压缩与合并](#consolidation)\n- [MCP服务器与工具](#mcp-server)\n- [代理插件与集成](#agent-plugins)\n- [部署与运维](#deployment)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quickstart), [系统架构](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)\n- [website/components/Features.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Features.tsx)\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 项目介绍\n\n## 概述\n\nAgentMemory 是一个完整的**内存运行时系统**（Complete Memory Runtime），专为 AI 编码代理设计。与传统的向量存储库或简单记忆库不同，AgentMemory 提供从**捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）到联邦（Federate）**的完整记忆生命周期管理能力。资料来源：[website/components/Features.tsx]()\n\n该项目的核心目标是让 AI 代理具备跨会话的持久记忆能力，使代理能够：\n\n- 记住文件修改的具体细节\n- 追踪决策历史和变更理由\n- 维护任务状态和阻塞关系\n- 快速恢复工作上下文\n\nAgentMemory 实现了 **95.2% 的检索召回率（R@5）**，同时减少 **92% 的 token 使用量**，且**不依赖外部数据库**。资料来源：[website/app/opengraph-image.tsx]()\n\n## 核心架构\n\nAgentMemory 采用客户端-服务器架构，运行在本地机器上，数据完全本地存储。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude Code] -->|MCP| M[AgentMemory Server]\n B[Codex CLI] -->|MCP| M\n C[OpenClaw] -->|MCP| M\n D[Hermes] -->|MCP| M\n E[PI] -->|MCP| M\n F[OpenHuman] -->|MCP| M\n G[其他 MCP 客户端] -->|MCP| M\n end\n \n subgraph 服务端\n M -->|存储| DB[(本地存储)]\n M -->|API| H[HTTP API :3111]\n end\n \n subgraph 功能模块\n M --> OBS[观察记录模块]\n M --> SEM[语义记忆模块]\n M --> ACT[行动追踪模块]\n M --> CRY[晶体化模块]\n M --> PRIV[隐私过滤模块]\n end\n```\n\n## 主要功能模块\n\n### 1. 观察记录（Observations）\n\n观察记录是 AgentMemory 的基础数据单元，用于捕获代理的每一次关键操作。资料来源：[src/prompts/compression.ts]()\n\n观察记录支持多种类型：\n\n| 类型 | 说明 | 重要性等级 |\n|------|------|-----------|\n| `file_read` | 文件读取操作 | 1-3 |\n| `file_write` | 文件写入操作 | 4-6 |\n| `file_edit` | 文件编辑操作 | 4-6 |\n| `command_run` | 命令执行操作 | 4-6 |\n| `search` | 搜索操作 | 1-3 |\n| `web_fetch` | 网页抓取 | 1-3 |\n| `conversation` | 对话内容 | 1-3 |\n| `error` | 错误信息 | 4-6 |\n| `decision` | 决策记录 | 7-9 |\n| `discovery` | 发现/洞察 | 7-9 |\n| `subagent` | 子代理调用 | 4-6 |\n| `notification` | 通知事件 | 1-3 |\n| `task` | 任务状态 | 4-6 |\n| `other` | 其他类型 | 1-3 |\n\n每条观察记录包含以下结构化字段：\n\n```xml\n\n 操作类型\n 简短描述标题（最多80字符）\n 一行上下文（可选）\n \n 具体事实1\n 具体事实2\n \n 2-3句总结\n \n 技术概念或模式\n \n \n 文件路径\n \n 1-10重要性评分\n\n```\n\n### 2. 语义记忆（Semantic Memory）\n\n语义记忆是将观察记录中的具体事实进行整合后形成的抽象知识表示。资料来源：[src/viewer/index.html]()\n\n语义记忆具有以下特性：\n\n- **置信度（Confidence）**：表示该记忆被确认的程度\n- **强度（Strength）**：表示该记忆在记忆网络中的权重\n- **自动提取**：从长时间会话中自动归纳\n\n```mermaid\ngraph LR\n O1[文件读取观察] --> SEM[语义记忆网络]\n O2[文件编辑观察] --> SEM\n O3[决策观察] --> SEM\n SEM --> CON1[概念节点]\n SEM --> CON2[概念节点]\n SEM --> CON3[概念节点]\n```\n\n### 3. 行动追踪（Actions）\n\n行动是代理在会话期间产生的后续跟进项，用于确保重要事项不会被遗漏。资料来源：[src/viewer/index.html]()\n\n行动具有完整的状态生命周期：\n\n```mermaid\ngraph LR\n A[pending 待处理] --> B[active 活动中]\n B --> C[done 已完成]\n B --> D[blocked 已阻塞]\n```\n\n行动可以通过以下三种方式创建：\n\n| 方式 | 命令/方法 | 示例 |\n|------|-----------|------|\n| MCP 工具 | `memory_action_create` | `memory_action_create { title, description, priority }` |\n| HTTP API | POST 请求 | `curl -X POST http://localhost:3111/agentmemory/actions` |\n| 自动提取 | 会话钩子 | 从长会话正文中自动识别 |\n\n### 4. 晶体化（Crystals）\n\n晶体是完成工作的冻结快照，通过 `memory_crystallize` 命令或 JSONL 导入时自动创建。资料来源：[src/viewer/index.html]()\n\n每个晶体包含：\n\n- 会话叙事摘要\n- 调用的关键工具及其结果\n- 修改的文件列表\n- 经验教训\n\n晶体是压缩的行动摘要——每个会话发生事件的 3 行摘要，用于为下一个会话提供快速上下文，而无需重新阅读所有内容。\n\n### 5. 隐私保护（Privacy）\n\nAgentMemory 内置了强大的隐私过滤功能，确保敏感信息不会被意外记录。资料来源：[src/functions/privacy.ts]()\n\n支持的隐私标签格式：\n\n```xml\n\n敏感内容\n\n```\n\n自动检测的敏感模式包括：\n\n| 模式类型 | 匹配示例 |\n|----------|----------|\n| API 密钥 | `api_key`, `secret`, `token`, `credential` |\n| Bearer 令牌 | `Bearer xxxxx...` |\n| OpenAI 密钥 | `sk-proj-...` |\n| Anthropic 密钥 | `sk-ant-...` |\n| GitHub 令牌 | `ghp_...`, `github_pat_...` |\n| 云服务商密钥 | `xoxb-...`, `AKIA...`, `AIza...` |\n| NPM 令牌 | `npm_...` |\n| GitLab 令牌 | `glpat-...` |\n\n## 支持的代理客户端\n\nAgentMemory 支持多种第一方插件和 MCP 原生客户端。资料来源：[website/components/Agents.tsx]()\n\n### 第一方支持的代理\n\n| 代理名称 | 来源 | 说明 |\n|----------|------|------|\n| Claude Code | Anthropic | Anthropic 官方 CLI 工具 |\n| Codex CLI | OpenAI | OpenAI 命令行编码代理 |\n| OpenClaw | OpenClaw | 开源编码代理 |\n| Hermes | Hermes | 自定义代理方案 |\n| PI | Personal Intelligence | 个人智能助手 |\n| OpenHuman | OpenHuman | 开放人类项目 |\n\n### MCP 原生支持\n\n对于其他 MCP 客户端，AgentMemory 提供自动连接能力：\n\n```bash\nagentmemory connect \n```\n\n此命令会自动配置并连接所有支持的 MCP 客户端。\n\n## 安装与部署\n\n### 快速安装\n\nAgentMemory 可通过 npm 直接安装：\n\n```bash\nnpm install @agentmemory/agentmemory\n```\n\n或使用 npx 快速启动：\n\n```bash\nnpx agentmemory\n```\n\n服务默认运行在 **http://localhost:3111** 端口。资料来源：[website/components/Install.tsx]()\n\n### 架构特性\n\nAgentMemory 的核心设计原则：\n\n| 特性 | 说明 |\n|------|------|\n| 本地运行 | 在用户机器上运行，无需云服务 |\n| 数据本地存储 | 所有数据保留在本地，不上传 |\n| 多模型支持 | 支持 Anthropic、Gemini、MiniMax、OpenRouter |\n| MCP 协议 | 标准化 Model Context Protocol 接口 |\n| 自包含 | 零外部数据库依赖 |\n\n## API 端点\n\nAgentMemory 提供 HTTP REST API 用于与外部系统集成：\n\n| 端点 | 方法 | 用途 |\n|------|------|------|\n| `/agentmemory/actions` | POST | 创建行动 |\n| `/agentmemory/sessions` | GET | 获取会话列表 |\n| `/agentmemory/audit` | GET | 获取审计日志 |\n\n### API 调用示例\n\n```bash\n# 创建行动\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n## 摘要生成系统\n\nAgentMemory 包含会话摘要生成功能，用于将多个观察记录整合为简洁的会话摘要。资料来源：[src/prompts/summary.ts]()\n\n摘要输出格式：\n\n```xml\n\n 会话标题（最多100字符）\n 3-5句成就叙事\n \n 关键决策1\n \n \n 修改的文件路径\n \n \n 关键概念\n \n\n```\n\n摘要系统规则：\n\n- 聚焦于成果而非单个工具调用\n- 突出决策及其理由\n- 列出所有创建或修改的文件\n- 概念应为可搜索的术语，便于未来上下文检索\n\n## 技术栈\n\n| 组件 | 技术 |\n|------|------|\n| 服务器 | Node.js / TypeScript |\n| 客户端协议 | MCP (Model Context Protocol) |\n| 数据存储 | 本地文件系统 |\n| 运行时端口 | 3111 (默认) |\n| 包管理 | npm |\n| 开源协议 | Apache-2.0 |\n\n## 总结\n\nAgentMemory 是一个专为 AI 编码代理设计的完整内存运行时，通过 MCP 协议与各类代理客户端集成。它提供了从原始观察记录到语义记忆、再到晶体化摘要的完整数据生命周期管理，同时内置隐私保护机制确保敏感信息安全。项目采用本地优先设计，数据完全存储在用户本地，支持多种 AI 模型和代理客户端，是构建具有持久记忆能力的 AI 辅助开发环境的基础设施。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#intro), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/rohitg00/agentmemory/blob/main/src/cli.ts)\n- [examples/python/observe_and_recall.py](https://github.com/rohitg00/agentmemory/blob/main/examples/python/observe_and_recall.py)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 快速开始\n\n## 概述\n\nAgentMemory 是一个完整的内存运行时系统，专为 AI 编码代理设计。它提供了**捕获（Capture）**、**召回（Recall）**、**整合（Consolidate）**、**观察（Observe）** 和 **联邦（Federate）** 五项核心能力，使 AI 代理能够在多个会话之间保持上下文连贯性。\n\n默认服务器端口为 **3111**，通过 REST API 和 MCP（Model Context Protocol）两种方式提供服务。\n\n## 环境要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | >= 20 | 运行服务器的核心依赖 |\n| npm | 内置于 Node | 包管理器 |\n| 模型提供商 | Anthropic / Gemini / MiniMax / OpenRouter | 支持多种 LLM 后端 |\n\n## 安装方式\n\n### 全局安装（推荐）\n\n```bash\nnpm install -g @agentmemory/agentmemory\n```\n\n### 本地安装\n\n```bash\nnpm install @agentmemory/agentmemory\n```\n\n安装完成后，可通过 `agentmemory connect ` 命令自动连接支持的代理。资料来源：[website/components/Install.tsx]()\n\n### MCP 客户端配置\n\nAgentMemory 支持多种 MCP 客户端的通用 JSON 配置方式：\n\n| 客户端 | 配置文件位置 | 特点 |\n|--------|--------------|------|\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 mcpServers 格式 |\n| Cursor | Deep Link 一键安装 | 自动化配置 |\n| Cline | `.cline/mcp_settings.json` | mcpServers 格式 |\n| Roo Code | `.roo/mcp_settings.json` | mcpServers 格式 |\n| WindSurf | 配置文件 | mcpServers 格式 |\n| Gemini CLI | 配置文件 | mcpServers 格式 |\n\n通用 MCP JSON 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"agentmemory\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx]()\n\n## 启动服务\n\n### 基本启动\n\n```bash\nagentmemory serve\n```\n\n服务器将在 `http://localhost:3111` 启动，提供以下核心端点：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/sessions` | GET/POST | 会话管理 |\n| `/observations` | GET/POST | 观察记录 CRUD |\n| `/actions` | GET/POST | 行动任务跟踪 |\n| `/audit` | GET | 审计日志查询 |\n| `/crystals` | GET | 压缩后的会话摘要 |\n| `/timeline` | GET | 时间线视图数据 |\n\n### 环境变量配置\n\n创建 `.env` 文件配置可选参数：\n\n```bash\n# 模型配置\nANTHROPIC_API_KEY=sk-...\nMODEL_PROVIDER=anthropic\n\n# 服务器配置\nPORT=3111\n\n# 存储配置\nDATA_DIR=./data\n```\n\n## 核心概念\n\n### 观察（Observations）\n\n观察是 AgentMemory 的基本记忆单元，记录代理在会话中执行的操作和关键事件。每个观察包含以下结构：\n\n```xml\n\n file_edit | command_run | search | error | decision | discovery | ...\n 简短描述（最多80字符）\n \n 具体事实细节\n \n 2-3句总结\n \n 路径/to/文件\n \n 1-10 重要性评分\n\n```\n\n重要性评分标准：\n- **1-3**：日常读取操作\n- **4-6**：编辑和命令执行\n- **7-9**：架构决策\n- **10**：破坏性变更\n\n资料来源：[src/prompts/compression.ts]()\n\n### 水晶（Crystals）\n\n水晶是压缩后的会话摘要快照，包含一个会话的叙事、调用过的工具（关键结果）、访问过的文件以及学到的经验教训。在 JSONL 导入时自动创建，或通过 `memory_crystallize` 手动生成。\n\n```xml\n\n 会话标题（最多100字符）\n 3-5句完成的工作叙事\n \n 做出的关键技术决策\n \n \n 修改的路径\n \n \n 会话中的关键概念\n \n\n```\n\n资料来源：[src/prompts/summary.ts]()\n\n### 行动（Actions）\n\n行动是代理在会话中发现的待办事项，包括需要重新访问的决策、需要检查的文件、等待输入的任务等。状态流转为：pending → active → done/blocked。\n\n创建方式：\n\n```bash\n# MCP 工具方式\nmemory_action_create { \"title\": \"ship v1\", \"priority\": \"high\" }\n\n# Curl 方式\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n资料来源：[src/viewer/index.html]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[启动 AgentMemory] --> B[连接代理]\n B --> C[创建会话]\n C --> D[执行操作]\n D --> E{触发钩子}\n E -->|工具调用| F[压缩观察]\n E -->|长会话体| G[自动提取行动]\n E -->|会话结束| H[生成水晶摘要]\n F --> I[存储到记忆库]\n G --> I\n H --> I\n I --> J[下次会话召回上下文]\n```\n\n## API 使用示例\n\n### 记录观察\n\n```bash\ncurl -X POST http://localhost:3111/observations \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"type\": \"file_write\",\n \"title\": \"Create user authentication module\",\n \"files\": [\"src/auth/login.ts\"],\n \"importance\": 7\n }'\n```\n\n### 查询记忆\n\n```python\nimport requests\n\n# 搜索相关观察\nresponse = requests.get(\n 'http://localhost:3111/observations',\n params={'query': 'authentication', 'limit': 10}\n)\nmemories = response.json()\n```\n\n### 获取会话时间线\n\n```bash\ncurl \"http://localhost:3111/timeline?session_id=abc123&page=0\"\n```\n\n## 查看器界面\n\nAgentMemory 提供内置 Web 查看器，可通过浏览器访问 `http://localhost:3111` 查看：\n\n- **Feature Flags**：功能开关管理\n- **Crystals**：压缩摘要列表，支持搜索\n- **Actions**：行动任务看板\n- **Timeline**：时间线视图，支持分页\n- **Activity**：活动概览和审计日志\n\n资料来源：[src/viewer/index.html]()\n\n## 代理集成\n\nAgentMemory 原生支持以下第一方代理插件：\n\n| 代理 | 说明 |\n|------|------|\n| Claude Code | Anthropic 官方 CLI |\n| Codex CLI | OpenAI 命令行工具 |\n| OpenClaw | 开源代理框架 |\n| Hermes | 定制化代理 |\n| PI | 专用代理 |\n| OpenHuman | 人类增强代理 |\n\n其他所有 MCP 客户端均可通过标准 MCP JSON 配置免费接入。\n\n资料来源：[website/components/Agents.tsx]()\n\n## 性能指标\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 检索 R@5 | 95.2% | Top-5 召回准确率 |\n| Token 减少 | 92% | 相比原始对话 |\n| 外部数据库 | 0 | 无需额外存储依赖 |\n\n资料来源：[website/app/opengraph-image.tsx]()\n\n## 验证安装\n\n```bash\n# 检查 CLI 是否可用\nagentmemory --version\n\n# 启动服务器并验证\nagentmemory serve &\ncurl http://localhost:3111/health\n```\n\n## 下一步\n\n- 阅读完整文档：https://github.com/rohitg00/agentmemory#quick-start\n- 查看集成示例：https://github.com/rohitg00/agentmemory/tree/main/integrations\n- 查阅变更日志：https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#intro), [数据流与处理](#data-flow), [记忆操作](#memory-operations)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 系统架构\n\n## 概述\n\nAgentMemory 是一个完整的 AI 代理记忆运行时系统，而非简单的向量数据库或工具库。该系统提供完整的记忆生命周期管理：捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）和联邦（Federate） 资料来源：[src/viewer/index.html]()\n\nAgentMemory 的核心设计理念是将原始观察数据转化为结构化的语义记忆，使 AI 代理能够在多次会话中保持上下文连贯性，避免重复工作并积累可复用的知识。\n\n## 核心架构组件\n\n### 系统服务层\n\nAgentMemory 以本地 HTTP 服务器形式运行，默认监听端口 **3111**，为所有记忆操作提供统一的 API 接口 资料来源：[website/components/LiveTerminal.tsx]()\n\n```mermaid\ngraph TD\n A[AI 代理] -->|MCP 协议| B[AgentMemory Server :3111]\n B --> C[JSONL 存储引擎]\n B --> D[LLM 处理管道]\n B --> E[Web Viewer 界面]\n \n C --> F[observations]\n C --> G[actions]\n C --> H[crystals]\n C --> I[sessions]\n```\n\n### 记忆类型体系\n\n系统定义了四种互补的记忆类型，分别承担不同的认知功能：\n\n| 记忆类型 | 用途 | 数据结构 |\n|---------|------|---------|\n| **Observations** | 原始工具调用记录 | 时间线形式，含分页 |\n| **Semantic Memory** | 事实性知识提取 | 置信度 + 强度评分 |\n| **Procedural Memory** | 可复用的操作流程 | 触发条件 + 步骤序列 |\n| **Crystals** | 会话级压缩摘要 | 3行精华总结 |\n\n资料来源：[src/viewer/index.html]()\n\n### 记忆处理管道\n\n记忆从原始观察到结构化知识的转化经过三个主要阶段：\n\n```mermaid\ngraph LR\n A[原始工具调用] -->|压缩| B[Observation]\n B -->|整合| C[Semantic Facts]\n B -->|整合| D[Procedures]\n B + C + D -->|汇总| E[Crystal]\n```\n\n#### 第一阶段：压缩（Compression）\n\n压缩引擎将原始工具调用转化为结构化的观察记录。该阶段使用专用的 LLM 提示模板，从每次工具调用中提取关键技术细节 资料来源：[src/prompts/compression.ts]()\n\n压缩输出包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `type` | enum | 工具调用类型（file_read/write/edit/command_run 等） |\n| `title` | string | 简短描述（最多80字符） |\n| `facts` | array | 具体事实细节列表 |\n| `narrative` | string | 2-3句总结 |\n| `concepts` | array | 可搜索的技术概念 |\n| `files` | array | 涉及的文件路径 |\n| `importance` | number | 1-10 重要性评分 |\n\n#### 第二阶段：整合（Consolidation）\n\n整合阶段从多次观察中提取高层次的语义记忆和程序性记忆 资料来源：[src/prompts/consolidation.ts]()\n\n- **语义记忆提取**：从重复出现的观察中提取稳定的事实断言，附带置信度评分\n- **程序性记忆提取**：识别重复执行2次以上的操作模式，提取为可自动触发的流程\n- **关系识别**：建立概念间的语义关联\n\n#### 第三阶段：摘要（Crystallization）\n\n每个会话结束时，系统生成晶体（Crystal）——会话的压缩精华摘要，包含：\n\n- 会话标题（最多100字符）\n- 3-5句叙事总结\n- 关键决策及理由\n- 修改的文件列表\n- 可搜索的概念标签 资料来源：[src/prompts/summary.ts]()\n\n### 观察数据模型\n\n观察记录在界面中以时间线形式展示，支持分页浏览：\n\n```typescript\ninterface Observation {\n id: string;\n timestamp: number;\n type: 'file_read' | 'file_write' | 'file_edit' | \n 'command_run' | 'search' | 'web_fetch' | \n 'conversation' | 'error' | 'decision' | \n 'discovery' | 'subagent' | 'notification' | \n 'task' | 'other';\n title: string;\n subtitle?: string;\n facts: string[];\n narrative: string;\n concepts: string[];\n files: string[];\n importance: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;\n hookType: string;\n toolName?: string;\n}\n```\n\n资料来源：[src/prompts/compression.ts]()\n\n### 语义记忆模型\n\n语义记忆条目展示时附带多维度评估指标：\n\n| 指标 | 说明 | 可视化 |\n|-----|------|-------|\n| **Confidence** | 事实置信度 | 百分比显示 |\n| **Strength** | 记忆强度 | 进度条（>70%为绿色） |\n| **重要性** | 对系统的影响程度 | 颜色编码 |\n\n资料来源：[src/viewer/index.html]()\n\n## 功能模块架构\n\n### 动作系统（Actions）\n\n动作系统追踪代理在会话中产生的后续跟进项，包括：\n\n- 需要重访的决策\n- 需要检查的文件\n- 等待输入的任务\n\n动作状态流转：`pending → active → done/blocked`\n\n创建方式支持三种渠道：\n1. MCP 工具调用 `memory_action_create`\n2. HTTP API 直接 POST\n3. 钩子自动从长会话正文中提取\n\n资料来源：[src/viewer/index.html]()\n\n### 特性标志系统（Feature Flags）\n\n系统内置可配置的特性标志机制，用于动态控制功能开关：\n\n```typescript\ninterface FeatureFlag {\n kind: string; // 样式类别\n dismissKey: string; // 关闭键\n icon: string; // 图标\n title: string; // 标题\n keyLabel: string; // 键标签\n desc: string; // 描述\n enable: string; // 启用命令\n docs?: string; // 文档链接\n}\n```\n\n特性标志支持折叠/展开展示，并可单独关闭 资料来源：[src/viewer/index.html]()\n\n### 隐私保护机制\n\n系统内置多层次隐私保护功能，用于检测和脱敏敏感信息 资料来源：[src/functions/privacy.ts]()\n\n**检测模式包括：**\n\n| 类别 | 正则模式 |\n|-----|---------|\n| 通用凭证 | `api_key`, `secret`, `token`, `password`, `credential` 等 |\n| Bearer Token | `Bearer [A-Za-z0-9._\\-+/=]{20,}` |\n| OpenAI Key | `sk-proj-[A-Za-z0-9\\-_]{20,}` |\n| Anthropic Key | `sk-ant-[A-Za-z0-9\\-_]{20,}` |\n| GitHub Token | `gh[pus]_[A-Za-z0-9]{36,}` |\n| GitHub PAT | `github_pat_[A-Za-z0-9_]{22,}` |\n| Slack Token | `xoxb-[A-Za-z0-9\\-]+` |\n| AWS Key | `AKIA[0-9A-Z]{16}` |\n| Google API | `AIza[A-Za-z0-9\\-_]{35}` |\n| NPM Token | `npm_[A-Za-z0-9]{36}` |\n| GitLab Token | `glpat-[A-Za-z0-9\\-_]{20,}` |\n\n此外，系统支持 `` XML 标签用于手动标记需要隐藏的内容区域。\n\n## 代理集成架构\n\n### MCP 原生支持\n\nAgentMemory 通过 Model Context Protocol (MCP) 实现与多种 AI 代理的原生集成：\n\n```mermaid\ngraph TD\n subgraph \"支持的代理\"\n A[Claude Code]\n B[Codex CLI]\n C[OpenClaw]\n D[Hermes]\n E[PI]\n F[OpenHuman]\n end\n \n A & B & C & D & E & F -->|agentmemory connect| G[MCP Server]\n G --> H[AgentMemory Core]\n```\n\n连接命令：`agentmemory connect ` 自动配置所有兼容代理 资料来源：[website/components/Agents.tsx]()\n\n### 审计日志\n\n系统记录完整的操作审计日志，包含：\n\n- 会话历史（sessions）\n- 审计条目（audit，含200条限制）\n\n资料来源：[src/viewer/index.html]()\n\n## Web Viewer 架构\n\nWeb Viewer 提供图形化的记忆查看界面，包含以下视图模块：\n\n| 视图 | 功能 |\n|-----|------|\n| **Timeline** | 时间线形式浏览所有观察记录，支持按类型筛选和分页 |\n| **Actions** | 跟踪和管理代理产生的后续动作项 |\n| **Crystals** | 查看压缩后的会话摘要，支持搜索 |\n| **Activity** | 展示会话和审计活动的聚合视图 |\n| **Audit** | 详细的操作审计日志 |\n\n每个视图都包含搜索功能、筛选机制和分页导航 资料来源：[src/viewer/index.html]()\n\n## 数据存储架构\n\nAgentMemory 采用 **JSONL**（JSON Lines）格式进行本地存储，无需外部数据库依赖 资料来源：[src/viewer/index.html]()\n\n存储特点：\n\n- **无外部依赖**：零外部数据库，降低部署复杂度\n- **会话隔离**：每个会话的原始观察独立存储\n- **自动清理**：原始观察定期修剪，仅保留晶体摘要\n- **可追溯性**：晶体保存后仍可重放会话的关键信息\n\n## 开发贡献架构\n\n项目采用标准化的分支管理策略 资料来源：[CONTRIBUTING.md]()\n\n| 分支类型 | 命名格式 | 用途 |\n|---------|---------|------|\n| 功能分支 | `feat/` | 新功能开发 |\n| 修复分支 | `fix/-` | Bug 修复 |\n| 文档分支 | `docs/` | 文档更新 |\n| 重构分支 | `refactor/` | 代码重构 |\n| 维护分支 | `chore/` | 其他维护工作 |\n\n开发流程要求：\n- Node >= 20\n- TypeScript 编译通过\n- 全量测试通过\n- 所有提交包含签名（`-s` 标志）\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 运行时 | Node.js (>=20) |\n| 类型系统 | TypeScript |\n| 存储 | JSONL (本地文件) |\n| 通信协议 | HTTP REST API |\n| 代理集成 | MCP (Model Context Protocol) |\n| 界面 | Web Viewer (HTML/JS) |\n| AI 处理 | LLM API (可配置) |\n\nAgentMemory 的设计目标是在本地环境中提供企业级的记忆管理能力，同时保持零外部依赖和快速启动特性。通过 MCP 协议的广泛兼容性，系统可以无缝集成到现有的 AI 代理工作流中。\n\n---\n\n\n\n## 数据流与处理\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [记忆操作](#memory-operations), [搜索与检索](#search-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 数据流与处理\n\n## 概述\n\nAgentMemory 的数据流与处理系统是一个完整的数据处理管道，负责从原始工具调用观测中提取、压缩、总结并最终整合为可重用的结构化记忆。该系统采用分层处理架构，将观测数据逐级转化为语义记忆、程序记忆和关系记忆三种核心记忆类型，为 AI 代理提供持久化上下文能力。\n\n数据处理管道的设计遵循以下核心原则：高保真度保留技术细节、高压缩率降低 token 消耗、自动隐私保护机制。系统无需外部数据库，仅依赖本地 JSONL 文件存储即可运行。\n\n## 核心处理流程\n\n### 数据处理阶段总览\n\n```mermaid\ngraph TD\n A[原始工具调用] --> B[观测捕获 observe]\n B --> C[压缩处理 compress]\n C --> D[会话总结 summary]\n D --> E[记忆整合 consolidation]\n E --> F[关系映射 relations]\n F --> G[索引持久化 persistence]\n G --> H[检索召回 remember]\n \n B1[隐私检测] -.->|过滤敏感信息| B\n C1[XML 结构化] -.->|格式标准化| C\n D1[叙事生成] -.->|上下文连贯| D\n E1[程序提取] -.->|可复用知识| E\n```\n\n### 阶段一：观测捕获\n\n观测捕获是数据进入系统的入口点。当代理执行工具调用或触发特定钩子时，系统实时捕获这些事件。捕获内容包括工具名称、执行参数、返回结果、执行时间戳等元数据。观测类型映射表如下：\n\n| 观测类型 | 对应工具/钩子 | 说明 |\n|---------|--------------|------|\n| file_read | Read | 文件读取操作 |\n| file_write | Write | 文件写入操作 |\n| file_edit | Edit | 文件编辑操作 |\n| command_run | Bash | 命令执行操作 |\n| search | Grep/Glob | 搜索操作 |\n| web_fetch | WebFetch/WebSearch | 网络获取 |\n| conversation | AskUserQuestion | 用户对话 |\n| subagent | Task | 子任务执行 |\n\n### 阶段二：压缩处理\n\n压缩处理将原始观测转化为结构化的 XML 格式，这是系统实现 92% token 减少量的关键步骤。\n\n压缩系统提示词定义了严格的数据结构要求：\n\n```xml\n\n one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other\n Short descriptive title (max 80 chars)\n One-line context (optional)\n \n Specific factual detail 1\n Specific factual detail 2\n \n 2-3 sentence summary of what happened and why it matters\n \n technical concept or pattern\n \n \n path/to/file\n \n 1-10 scale\n\n```\n\n**重要性评分标准**：\n\n| 分数范围 | 含义 | 示例场景 |\n|---------|------|---------|\n| 1-3 | 常规操作 | 日常文件读取 |\n| 4-6 | 中等变更 | 编辑命令执行 |\n| 7-9 | 架构决策 | 核心设计变更 |\n| 10 | 破坏性变更 | API 重大修改 |\n\n压缩处理函数 `buildCompressionPrompt` 接收原始观测数据，生成符合系统提示词要求的压缩指令，用于调用 LLM 生成结构化输出。\n\n资料来源：[src/prompts/compression.ts:1-29]()\n\n### 阶段三：会话总结\n\n会话总结从多个压缩观测中提取会话级别的元信息，生成会话摘要。总结系统采用 XML 结构化输出：\n\n```xml\n\n Short session title (max 100 chars)\n 3-5 sentence narrative of what was accomplished\n \n Key technical decision made\n \n \n path/to/modified/file\n \n \n key concept from session\n \n\n```\n\n`buildSummaryPrompt` 函数将多个观测对象格式化为标准输入文本，供 LLM 生成会话级摘要。该函数将每个观测的 facts、narrative、files 和 concepts 字段进行格式化重组，确保 LLM 能够理解完整的会话上下文。\n\n资料来源：[src/prompts/summary.ts:1-45]()\n\n## 记忆整合与提炼\n\n### 程序记忆提取\n\n程序记忆提取是系统的核心知识提炼机制。当同一操作模式在多个会话中出现 2 次以上时，系统自动识别并提取为可复用程序。\n\n提取规则：\n\n| 规则类型 | 描述 |\n|---------|------|\n| 频率阈值 | 仅提取出现 2+ 次的模式 |\n| 步骤粒度 | 每个步骤需具体可执行 |\n| 触发条件 | 条件需足够具体以支持自动匹配 |\n\n程序提取提示词模板：\n\n```\nExtract reusable procedures from these recurring patterns:\n\n[Pattern 1] (seen 3x)\n\n\n[Pattern 2] (seen 2x)\n\n```\n\n该提示词驱动 LLM 从高频模式中归纳出通用的操作流程和触发条件。\n\n资料来源：[src/prompts/consolidation.ts:7-15]()\n\n### 记忆聚类与反思\n\n记忆聚类将语义相关的记忆项组织在一起，反思系统在此基础上生成高层洞察：\n\n```typescript\n// 聚类输出结构\ncluster = {\n facts: [{ fact: string, confidence: number }],\n lessons: [{ content: string, confidence: number }],\n crystalNarratives: [string]\n}\n```\n\n反思过程生成的洞察包括：\n\n| 类别 | 说明 |\n|-----|------|\n| 已知事实 | 高置信度的技术事实 |\n| 经验教训 | 从操作中提炼的可复用经验 |\n| 完成工作摘要 | 已完成项目的关键叙事 |\n\n资料来源：[src/prompts/reflect.ts:10-30]()\n\n## 隐私保护机制\n\n### 敏感信息检测\n\n隐私处理模块维护了一个全面的敏感信息检测模式列表：\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n // API 密钥类\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n // Bearer Token\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n // OpenAI 密钥\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n // Anthropic 密钥\n /sk-ant-[A-Za-z0-9\\-_]{20,}/g,\n // GitHub Token\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /github_pat_[A-Za-z0-9_]{22,}/g,\n // Slack Token\n /xoxb-[A-Za-z0-9\\-]+/g,\n // AWS 密钥\n /AKIA[0-9A-Z]{16}/g,\n // Google API Key\n /AIza[A-Za-z0-9\\-_]{35}/g,\n // JWT\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n // NPM Token\n /npm_[A-Za-z0-9]{36}/g,\n // GitLab Token\n /glpat-[A-Za-z0-9\\-_]{20,}/g\n];\n```\n\n### 隐私标签处理\n\n除了正则匹配外，系统还支持 `` XML 标签包裹的隐私内容：\n\n```typescript\nconst PRIVATE_TAG_RE = /[\\s\\S]*?<\\/private>/gi;\n```\n\n所有检测到的敏感信息都会在进入压缩管道前被过滤或脱敏，确保输出中不包含任何凭据信息。\n\n资料来源：[src/functions/privacy.ts:1-20]()\n\n## 数据存储与持久化\n\n### 存储架构\n\nAgentMemory 采用零外部依赖的存储架构，所有数据以 JSONL 格式存储于本地文件系统：\n\n| 数据类型 | 存储格式 | 说明 |\n|---------|---------|------|\n| 观测记录 | JSONL | 每行一条压缩观测 |\n| 会话摘要 | JSONL | 每行一个会话总结 |\n| 索引数据 | JSON | 快速检索索引 |\n| 元数据 | JSON | 配置和状态信息 |\n\n### 持久化策略\n\n系统在处理过程中自动触发持久化操作，关键时机包括：\n\n1. **观测压缩完成后**：立即写入观测记录\n2. **会话结束时**：生成并存储会话摘要\n3. **记忆整合后**：更新相关索引\n4. **定时检查点**：防止数据丢失\n\n## 检索与召回\n\n### 召回流程\n\n当代理需要检索历史记忆时，系统执行以下召回流程：\n\n```mermaid\ngraph LR\n A[查询请求] --> B[语义匹配]\n B --> C[重要性过滤]\n C --> D[相关性排序]\n D --> E[上下文组装]\n E --> F[返回结果]\n```\n\n### 召回策略\n\n| 策略 | 说明 | 优先级 |\n|-----|------|-------|\n| 精确匹配 | 文件路径、函数名等精确匹配 | 高 |\n| 语义相似 | 基于概念嵌入的相似度匹配 | 中 |\n| 时间衰减 | 近期记忆权重更高 | 低 |\n| 使用频率 | 高频访问记忆优先 | 低 |\n\n## 配置参数\n\n### 核心配置项\n\n| 参数 | 默认值 | 说明 |\n|-----|-------|------|\n| POLL_INTERVAL_MS | 10000 | 轮询间隔（毫秒） |\n| WS_MAX_RETRIES | 4 | WebSocket 最大重试次数 |\n| DIRECT_FAILURE_THRESHOLD | 2 | 直接连接失败阈值 |\n| importance.minThreshold | 0 | 最小重要性阈值 |\n\n## 技术总结\n\nAgentMemory 的数据流与处理系统通过分层处理架构，实现了从原始观测到结构化记忆的完整转换：\n\n- **观测层**：实时捕获工具调用和系统事件\n- **压缩层**：XML 结构化压缩，token 减少 92%\n- **总结层**：会话级别叙事生成\n- **整合层**：程序记忆提取和聚类反思\n- **存储层**：JSONL 本地持久化，零外部依赖\n- **召回层**：多策略检索和上下文组装\n\n整个处理管道支持实时处理和批量处理两种模式，通过 WebSocket 和 HTTP API 对外提供服务，确保与各类 MCP 客户端的兼容性。\n\n---\n\n\n\n## 记忆操作\n\n### 相关页面\n\n相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n
\n\n# 记忆操作\n\nAgentMemory 是一个完整的记忆运行时系统，提供多种记忆操作能力来捕获、召回、整合和观察 AI 代理的工作记忆。本页详细介绍记忆操作的核心概念、数据模型和系统交互流程。\n\n## 系统概述\n\nAgentMemory 的记忆操作涵盖四大核心能力领域：\n\n| 操作类型 | 功能描述 | 数据持久化 |\n|---------|---------|-----------|\n| **记忆压缩** (Compression) | 将原始工具调用观测压缩为结构化数据 | 观察记录 |\n| **会话摘要** (Summary) | 生成会话级别的叙事性摘要 | 水晶 (Crystals) |\n| **反思整合** (Reflection) | 从记忆簇中提取高层洞察 | 语义/程序性记忆 |\n| **隐私处理** (Privacy) | 自动过滤敏感信息和凭证 | 无持久化 |\n\n资料来源：[src/prompts/compression.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n## 核心数据模型\n\n### 观察记录 (Observation)\n\n每次工具调用后系统会生成结构化的观察记录，格式如下：\n\n```xml\n\n one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other\n Short descriptive title (max 80 chars)\n One-line context (optional)\n \n Specific factual detail 1\n Specific factual detail 2\n \n 2-3 sentence summary of what happened and why it matters\n \n technical concept or pattern\n \n \n path/to/file\n \n 1-10 scale, 10 being critical architectural decision\n\n```\n\n**重要性评分标准：**\n\n| 评分范围 | 含义 | 示例场景 |\n|---------|------|---------|\n| 1-3 | 常规读取操作 | 读取配置文件、查看文档 |\n| 4-6 | 编辑和命令执行 | 修改代码、运行测试 |\n| 7-9 | 架构决策 | API 设计变更、依赖调整 |\n| 10 | 重大变更 | 破坏性更改、安全修复 |\n\n资料来源：[src/prompts/compression.ts:3-31](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n### 水晶 (Crystals)\n\n水晶是会话完成后的冻结快照，捕获单个会话的叙事、调用工具的关键结果、触及的文件以及提炼的经验教训。\n\n```html\n
\n Crystals are frozen snapshots of completed work. \n Each crystal captures one session's narrative, the tools invoked (key outcomes), \n files touched, and lessons surfaced — a replayable summary you keep after \n raw observations are pruned.\n
\n```\n\n**水晶数据结构：**\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| title | string | 会话标题（最多100字符） |\n| narrative | string | 3-5句完成事项叙事 |\n| decisions | array | 做出的技术决策 |\n| files | array | 创建或修改的文件路径 |\n| concepts | array | 可搜索的关键概念 |\n\n资料来源：[src/viewer/index.html:1-50](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html) 和 [src/prompts/summary.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n\n### 语义记忆与程序性记忆\n\n系统将观察记录分类存储为两种互补的记忆形式：\n\n**语义记忆 (Semantic Memory)**：存储事实性信息，基于置信度评分。\n\n```html\n
Semantic Memory
\n semFacts.slice(0, 5).forEach(function(f) {\n var conf = typeof f.confidence === 'number' ? Math.round(f.confidence * 100) : null;\n var str = typeof f.strength === 'number' ? Math.round(f.strength * 100) : null;\n });\n
\n```\n\n**程序性记忆 (Procedural Memory)**：存储可重用的操作流程，从反复出现的模式中提取。\n\n> 资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n## 操作流程\n\n### 记忆压缩流程\n\n```mermaid\ngraph TD\n A[工具调用完成] --> B[触发压缩钩子]\n B --> C[构建压缩提示词]\n C --> D[调用 LLM 生成结构化观察]\n D --> E{隐私检查}\n E -->|发现敏感信息| F[标记为 private]\n E -->|无敏感信息| G[直接存储]\n F --> H[存储观察记录]\n G --> H\n H --> I[更新时间线视图]\n```\n\n压缩提示词系统包含三类操作：\n\n| 操作 | 触发条件 | 产物 |\n|-----|---------|-----|\n| 压缩 (Compression) | 单次工具调用完成 | 单条观察记录 |\n| 摘要 (Summary) | 会话结束或手动触发 | 水晶快照 |\n| 整合 (Consolidation) | 多个相关观察积累 | 高阶洞察 |\n\n资料来源：[src/prompts/compression.ts:31-45](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n\n### 会话摘要生成\n\n```mermaid\ngraph LR\n A[观察记录集合] --> B[压缩为结构化数据]\n B --> C[构建摘要提示词]\n C --> D[LLM 生成 XML 格式摘要]\n D --> E[解析并存储为水晶]\n E --> F[供后续会话检索使用]\n```\n\n**摘要生成规则：**\n\n- 聚焦成果，而非单个工具调用\n- 突出决策及其理由\n- 列出所有创建或修改的文件\n- 概念应为可搜索术语，用于未来上下文检索\n\n资料来源：[src/prompts/summary.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n\n### 反思整合流程\n\n```mermaid\ngraph TD\n A[相关记忆簇] --> B[收集已知事实]\n B --> C[提取经验教训]\n C --> D[汇总水晶叙事]\n D --> E[构建反思提示词]\n E --> F[生成高阶洞察]\n F --> G[更新语义/程序性记忆]\n```\n\n反思操作从记忆簇中综合提炼出更高层次的见解，包含：\n\n- 已知事实 (Known Facts)：带置信度的技术事实\n- 经验教训 (Lessons Learned)：带置信度的行为准则\n- 完成工作摘要 (Completed Work Summaries)：会话叙事片段\n\n资料来源：[src/prompts/reflect.ts:1-40](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)\n\n## 隐私处理机制\n\nAgentMemory 内置敏感信息自动过滤功能，在记忆压缩前扫描输出内容。\n\n### 检测模式\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n /sk-ant-[A-Za-z0-9\\-_]{20,}/g,\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /github_pat_[A-Za-z0-9_]{22,}/g,\n /xoxb-[A-Za-z0-9\\-]+/g,\n /AKIA[0-9A-Z]{16}/g,\n /AIza[A-Za-z0-9\\-_]{35}/g,\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n /npm_[A-Za-z0-9]{36}/g,\n /glpat-[A-Za-z0-9\\-_]{20,}/g,\n];\n```\n\n### 隐私处理规则\n\n| 标签格式 | 作用 | 持久化 |\n|---------|------|--------|\n| `...` | 包裹敏感内容 | 不存储 |\n\n隐私扫描覆盖的凭证类型：\n\n| 类型 | 匹配模式示例 |\n|-----|-------------|\n| API 密钥 | `api_key=xxx...`、`secret: xxx...` |\n| Bearer 令牌 | `Bearer eyJ...` |\n| OpenAI 密钥 | `sk-proj-xxx...` |\n| Anthropic 密钥 | `sk-ant-xxx...` |\n| GitHub 令牌 | `ghp_xxx...`、`github_pat_xxx...` |\n| Slack 令牌 | `xoxb-xxx...` |\n| AWS 密钥 | `AKIAxxx...` |\n| Google API | `AIzaxxx...` |\n| NPM 令牌 | `npm_xxx...` |\n| GitLab 令牌 | `glpat-xxx...` |\n\n资料来源：[src/functions/privacy.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)\n\n## 可视化界面\n\nAgentMemory 提供 Web 查看器界面，支持多种记忆操作的交互式展示。\n\n### 时间线视图\n\n观察记录以时间线形式展示，支持分页浏览：\n\n```html\n
\n \n Page 1 of 10 (95 total)\n \n
\n```\n\n**时间线过滤类型：**\n\n- `file_read` - 文件读取\n- `file_write` - 文件写入\n- `file_edit` - 文件编辑\n- `command_run` - 命令执行\n- `search` - 搜索操作\n- `error` - 错误记录\n- `decision` - 决策记录\n\n### 记忆检索\n\n```html\n\n```\n\n支持对水晶、语义记忆、程序性记忆、经验教训等多种记忆类型的全文搜索。\n\n### 功能标志 (Feature Flags)\n\n系统支持通过 URL 参数启用或禁用特定功能：\n\n```html\n
\n ' + b.icon + '\n
\n
' + b.title + ' ' + b.keyLabel + '
\n ' + esc(b.enable) + '\n
\n
\n```\n\n资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n## 操作 API 概览\n\n基于记忆操作的核心函数接口：\n\n| 函数 | 用途 | 输入 | 输出 |\n|-----|------|-----|-----|\n| `buildCompressionPrompt` | 构建压缩提示词 | 工具调用信息 | 格式化的提示字符串 |\n| `buildSummaryPrompt` | 构建摘要提示词 | 观察记录数组 | 格式化的摘要提示 |\n| `buildReflectionPrompt` | 构建反思提示词 | 记忆簇数据 | 格式化的反思提示 |\n| `buildProceduralExtractionPrompt` | 提取程序性记忆 | 模式数组 | 格式化提取提示 |\n\n所有构建函数均位于 `src/prompts/` 目录下，采用纯函数设计，便于测试和组合使用。\n\n资料来源：[src/prompts/consolidation.ts:1-20](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n\n## 总结\n\nAgentMemory 的记忆操作构成了一个完整的信息生命周期管理系统：\n\n1. **捕获阶段**：通过压缩机制将原始工具调用转化为结构化观察\n2. **组织阶段**：通过摘要和反思机制将观察整合为水晶和高层洞察\n3. **检索阶段**：通过多种视图和搜索机制支持快速上下文召回\n4. **保护阶段**：通过隐私扫描确保敏感信息安全处理\n\n该系统设计遵循\"数据本地化、Token 高效化、外部依赖最小化\"的原则，所有记忆操作均可在本地完成，无需外部数据库支持。\n\n---\n\n\n\n## 搜索与检索\n\n### 相关页面\n\n相关主题：[记忆操作](#memory-operations), [记忆压缩与合并](#consolidation), [MCP服务器与工具](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/functions/smart-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/smart-search.ts)\n- [src/functions/search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/search.ts)\n- [src/functions/graph-retrieval.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/graph-retrieval.ts)\n- [src/state/hybrid-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/hybrid-search.ts)\n- [src/state/vector-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/vector-index.ts)\n- [src/state/search-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/search-index.ts)\n- [src/state/reranker.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/reranker.ts)\n
\n\n# 搜索与检索\n\nAgentMemory 的搜索与检索系统是整个记忆运行时的核心能力之一，负责从语义记忆、程序性记忆、关系网络等多种数据存储中高效定位并召回相关信息。该系统采用混合检索架构，结合向量相似度搜索、关键词倒排索引和图关系遍历，为 AI 编码代理提供精准的上下文召回能力。\n\n## 系统架构总览\n\nAgentMemory 的搜索系统由多个相互协作的模块组成，形成一个多层次的检索管道：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Smart Search 智能搜索]\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 H --> I[最终结果]\n```\n\n核心模块分布在两个目录层级：\n\n| 目录 | 职责 | 关键文件 |\n|------|------|----------|\n| `src/functions/` | 搜索业务逻辑与 API 封装 | `smart-search.ts`, `search.ts`, `graph-retrieval.ts` |\n| `src/state/` | 索引数据结构和检索算法实现 | `hybrid-search.ts`, `vector-index.ts`, `search-index.ts`, `reranker.ts` |\n\n## 向量索引检索\n\n向量索引是语义相似度搜索的基础设施。AgentMemory 使用向量嵌入表示语义记忆中的事实、概念和叙述文本，支持基于余弦相似度或欧氏距离的近似最近邻搜索。\n\n### 索引数据结构\n\n向量索引模块维护以下核心数据结构：\n\n- **嵌入向量存储**：将文本内容转换为高维向量并持久化存储\n- **元数据索引**：为每个向量关联来源、时间戳、置信度等元信息\n- **分区索引**：按语义类别或时间窗口对向量进行分区优化查询性能\n\n### 检索流程\n\n```mermaid\ngraph LR\n A[查询文本] --> B[嵌入模型]\n B --> C[查询向量]\n C --> D[ANN搜索]\n D --> E[候选集]\n E --> F[元数据过滤]\n F --> G[排序结果]\n```\n\n向量检索的关键参数包括：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `topK` | `number` | 返回的最相似结果数量 |\n| `minScore` | `number` | 最小相似度阈值 |\n| `filters` | `object` | 元数据过滤条件 |\n| `embeddingModel` | `string` | 指定的嵌入模型名称 |\n\n## 倒排索引检索\n\n倒排索引提供基于关键词的精确匹配能力，与向量检索形成互补。搜索索引模块维护从术语到记忆条目的映射，支持布尔查询和短语匹配。\n\n### 索引构建\n\n索引构建过程包括以下步骤：\n\n1. **文本分词**：对记忆内容进行标准化分词处理\n2. **术语提取**：识别关键词和实体名称\n3. **倒排列表构建**：建立术语到文档 ID 的映射\n4. **权重计算**：基于 TF-IDF 或 BM25 计算术语权重\n\n### 查询处理\n\n倒排索引检索支持多种查询语法：\n\n- **AND 查询**：`term1 AND term2` - 返回同时包含两个术语的结果\n- **OR 查询**：`term1 OR term2` - 返回包含任一术语的结果\n- **短语查询**：`\"exact phrase\"` - 精确匹配短语\n- **字段限定**：`field:value` - 限定搜索特定字段\n\n## 图关系检索\n\n图检索模块维护记忆条目之间的语义关系网络，支持基于关系路径的扩展检索。\n\n### 关系类型\n\nAgentMemory 中的关系包括：\n\n| 关系类型 | 描述 | 示例 |\n|----------|------|------|\n| `causes` | 因果关系 | 修改配置导致应用重启 |\n| `implements` | 实现关系 | 抽象接口被具体类实现 |\n| `depends_on` | 依赖关系 | 模块 A 依赖模块 B |\n| `related_to` | 关联关系 | 相关但非直接因果 |\n| `derived_from` | 派生关系 | 经验教训来源于具体案例 |\n\n### 图遍历算法\n\n图检索支持以下遍历策略：\n\n```mermaid\ngraph TD\n A[起点节点] --> B[直接邻居]\n A --> C[2度邻居]\n A --> D[N度可达]\n B --> E[BFS广度优先]\n C --> E\n D --> F[DFS深度优先]\n B --> G[PageRank排序]\n C --> G\n```\n\n- **广度优先搜索 (BFS)**：适合查找最近关联的记忆\n- **深度优先搜索 (DFS)**：适合探索完整的语义路径\n- **PageRank 排序**：根据关系重要性权重排序结果\n\n## 混合搜索调度\n\n混合搜索是 AgentMemory 检索系统的核心调度层，协调向量检索、倒排索引和图检索的结果融合。\n\n### 融合策略\n\n混合搜索支持多种结果融合策略：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `reciprocal_rank` | 倒数排名融合 | 多源结果互补 |\n| `compressed_score` | 加权分数融合 | 需要精确控制各源权重 |\n| `rrf_k` | 倒数排名融合因子 | 平衡精确性和多样性 |\n\n### 调度配置\n\n混合搜索的调度参数包括：\n\n```typescript\ninterface HybridSearchConfig {\n vectorWeight: number; // 向量检索权重\n keywordWeight: number; // 关键词检索权重\n graphWeight: number; // 图检索权重\n fusionStrategy: 'rrf' | 'weighted' | 'composite';\n minRelevanceScore: number; // 最低相关性阈值\n maxResults: number; // 最大返回结果数\n}\n```\n\n## 重排序器\n\n重排序器（Reranker）对候选结果进行精细化排序，提升最终结果的相关性。\n\n### 排序算法\n\n重排序器采用多信号融合排序：\n\n1. **原始相似度分数**：来自向量或关键词检索的初始分数\n2. **关系重要性**：基于图结构的节点重要性得分\n3. **时效性权重**：新近更新的记忆获得更高权重\n4. **使用频率**：高频访问的记忆获得提升\n5. **隐私敏感性**：敏感内容可能被降权或过滤\n\n### 排序公式\n\n综合排序分数计算如下：\n\n```\nfinalScore = α × vectorScore + β × keywordScore + γ × graphScore + δ × recencyScore + ε × usageScore\n```\n\n其中 `α`, `β`, `γ`, `δ`, `ε` 为可配置的权重系数，满足 `α + β + γ + δ + ε = 1`。\n\n## 隐私过滤\n\n检索系统在返回结果前必须经过隐私过滤器处理，确保敏感信息不被泄露。\n\n### 敏感信息检测\n\n隐私过滤器使用正则表达式检测敏感数据：\n\n| 模式类型 | 正则表达式特征 | 示例 |\n|----------|----------------|------|\n| API 密钥 | `api[_-]?key\\|secret\\|token` | `sk-xxxx...` |\n| Bearer 令牌 | `Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}` | `Bearer eyJ...` |\n| GitHub 令牌 | `gh[pus]_[A-Za-z0-9]{36,}` | `ghp_xxxx...` |\n| NPM 令牌 | `npm_[A-Za-z0-9]{36}` | `npm_xxxx...` |\n| JSON Web 令牌 | `eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}` | `eyJhbG...` |\n\n资料来源：[src/functions/privacy.ts:4-22]()\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[检索结果] --> B{包含敏感内容?}\n B -->|是| C[标记敏感字段]\n B -->|否| F[通过]\n C --> D{完全敏感?}\n D -->|是| E[从结果中移除]\n D -->|否| F\n E --> G[返回过滤后结果]\n F --> G\n```\n\n隐私过滤器会将 `` 标签包裹的内容完全移除，确保返回给用户的结果不包含任何凭证、密钥或个人身份信息。\n\n## 语义记忆检索\n\n语义记忆是检索系统最重要的数据来源之一，包含从观察记录中提取的事实性知识。\n\n### 语义事实结构\n\n检索到的语义事实包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `fact` | `string` | 事实内容文本 |\n| `confidence` | `number` | 置信度 (0-1) |\n| `strength` | `number` | 强度 (0-1) |\n| `extractedAt` | `timestamp` | 提取时间 |\n\n### 检索展示\n\n在 AgentMemory Viewer 界面中，语义记忆以卡片形式展示，显示置信度和强度条：\n\n```html\n\n
\n
{fact}
\n
\n
{strength}%
\n
\n```\n\n## 观察记录检索\n\n观察记录（Observations）是从代理工具调用中提取的原始记忆单元，经过压缩后存储。\n\n### 观察类型\n\n| 类型 | 描述 | 重要性范围 |\n|------|------|------------|\n| `file_read` | 文件读取 | 1-3 |\n| `file_write` | 文件写入 | 4-6 |\n| `file_edit` | 文件编辑 | 4-6 |\n| `command_run` | 命令执行 | 4-6 |\n| `error` | 错误信息 | 7-9 |\n| `decision` | 决策记录 | 7-9 |\n| `discovery` | 发现事项 | 7-9 |\n| `subagent` | 子代理调用 | 4-6 |\n\n### 压缩观察结构\n\n压缩后的观察记录格式：\n\n```xml\n\n decision\n 使用 SQLite 替代 Redis\n 缓存需求简单\n \n 数据量小于 10000 条\n 无需分布式缓存\n \n 团队决定简化架构...\n \n SQLite 嵌入式数据库\n 缓存架构简化\n \n \n src/db/cache.ts\n \n 8\n\n```\n\n资料来源：[src/prompts/compression.ts:1-40]()\n\n## 分页与过滤\n\n观察记录检索支持分页浏览和多种过滤条件。\n\n### 分页参数\n\n| 参数 | 说明 |\n|------|------|\n| `page` | 当前页码 (从 0 开始) |\n| `pageSize` | 每页条目数 |\n| `totalPages` | 总页数 |\n| `total` | 符合条件的总条目数 |\n\n### 类型过滤\n\n观察记录可按类型进行过滤：\n\n- `all` - 所有类型\n- `file_*` - 文件相关操作\n- `command` - 命令执行\n- `search` - 搜索操作\n- `web_fetch` - 网页获取\n- `conversation` - 对话记录\n- `error` - 错误信息\n- `decision` - 决策记录\n\n### 时间线视图\n\n时间线视图按时间倒序展示观察记录，每页显示固定数量的条目，适合回顾特定时间段的代理行为。\n\n## API 端点\n\nAgentMemory 提供以下检索相关的 HTTP API：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/search` | `POST` | 执行混合搜索 |\n| `/semantic` | `GET` | 获取语义记忆 |\n| `/observations` | `GET` | 获取观察记录 |\n| `/graph/neighbors` | `GET` | 获取关系邻接节点 |\n\n## 性能优化\n\n### 索引优化策略\n\n1. **增量索引**：新记忆追加而非重建全量索引\n2. **批量向量化**：多个文本批量转换减少模型调用开销\n3. **缓存机制**：热门查询结果缓存加速重复检索\n4. **分区策略**：按时间或类别分区缩小搜索范围\n\n### 查询优化\n\n- 使用近似最近邻算法减少计算量\n- 设置合理的 `topK` 和 `minScore` 阈值\n- 利用元数据过滤减少候选集大小\n- 图检索设置最大深度防止遍历爆炸\n\n## 最佳实践\n\n### 查询构造建议\n\n1. **使用精确术语**：领域特定术语可提高关键词检索准确性\n2. **组合多信号**：复杂查询建议使用混合搜索而非单一检索模式\n3. **合理设置阈值**：根据召回率和精确率需求调整 `minRelevanceScore`\n4. **利用关系扩展**：初始结果不足时可启用图关系扩展\n\n### 结果后处理\n\n1. **验证隐私合规性**：检索结果在展示前必须经过隐私过滤器\n2. **置信度排序**：高置信度结果优先展示给用户\n3. **去重处理**：合并来自不同来源的重复结果\n4. **上下文补充**：为每个结果补充相关背景信息\n\n## 相关模块\n\n- **记忆压缩**：[compression.ts](src/prompts/compression.ts) - 观察记录的压缩格式定义\n- **会话总结**：[summary.ts](src/prompts/summary.ts) - 会话摘要生成提示词\n- **反思提炼**：[reflect.ts](src/prompts/reflect.ts) - 记忆聚类的反思提示词\n- **Viewer 界面**：[index.html](src/viewer/index.html) - 检索结果的 Web 界面展示\n\n---\n\n\n\n## 记忆压缩与合并\n\n### 相关页面\n\n相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)\n- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)\n- [src/functions/compress-file.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/compress-file.ts)\n- [src/functions/replay.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/replay.ts)\n- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)\n
\n\n# 记忆压缩与合并\n\n## 概述\n\n记忆压缩与合并（Memory Compression and Consolidation）是 AgentMemory 系统中用于管理长期记忆的核心机制。该系统通过多层次的处理流程，将原始观察数据转化为结构化、可检索的高价值记忆单元，从而在保持上下文完整性的同时显著降低存储和检索开销。\n\n根据项目性能指标，该系统实现了 **92% 的 token 减少**，同时保持 **95.2% 的检索召回率（R@5）**，且无需外部数据库支持。资料来源：[website/app/opengraph-image.tsx:8-15]()\n\n## 核心设计理念\n\n### 压缩驱动的记忆生命周期\n\n```\ngraph TD\n A[原始观察 Raw Observations] --> B[压缩引擎 Compression Engine]\n B --> C[结构化观察 Compressed Observations]\n C --> D[会话摘要 Crystal]\n C --> E[经验教训 Lessons]\n C --> F[语义记忆 Semantic Memory]\n C --> G[程序记忆 Procedural Memory]\n \n style A fill:#ff6b6b\n style C fill:#4ecdc4\n style G fill:#ffe66d\n```\n\nAgentMemory 采用**压缩优先**的策略，将 AI 编码代理在会话中产生的每一次工具调用、文件操作、命令执行等原始观察数据，通过 LLM 驱动的压缩引擎提取关键信息，生成包含类型、标题、事实、叙述、概念、文件路径和重要性评分等结构化字段的观察记录。资料来源：[src/prompts/compression.ts:1-30]()\n\n### 合并驱动的记忆提炼\n\n合并机制将重复出现的模式识别并提炼为可复用的程序记忆。系统仅提取出现 2 次及以上的模式，确保提炼出的程序具有足够的实践验证。资料来源：[src/prompts/consolidation.ts:12-20]()\n\n## 压缩系统详解\n\n### 观察类型分类\n\n压缩引擎将所有观察归类为以下类型之一：\n\n| 类型 | 描述 | 典型场景 |\n|------|------|----------|\n| `file_read` | 文件读取操作 | 读取配置文件、源码 |\n| `file_write` | 文件创建操作 | 生成新文件、导出数据 |\n| `file_edit` | 文件修改操作 | 编辑代码、修改配置 |\n| `command_run` | 命令执行操作 | npm install、git commit |\n| `search` | 搜索操作 | 代码搜索、全局查找 |\n| `web_fetch` | 网页抓取 | 获取文档、API 响应 |\n| `conversation` | 对话交互 | 用户与代理的交流 |\n| `error` | 错误事件 | 异常捕获、构建失败 |\n| `decision` | 决策点 | 技术选型、架构决策 |\n| `discovery` | 发现事项 | 新工具、替代方案 |\n| `subagent` | 子代理调用 | 任务委托、并行处理 |\n| `notification` | 通知事件 | 构建完成、部署成功 |\n| `task` | 任务跟踪 | 待办事项、里程碑 |\n| `other` | 其他类型 | 不属于以上类别 |\n\n资料来源：[src/prompts/compression.ts:10-11]()\n\n### 重要性评分体系\n\n压缩输出包含 1-10 的重要性评分，用于后续存储策略决策：\n\n| 分数范围 | 含义 | 存储策略示例 |\n|----------|------|--------------|\n| 1-3 | 常规操作 | 快速遗忘、快速合并 |\n| 4-6 | 中等重要 | 标准保留周期 |\n| 7-9 | 重要决策 | 长期保留、高权重检索 |\n| 10 | 关键变更 | 永久保留、影响分析 |\n\n资料来源：[src/prompts/compression.ts:23-24]()\n\n### 压缩输出格式\n\n压缩后的观察数据采用 XML 格式输出，包含以下结构化字段：\n\n```xml\n\n file_edit\n 实现用户认证中间件\n 使用 JWT 方案替换会话认证\n \n 中间件位于 src/middleware/auth.ts\n 使用 RS256 算法进行签名验证\n 添加了 refreshToken 过期自动续期逻辑\n \n 为现有 API 添加了统一的 JWT 认证中间件，解决了多端登录状态同步问题。\n \n JWT middleware\n auth middleware\n \n \n src/middleware/auth.ts\n src/routes/api.ts\n \n 7\n\n```\n\n资料来源：[src/prompts/compression.ts:2-29]()\n\n### 文件压缩与验证\n\n`compress-file.ts` 模块提供了文件级压缩能力，包含以下验证机制：\n\n```typescript\nfunction validateCompression(original: string, compressed: string): string[] {\n // 验证标题层级完整性\n // 验证 URL 数量和内容一致性\n // 验证代码块数量和内容一致性\n}\n```\n\n验证规则确保压缩过程不会丢失关键信息：\n\n| 验证项 | 检查逻辑 |\n|--------|----------|\n| 标题层级 | 原始文件中的所有标题必须出现在压缩结果中 |\n| URL 集合 | URL 数量和内容必须完全一致 |\n| 代码块 | 代码块数量和内容必须保持不变 |\n\n资料来源：[src/functions/compress-file.ts:24-45]()\n\n## 合并系统详解\n\n### 合并类型\n\n```\ngraph LR\n A[压缩观察] --> B{合并触发条件}\n B -->|会话结束| C[会话摘要 Crystal]\n B -->|重复模式| D[程序记忆 Procedural]\n B -->|事实积累| E[语义记忆 Semantic]\n B -->|纠正记录| F[经验教训 Lessons]\n```\n\n#### 会话摘要（Crystal）\n\n会话摘要是会话级别的压缩产物，通过 `buildSummaryPrompt` 函数构建。该函数将多个压缩观察整合为单一的结构化摘要：\n\n```typescript\nexport function buildSummaryPrompt(observations: Array<{\n type: string\n title: string\n facts: string[]\n narrative: string\n files: string[]\n concepts: string[]\n}>): string\n```\n\n输出格式：\n\n```xml\n\n 会话标题\n 3-5句会话总结\n \n 关键决策1\n \n \n 修改的文件路径\n \n \n 关键概念\n \n\n```\n\n资料来源：[src/prompts/summary.ts:1-38]()\n\n#### 程序记忆（Procedural Memory）\n\n程序记忆通过 `buildProceduralExtractionPrompt` 函数提取，用于识别重复执行的模式：\n\n```typescript\nexport function buildProceduralExtractionPrompt(\n patterns: Array<{ content: string; frequency: number }>,\n): string\n```\n\n提取规则：\n- 仅提取出现 **2 次及以上** 的模式\n- 步骤描述需具体可执行\n- 触发条件需足够具体以支持自动匹配\n\n资料来源：[src/prompts/consolidation.ts:12-24]()\n\n### 经验教训系统\n\n`replay.ts` 模块包含经验教训的自动识别机制，通过正则表达式模式匹配：\n\n```typescript\nconst LESSON_PATTERNS: RegExp[] = [\n /\\b(always|never|don'?t|do not|make sure|remember to|note:|caveat:|warning:)\\b[^.\\n]{10,200}[.!\\n]/gi,\n /\\b(prefer|avoid)\\s[^.\\n]{10,200}[.!\\n]/gi,\n];\n```\n\n这些模式识别以下类型的经验：\n- **强制规则**：`always`、`never`、`make sure`\n- **否定规则**：`don't`、`do not`\n- **提醒标记**：`note:`、`caveat:`、`warning:`\n- **偏好指导**：`prefer`、`avoid`\n\n资料来源：[src/functions/replay.ts:45-48]()\n\n### Crystal 和 Lessons 的派生流程\n\n```typescript\nasync function deriveCrystalAndLessons(\n kv: StateKV,\n sessionId: string,\n project: string,\n rawObs: RawObservation[],\n compressed: CompressedObservation[],\n firstPrompt: string | undefined,\n): Promise\n```\n\n流程说明：\n\n1. **输入收集**：收集原始观察、压缩观察和首条提示\n2. **元数据提取**：从压缩观察中提取所有涉及的文件和工具\n3. **文本分离**：区分用户提示和助手响应\n4. **Crystal 生成**：创建包含时间戳的会话摘要\n5. **Lessons 提取**：应用模式匹配提取经验教训\n6. **关联存储**：将派生结果与原始会话关联\n\n资料来源：[src/functions/replay.ts:50-76]()\n\n## 数据流架构\n\n```\ngraph TD\n subgraph 输入层\n R[Raw Observations]\n F[首条提示 First Prompt]\n end\n \n subgraph 压缩层\n C[压缩引擎]\n V[验证模块]\n end\n \n subgraph 合并层\n X[Crystal 生成]\n L[Lessons 提取]\n P[Procedural 提取]\n end\n \n subgraph 存储层\n S[Sessions]\n K[Knowledge]\n end\n \n R --> C\n F --> X\n C --> V\n V -->|验证通过| X\n X --> S\n L --> K\n P --> K\n```\n\n## 隐私与安全\n\n系统在压缩和合并过程中实施严格的隐私保护措施。`privacy.ts` 模块定义了私密密文和敏感信息的识别模式：\n\n```typescript\nconst PRIVATE_TAG_RE = /[\\s\\S]*?<\\/private>/gi;\n\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n // ... 更多模式\n];\n```\n\n支持的敏感信息类型包括：\n- API 密钥和 Bearer Token\n- OpenAI、GitHub、GitLab 等平台密钥\n- AWS、Google Cloud 等云服务凭证\n- NPM、JWT 等通用认证令牌\n\n资料来源：[src/functions/privacy.ts:1-25]()\n\n## 配置与调优\n\n### 压缩提示词\n\n系统通过 `COMPRESSION_SYSTEM` 提示词指导 LLM 执行压缩任务，提示词包含：\n\n| 配置项 | 说明 |\n|--------|------|\n| 输出格式 | XML 结构化格式 |\n| 字段要求 | 标题最大 80 字符 |\n| 重要性规则 | 1-3 常规、4-6 编辑命令、7-9 架构决策、10 破坏性变更 |\n| 概念标签 | 应为可复用的搜索词 |\n| 隐私处理 | 剥离密钥、令牌、凭证 |\n\n### 合并策略\n\n| 策略 | 触发条件 | 输出 |\n|------|----------|------|\n| Crystal 生成 | 会话结束或手动触发 | 会话摘要 |\n| Procedural 提取 | 模式出现 2+ 次 | 可复用流程 |\n| Lessons 提取 | 模式匹配命中 | 经验教训 |\n| Semantic 合并 | 事实积累达到阈值 | 语义记忆 |\n\n## 最佳实践\n\n### 1. 观察记录的完整性\n\n在会话中保持工具调用的完整记录，以便压缩引擎能够提取足够的上下文信息。包含原始响应内容的观察能生成更高质量的 Crystal。\n\n### 2. 概念标签的精确性\n\n为压缩观察分配准确的 `concepts` 标签，这些标签直接影响后续检索的召回率。建议使用标准化的技术术语作为概念标签。\n\n### 3. 隐私标记的使用\n\n在原始观察中使用 `...` 标签包裹敏感内容，确保压缩流程自动剥离这些信息。\n\n### 4. Crystal 的定期复审\n\n虽然 Crystal 是自动生成的，但建议定期审查并手动强化重要的决策和发现，以提升系统学习效果。\n\n## 性能特性\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 减少 | 92% | 相比原始观察的压缩率 |\n| 检索召回率 | 95.2% (R@5) | Top-5 检索准确率 |\n| 外部依赖 | 0 | 无需外部数据库 |\n| 处理模式 | 实时 + 批量 | 支持即时压缩和后台合并 |\n\n资料来源：[website/app/opengraph-image.tsx:8-15]()\n\n## 相关模块\n\n| 模块路径 | 功能描述 |\n|----------|----------|\n| `src/prompts/compression.ts` | 压缩系统提示词定义 |\n| `src/prompts/consolidation.ts` | 合并系统提示词定义 |\n| `src/functions/compress-file.ts` | 文件级压缩与验证 |\n| `src/functions/replay.ts` | Crystal 和 Lessons 派生 |\n| `src/prompts/summary.ts` | 会话摘要提示词 |\n| `src/functions/privacy.ts` | 隐私保护与敏感信息识别 |\n\n---\n\n\n\n## MCP服务器与工具\n\n### 相关页面\n\n相关主题：[记忆操作](#memory-operations), [搜索与检索](#search-retrieval), [代理插件与集成](#agent-plugins)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx) — 展示MCP兼容代理列表及集成方式\n- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx) — 各代理的MCP配置示例\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md) — MCP包发布流程\n- [integrations/pi/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/pi/README.md) — PI扩展与MCP的关系说明\n- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx) — 安装入口及npm包信息\n
\n\n# MCP服务器与工具\n\n## 概述\n\nMCP（Model Context Protocol）服务器是 AgentMemory 的核心组件之一，它为 AI 代理提供标准化的记忆工具接口。通过 MCP 协议，AgentMemory 能够与各种 AI 代理客户端（如 Claude Desktop、Cursor、Windsurf、VS Code 等）实现无缝集成，使代理能够在对话过程中持久化存储和检索记忆。\n\nAgentMemory 的 MCP 实现包含两个层面：一是作为 MCP 服务器运行，接受代理的工具调用请求；二是通过 MCP 协议与支持该协议的各种代理客户端建立连接。资料来源：[website/components/Agents.tsx:17-21]()\n\n> \"SIX FIRST-PARTY. REST MCP-NATIVE. NATIVE PLUGINS FOR CLAUDE CODE, CODEX CLI, OPENCLAW, HERMES, PI, AND OPENHUMAN. EVERY OTHER MCP CLIENT GETS IT FOR FREE.\"\n\n## 架构设计\n\n### 协议层结构\n\nAgentMemory 的 MCP 实现采用分层架构设计：\n\n```mermaid\ngraph TD\n A[MCP客户端
Claude Desktop / Cursor / Cline等] --> B[MCP协议层]\n B --> C[AgentMemory MCP服务器]\n C --> D[REST API层]\n D --> E[记忆存储引擎]\n E --> F[SQLite/文件存储]\n \n G[原生插件
Claude Code / Codex CLI / Hermes等] --> H[直接API调用]\n H --> D\n```\n\n### MCP 服务器角色\n\nMCP 服务器在 AgentMemory 架构中承担以下职责：\n\n| 职责 | 说明 |\n|------|------|\n| 工具注册 | 将记忆操作封装为 MCP 标准工具 |\n| 请求路由 | 解析 MCP 请求并分发到对应处理函数 |\n| 响应格式化 | 将记忆数据转换为 MCP 协议格式 |\n| 连接管理 | 维护与多个客户端的会话状态 |\n\n资料来源：[website/components/Agents.tsx:22-35]()\n\n## 支持的 MCP 客户端\n\n### 一线原生插件（内置支持）\n\nAgentMemory 为以下代理提供原生插件支持：\n\n- **Claude Code** — Anthropic 官方 CLI 代理\n- **Codex CLI** — OpenAI 官方代理\n- **OpenClaw** — 开源代理\n- **Hermes** — 开源代理框架\n- **PI** — 代理框架\n- **OpenHuman** — 开源项目\n\n```mermaid\ngraph LR\n A[Claude Code] --> B[原生插件]\n A2[Codex CLI] --> B\n A3[OpenClaw] --> B\n A4[Hermes] --> B\n A5[PI] --> B\n A6[OpenHuman] --> B\n \n B --> C[agentmemory connect命令
自动配置所有插件]\n```\n\n资料来源：[website/components/Agents.tsx:17-21]()\n\n### MCP 协议客户端（开箱即用）\n\n以下客户端通过标准 MCP JSON 配置即可使用 AgentMemory：\n\n| 客户端 | 配置文件 | 特殊说明 |\n|--------|----------|----------|\n| Claude Desktop | `claude_desktop_config.json` | 标准 mcpServers 格式 |\n| Cursor | deeplink 一键连接 | 支持 mcpServers |\n| Cline | `~/.cursor/mcp.json` | 标准格式 |\n| Roo Code | `~/. Roo Code/mcp.json` | 标准格式 |\n| Windsurf | `~/.codeium/windsurf/mcp.json` | 标准格式 |\n| Gemini CLI | `~/.gemini/mcp.json` | 标准格式 |\n\n资料来源：[website/components/AgentInstall.tsx:8-25]()\n\n## 通用 MCP JSON 配置\n\n### 标准配置格式\n\n大多数 MCP 客户端使用以下配置格式：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### OpenCode 配置\n\nOpenCode 使用略有不同的配置格式：\n\n```json\n{\n \"mcp\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### VS Code 配置\n\nVS Code 的 MCP 配置文件位于 `.vscode/mcp.json`，使用 `servers` 键而非 `mcpServers`：\n\n```json\n{\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx:26-50]()\n\n## NPM 包分发\n\n### 包信息\n\nMCP 服务器作为独立的 npm 包分发：\n\n| 属性 | 值 |\n|------|-----|\n| 包名 | `@agentmemory/mcp` |\n| 入口文件 | `packages/mcp/bin.mjs` |\n| 用途 | MCP 协议服务器实现 |\n\n### 发布流程\n\nMCP 包的发布集成到 AgentMemory 的标准发布流程中：\n\n1. 更新 `packages/mcp/package.json` 中的版本号\n2. 同步主包的 `~x.y.z` 版本依赖\n3. GitHub Release 触发自动发布\n\n> \"The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance.\"\n\n资料来源：[CONTRIBUTING.md:58-64]()\n\n## MCP 工具接口\n\n### 核心工具列表\n\n通过 MCP 协议暴露的核心记忆工具：\n\n| 工具名 | 功能描述 |\n|--------|----------|\n| `memory_remember` | 存储新的记忆条目 |\n| `memory_recall` | 检索相关记忆 |\n| `memory_search` | 基于关键词搜索记忆 |\n| `memory_consolidate` | 合并和压缩记忆 |\n| `memory_action_create` | 创建待办事项 |\n\n资料来源：[src/viewer/index.html:1-10]()\n\n### 创建 Action 的 MCP 调用示例\n\n```javascript\n// MCP 工具调用格式\nmemory_action_create({ \n title: \"ship v1\", \n description: \"完成v1版本发布\",\n priority: \"high\" \n})\n```\n\n也可以通过 REST API 调用：\n\n```bash\ncurl -X POST http://localhost:3111/agentmemory/actions \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\":\"ship v1\",\"priority\":\"high\"}'\n```\n\n资料来源：[src/viewer/index.html:1-10]()\n\n## 与 PI 扩展的关系\n\nPI 代理使用独特的扩展 API 而非 MCP 协议：\n\n> \"This extension uses pi's extension API, not MCP, so it can hook directly into the agent lifecycle.\"\n\n这意味着 PI 代理可以直接访问 AgentMemory 的内部 API，绕过 MCP 协议层，获得更深入的生命周期集成能力。\n\n**共享架构优势**：尽管使用不同协议，一个本地 AgentMemory 服务器可以被 PI、PI2、Hermes、OpenClaw、Claude Code、Codex CLI 和 Gemini CLI 共享。\n\n资料来源：[integrations/pi/README.md:1-10]()\n\n## 快速开始\n\n### 安装 MCP 服务器\n\n```bash\n# 通过 npx 直接运行\nnpx -y @agentmemory/mcp\n\n# 或全局安装\nnpm install -g @agentmemory/mcp\n```\n\n### 配置客户端\n\n1. 打开目标代理的配置界面\n2. 找到 MCP 服务器配置区域\n3. 添加 AgentMemory 服务器配置\n4. 重启代理以加载新配置\n\n资料来源：[website/components/Install.tsx:1-45]()\n\n## 配置示例汇总\n\n### Claude Desktop（macOS）\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### Claude Desktop（Windows）\n\n`%APPDATA%\\Claude\\claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### Codex CLI（TOML 格式）\n\n`~/.codex/config.toml`:\n\n```toml\n[server.agentmemory]\ncommand = \"npx\"\nargs = [\"-y\", \"@agentmemory/mcp\"]\n```\n\n### Hermes（YAML 格式）\n\n`integrations/hermes/plugin.yaml`:\n\n```yaml\n# AgentMemory 插件配置\n```\n\n### OpenClaw（YAML 格式）\n\n`integrations/openclaw/plugin.yaml`:\n\n```yaml\n# AgentMemory 插件配置\n```\n\n资料来源：[website/components/AgentInstall.tsx:51-70]()\n\n## 注意事项\n\n1. **数据本地性**：所有记忆数据默认存储在本地机器上，不会上传到第三方服务。\n\n2. **共享服务器**：一个 AgentMemory 服务器实例可以同时为多个代理提供服务。\n\n3. **健康检查**：使用 `/agentmemory-status` 端点验证服务器状态，应返回 `agentmemory healthy`。\n\n4. **协议选择**：\n - 原生插件 → 直接 API 调用\n - MCP 客户端 → MCP 协议层\n - PI 代理 → 扩展 API（非 MCP）\n\n5. **版本同步**：确保 MCP 包版本与主包版本保持一致以获得最佳兼容性。\n\n资料来源：[integrations/pi/README.md:1-5]()\n\n## 相关资源\n\n- [安装指南](../安装指南.md)\n- [记忆系统架构](./记忆系统架构.md)\n- [集成目录](https://github.com/rohitg00/agentmemory/tree/main/integrations)\n- [npm 包页面](https://www.npmjs.com/package/@agentmemory/mcp)\n\n---\n\n\n\n## 代理插件与集成\n\n### 相关页面\n\n相关主题：[MCP服务器与工具](#mcp-server), [快速开始](#quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)\n- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx)\n- [integrations/openclaw/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/openclaw/README.md)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)\n
\n\n# 代理插件与集成\n\n## 概述\n\nAgentMemory 项目提供了一套完整的代理（Agent）插件与集成系统，支持六种第一方原生插件，并通过 MCP（Model Context Protocol）协议实现对其他第三方代理的广泛兼容。核心通过 `agentmemory connect ` 命令实现自动连接配置，同时支持 MCP 桥接方式和直接插件方式两种深度集成模式。\n\n项目采用统一的内存后端服务（默认运行于 `http://localhost:3111`），所有集成的代理共享相同的记忆存储、检索和检索增强生成（RAG）能力，实现跨代理的上下文一致性。\n\n## 支持的代理类型\n\n### 第一方原生插件\n\nAgentMemory 为以下六个第一方代理提供原生深度集成：\n\n| 代理名称 | 插件类型 | 连接方式 | 特点 |\n|---------|---------|---------|------|\n| Claude Code | 原生插件 | `agentmemory connect claude-code` | 完整记忆功能，Hook 深度集成 |\n| Codex CLI | 原生插件 | `agentmemory connect codex` | 完整记忆功能，Hook 深度集成 |\n| OpenClaw | 原生插件/直接插件 | `agentmemory connect openclaw` | 支持直接内存插件模式 |\n| Hermes | 原生插件 | `agentmemory connect hermes` | 完整记忆功能 |\n| PI | 原生插件 | `agentmemory connect pi` | 完整记忆功能 |\n| OpenHuman | 原生插件 | `agentmemory connect openhuman` | 完整记忆功能 |\n\n资料来源：[website/components/Agents.tsx:19-21]()\n\n### MCP 协议兼容代理\n\n除第一方插件外，AgentMemory 通过 MCP 协议实现对所有 MCP 兼容客户端的零成本接入：\n\n| 客户端 | 配置方式 | 连接难度 |\n|-------|---------|---------|\n| Claude Desktop | DeepLink 一键安装 | ⭐ |\n| Cursor | DeepLink 一键安装 | ⭐ |\n| VS Code (MCP) | mcp.json 配置文件 | ⭐ |\n| Cline | MCP JSON 配置 | ⭐⭐ |\n| Roo Code | MCP JSON 配置 | ⭐⭐ |\n| Windsurf | MCP JSON 配置 | ⭐⭐ |\n| Gemini CLI | MCP JSON 配置 | ⭐⭐ |\n| OpenCode | mcp.json (特殊格式) | ⭐⭐ |\n\n资料来源：[website/components/AgentInstall.tsx:1-150]()\n\n## 集成架构\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph \"MCP 客户端层\"\n A[Claude Code] --> B[MCP Bridge]\n C[Cursor] --> B\n D[VS Code] --> B\n E[其他 MCP 客户端] --> B\n end\n \n subgraph \"第一方插件层\"\n F[Claude Code 插件]\n G[Codex CLI 插件]\n H[OpenClaw 插件]\n I[Hermes 插件]\n J[PI 插件]\n K[OpenHuman 插件]\n end\n \n subgraph \"集成中间件\"\n L[MCP Bridge]\n M[直接插件接口]\n end\n \n subgraph \"AgentMemory 核心服务\"\n N[API Server :3111]\n O[SQLite 存储引擎]\n P[向量索引]\n Q[记忆整合引擎]\n end\n \n B --> L\n F --> M\n G --> M\n H --> M\n I --> M\n J --> M\n K --> M\n \n L --> N\n M --> N\n \n N --> O\n N --> P\n Q --> O\n```\n\n### MCP 桥接集成模式\n\nMCP 桥接模式适用于所有标准 MCP 客户端，通过 MCP JSON 配置实现连接：\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n通用 MCP JSON 配置兼容以下客户端：\n- Claude Desktop\n- Cursor\n- Cline\n- Roo Code\n- Windsurf\n- Gemini CLI\n\n资料来源：[website/components/AgentInstall.tsx:35-40]()\n\n### 直接插件集成模式\n\n对于支持插件系统的代理（如 OpenClaw），可采用直接插件模式实现更深度的集成：\n\n```json\n{\n \"plugins\": {\n \"slots\": {\n \"memory\": \"agentmemory\"\n },\n \"entries\": {\n \"agentmemory\": {\n \"enabled\": true,\n \"config\": {\n \"base_url\": \"http://localhost:3111\",\n \"token_budget\": 2000,\n \"min_confidence\": 0.5,\n \"fallback_on_error\": true,\n \"timeout_ms\": 5000\n }\n }\n }\n }\n}\n```\n\n| 配置参数 | 类型 | 默认值 | 说明 |\n|---------|------|-------|------|\n| base_url | string | http://localhost:3111 | AgentMemory 服务地址 |\n| token_budget | number | 2000 | 单次检索的最大 Token 预算 |\n| min_confidence | number | 0.5 | 最小置信度阈值 |\n| fallback_on_error | boolean | true | 服务不可用时的降级策略 |\n| timeout_ms | number | 5000 | 请求超时时间（毫秒） |\n\n资料来源：[integrations/openclaw/README.md:25-45]()\n\n## 插件机制\n\n### 技能系统（Skills）\n\nAgentMemory 的插件系统基于技能（Skills）模块化组织，每个技能封装特定功能：\n\n| 技能名称 | 功能描述 | 触发方式 |\n|---------|---------|---------|\n| recall | 长期记忆检索 | 自动 RAG / 手动调用 |\n| remember | 记忆编码与存储 | 会话结束自动触发 |\n| forget | 记忆遗忘与衰减 | 手动调用 / 自动清理 |\n| session-history | 会话历史管理 | 跨会话上下文 |\n\n资料来源：[integrations/openclaw/README.md:8-12]()\n\n### 钩子系统（Hooks）\n\nAgentMemory 通过钩子（Hooks）机制实现会话生命周期的深度集成：\n\n```mermaid\ngraph LR\n A[会话开始] --> B[before_agent_start Hook]\n B --> C[记忆检索]\n C --> D[Agent 执行]\n D --> E[Agent 结束]\n E --> F[agent_end Hook]\n F --> G[记忆整合]\n G --> H[长期存储]\n```\n\n| 钩子名称 | 触发时机 | 功能 |\n|---------|---------|------|\n| before_agent_start | Agent 启动前 | 检索相关长期记忆，构建上下文 |\n| agent_end | Agent 完成后 | 捕获对话轮次，执行记忆整合 |\n\n直接插件模式通过 `api.registerMemoryCapability({ promptBuilder })` 注册记忆能力，使代理系统能够识别 AgentMemory 作为活动内存插件。\n\n资料来源：[integrations/openclaw/README.md:47-54]()\n\n## 连接命令\n\n### 快速连接\n\n使用 `agentmemory connect` 命令可自动配置与目标代理的连接：\n\n```bash\n# 连接 Claude Code\nagentmemory connect claude-code\n\n# 连接 Codex CLI\nagentmemory connect codex\n\n# 连接 OpenClaw\nagentmemory connect openclaw\n\n# 连接 Hermes\nagentmemory connect hermes\n```\n\n该命令自动检测代理环境，生成对应的配置文件并完成必要的初始化步骤。\n\n资料来源：[website/components/Agents.tsx:19-21]()\n\n## 记忆运行时\n\n### 记忆运行时后端\n\nAgentMemory 提供统一的记忆运行时后端，所有集成的代理共享相同的记忆存储：\n\n- **语义记忆**：结构化的事实知识，支持置信度评分\n- **程序记忆**：可复用的操作步骤和流程\n- **关系记忆**：实体间的关联网络\n- **观察记录**：原始会话数据，包含工具调用和文件操作\n- **水晶（Crystals）**：会话压缩摘要，3 行长度的工作总结\n- **教训（Lessons）**：模式纠正记录，带置信度衰减机制\n- **行动（Actions）**：待跟进任务，支持状态流转（pending → active → done/blocked）\n\n资料来源：[src/viewer/index.html:150-200]()\n\n### 记忆检索配置\n\n| 参数 | 说明 | 影响 |\n|-----|------|-----|\n| token_budget | 检索结果的最大 Token 数 | 控制上下文长度 |\n| min_confidence | 检索结果的最小置信度 | 过滤低质量记忆 |\n| token_limit | 向量检索的 Token 上限 | 控制单次检索范围 |\n\n### 记忆生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> RawObservation: 会话进行中\n RawObservation --> SemanticFact: 整合引擎处理\n RawObservation --> Procedure: 重复模式提取\n RawObservation --> Crystal: 会话结束压缩\n SemanticFact --> ConfidenceDecay: 长期未使用\n Procedure --> ConfidenceDecay: 长期未使用\n Crystal --> [*]: 旧水晶被清理\n ConfidenceDecay --> [*]: 置信度归零删除\n```\n\n## 隐私与安全\n\n### 敏感信息处理\n\nAgentMemory 在存储记忆前自动扫描并过滤敏感信息：\n\n```typescript\nconst SECRET_PATTERN_SOURCES = [\n /(?:api[_-]?key|secret|token|password|credential|auth)[\\s]*[=:]\\s*[\"']?[A-Za-z0-9_\\-/.+]{20,}[\"']?/gi,\n /Bearer\\s+[A-Za-z0-9._\\-+/=]{20,}/gi,\n /sk-proj-[A-Za-z0-9\\-_]{20,}/g,\n /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\\-_]{19,}/g,\n /gh[pus]_[A-Za-z0-9]{36,}/g,\n /eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}/g,\n];\n```\n\n同时支持 `` 标签自动过滤：\n\n```xml\n\n这里的内容不会被存储\n\n```\n\n资料来源：[src/functions/privacy.ts:1-25]()\n\n## 扩展开发\n\n### 添加新的代理插件\n\n根据 CONTRIBUTING.md 的规范，添加新代理插件需要：\n\n1. **定义钩子类型**：在 `src/types.ts` 的 HookType 联合类型中添加新类型\n2. **实现钩子处理器**：在 `src/hooks/.ts` 中编写处理器逻辑\n3. **编写测试用例**：使用 Vitest 编写单元测试，验证观察记录正确写入\n\n```typescript\n// 1. 添加 HookType\ntype HookType = 'before_agent_start' | 'agent_end' | 'your_new_hook';\n\n// 2. 实现处理器 src/hooks/your_new_hook.ts\nexport async function handleYourNewHook(params: HookParams): Promise {\n // 处理逻辑\n}\n\n// 3. 编写测试\ndescribe('your_new_hook', () => {\n it('writes observation on trigger', async () => {\n // 测试断言\n });\n});\n```\n\n### 版本发布\n\n插件系统与主版本同步发布，每次版本更新需要同步修改 8 个文件：\n\n| 文件 | 修改内容 |\n|-----|---------|\n| package.json | 版本号更新 |\n| package-lock.json | 锁文件更新 |\n| plugin/.claude-plugin/plugin.json | 插件元数据 |\n| packages/mcp/package.json | MCP 包版本 |\n| src/version.ts | 版本常量定义 |\n| src/types.ts | 导出数据类型 |\n| src/functions/export-import.ts | 支持版本列表 |\n| test/export-import.test.ts | 版本断言测试 |\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n## 配置参考\n\n### Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### OpenCode 配置\n\n```json\n{\n \"mcp\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n### VS Code 配置\n\n需要在 `.vscode/mcp.json` 中使用 `servers` 键而非 `mcpServers`：\n\n```json\n{\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n}\n```\n\n资料来源：[website/components/AgentInstall.tsx:60-90]()\n\n## 总结\n\nAgentMemory 的代理插件与集成系统通过双轨制设计实现了广泛的兼容性：\n\n- **MCP 桥接模式**：一行配置即可连接任何 MCP 兼容客户端\n- **直接插件模式**：为支持的代理提供更深的集成能力\n\n所有集成共享同一个记忆后端服务，实现跨代理的上下文连续性，同时通过隐私保护机制确保敏感信息的安全。插件系统采用模块化设计，便于扩展新的代理支持和自定义钩子逻辑。\n\n---\n\n\n\n## 部署与运维\n\n### 相关页面\n\n相关主题：[快速开始](#quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)\n- [deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)\n- [deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)\n- [deploy/render/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/render/Dockerfile)\n- [deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)\n- [deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)\n- [src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n
\n\n# 部署与运维\n\n## 概述\n\nAgentMemory 是一个完整的记忆运行时系统，支持多种部署方式以满足不同场景的需求。项目提供了 Docker 容器化部署方案，覆盖本地开发、云平台托管和自托管等多种部署环境。\n\n核心服务默认运行在 **localhost:3111** 端口，提供 HTTP REST API 和 Web 可视化界面。部署架构采用前后端分离设计，后端服务处理记忆存储和检索，前端通过静态资源提供服务。\n\n## 部署架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[客户端] -->|HTTP API| B[AgentMemory 服务 :3111]\n B --> C[SQLite 数据库]\n B --> D[语义记忆存储]\n B --> E[程序记忆存储]\n B --> F[时序图谱存储]\n \n G[Web 查看器] --> B\n \n H[记忆动作系统] --> B\n \n I[MCP 协议接口] --> B\n```\n\n| 组件 | 说明 | 默认端口 |\n|------|------|----------|\n| REST API | 记忆 CRUD 操作接口 | 3111 |\n| Web 查看器 | 可视化记忆面板 | 3111 |\n| SQLite 存储 | 本地持久化数据库 | - |\n| MCP 服务 | 模型上下文协议支持 | - |\n\n### 服务端口配置\n\n服务默认监听 **3111** 端口，Web 查看器通过 `src/viewer/server.ts` 启动静态文件服务器。资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n\n```typescript\n// 端口配置通过环境变量或默认值设置\nconst PORT = process.env.PORT || 3111;\n```\n\n## Docker 部署\n\n### 多平台 Dockerfile\n\n项目为不同部署平台提供了优化的 Dockerfile 配置：\n\n| 平台 | Dockerfile 路径 | 特点 |\n|------|-----------------|------|\n| Fly.io | deploy/fly/Dockerfile | 轻量级多阶段构建 |\n| Railway | deploy/railway/Dockerfile | 标准 Node.js 镜像 |\n| Render | deploy/render/Dockerfile | 兼容 Render 平台 |\n| Coolify | deploy/coolify/Dockerfile | 自托管优化 |\n\n#### Fly.io Dockerfile\n\n```dockerfile\n# deploy/fly/Dockerfile\nFROM node:20-alpine\n\nWORKDIR /app\n\n# 复制 package 文件\nCOPY package*.json ./\n\n# 安装依赖\nRUN npm ci --only=production\n\n# 复制应用代码\nCOPY dist ./dist\nCOPY src/viewer ./src/viewer\n\n# 暴露端口\nEXPOSE 3111\n\n# 健康检查\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n CMD wget --no-verbose --tries=1 --spider http://localhost:3111/health || exit 1\n\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)\n\n#### Railway Dockerfile\n\n```dockerfile\n# deploy/railway/Dockerfile\nFROM node:20-slim\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci\n\nCOPY . .\nRUN npm run build\n\nEXPOSE 3111\n\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)\n\n#### Coolify Dockerfile\n\n```dockerfile\n# deploy/coolify/Dockerfile\nFROM node:20-alpine\n\nRUN apk add --no-cache dumb-init\n\nWORKDIR /app\n\nCOPY package*.json ./\nRUN npm ci --only=production && npm cache clean --force\n\nCOPY dist ./dist\nCOPY src/viewer ./src/viewer\n\nEXPOSE 3111\n\nUSER node\n\nENTRYPOINT [\"dumb-init\", \"--\"]\nCMD [\"node\", \"dist/index.js\"]\n```\n\n资料来源：[deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)\n\n### 镜像构建\n\n```bash\n# 构建本地镜像\ndocker build -t agentmemory:latest .\n\n# 带平台指定构建\ndocker buildx build --platform linux/amd64,linux/arm64 -t agentmemory:latest .\n```\n\n## Docker Compose 部署\n\n### 本地开发环境\n\n项目根目录的 `docker-compose.yml` 提供了开箱即用的本地部署配置：\n\n```yaml\n# docker-compose.yml\nversion: '3.8'\n\nservices:\n agentmemory:\n build:\n context: .\n dockerfile: Dockerfile\n ports:\n - \"3111:3111\"\n environment:\n - NODE_ENV=production\n - PORT=3111\n - DATA_DIR=/data\n volumes:\n - agentmemory-data:/data\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"wget\", \"--no-verbose\", \"--tries=1\", \"--spider\", \"http://localhost:3111/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 10s\n\nvolumes:\n agentmemory-data:\n driver: local\n```\n\n资料来源：[docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)\n\n### Fly.io 部署配置\n\n```yaml\n# deploy/fly/docker-compose.yml\nservices:\n agentmemory:\n build:\n context: ../..\n dockerfile: deploy/fly/Dockerfile\n ports:\n - -3111:3111\n env_file:\n - .env\n volumes:\n - agentmemory-data:/data\n restart: always\n\nvolumes:\n agentmemory-data:\n name: agentmemory_data\n```\n\n资料来源：[deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)\n\n### 启动命令\n\n```bash\n# 启动服务\ndocker-compose up -d\n\n# 查看日志\ndocker-compose logs -f agentmemory\n\n# 停止服务\ndocker-compose down\n\n# 重建并启动\ndocker-compose up -d --build\n```\n\n## 环境变量配置\n\n### 核心配置项\n\n| 环境变量 | 默认值 | 说明 |\n|----------|--------|------|\n| `PORT` | 3111 | 服务监听端口 |\n| `NODE_ENV` | production | 运行环境 |\n| `DATA_DIR` | ./data | 数据存储目录 |\n| `LOG_LEVEL` | info | 日志级别 |\n| `MAX_MEMORY_SIZE` | - | 最大记忆存储大小 |\n| `DB_PATH` | - | SQLite 数据库路径 |\n\n### 安全配置\n\n```bash\n# 设置管理员令牌\nexport ADMIN_TOKEN=your-secure-token\n\n# 配置 CORS 策略\nexport CORS_ORIGINS=https://your-domain.com\n\n# 启用 SSL\nexport HTTPS_ENABLED=true\nexport SSL_CERT_PATH=/path/to/cert.pem\nexport SSL_KEY_PATH=/path/to/key.pem\n```\n\n## Web 查看器运维\n\n### 静态资源服务\n\nWeb 查看器通过 `src/viewer/server.ts` 提供可视化界面：\n\n```mermaid\ngraph LR\n A[浏览器] -->|HTTP| B[查看器服务器]\n B --> C[index.html]\n B --> D[CSS/JS 资源]\n B --> E[API 数据]\n```\n\n资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)\n\n### 查看器功能\n\nWeb 界面 (`src/viewer/index.html`) 提供以下运维功能：\n\n- **记忆概览**：查看语义记忆、程序记忆、关系图谱\n- **特征标志**：管理功能开关和实验性功能\n- **行动追踪**：监控待处理任务和决策\n- **会话历史**：查看压缩后的观察记录\n\n资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)\n\n### 界面渲染逻辑\n\n```javascript\n// 查看器渲染核心逻辑\nfunction renderFlags(flags) {\n const pills = flags.map(b => \n `${b.icon} ${b.title}`\n ).join('');\n \n const html = `\n \n `;\n \n host.innerHTML = html;\n}\n```\n\n## 健康检查与监控\n\n### 健康检查端点\n\n```bash\n# 检查服务健康状态\ncurl http://localhost:3111/health\n\n# 预期响应\n{\n \"status\": \"ok\",\n \"timestamp\": \"2026-01-01T00:00:00.000Z\",\n \"uptime\": 3600\n}\n```\n\n### Docker 健康检查配置\n\n```yaml\nhealthcheck:\n test: [\"CMD\", \"wget\", \"--no-verbose\", \"--tries=1\", \"--spider\", \"http://localhost:3111/health\"]\n interval: 30s # 检查间隔\n timeout: 10s # 超时时间\n retries: 3 # 重试次数\n start_period: 10s # 启动等待时间\n```\n\n### 容器状态监控\n\n```bash\n# 查看容器健康状态\ndocker inspect --format='{{.State.Health.Status}}' agentmemory-agentmemory-1\n\n# 查看资源使用\ndocker stats agentmemory-agentmemory-1\n\n# 查看详细日志\ndocker logs agentmemory-agentmemory-1 --tail 100 --details\n```\n\n## 平台特定部署\n\n### Fly.io 部署\n\n```bash\n# 安装 Fly CLI\ncurl -L https://fly.io/install.sh | sh\n\n# 登录\nfly auth login\n\n# 部署应用\nfly deploy --config deploy/fly/docker-compose.yml\n\n# 查看部署状态\nfly status\n\n# 打开应用\nfly open\n```\n\n### Railway 部署\n\n1. 连接 GitHub 仓库\n2. 选择 `deploy/railway/Dockerfile`\n3. 配置环境变量\n4. Railway 自动构建和部署\n\n### Render 部署\n\n1. 创建新的 Web Service\n2. 连接 GitHub 仓库\n3. 设置构建命令：`npm run build`\n4. 设置启动命令：`node dist/index.js`\n5. 配置环境变量\n\n### Coolify 自托管\n\n1. 添加新项目\n2. 配置 Dockerfiles 路径：`deploy/coolify/Dockerfile`\n3. 设置端口映射：`3111:3111`\n4. 配置持久化存储卷\n\n## 数据持久化\n\n### 存储卷配置\n\n```yaml\nvolumes:\n agentmemory-data:\n driver: local\n driver_opts:\n type: none\n o: bind\n device: /path/to/host/data\n```\n\n### 备份策略\n\n```bash\n# 备份数据库\ndocker cp agentmemory:/data/memory.db ./backup-$(date +%Y%m%d).db\n\n# 备份整个数据目录\ntar -czf agentmemory-data-$(date +%Y%m%d).tar.gz ./data/\n\n# 恢复数据\ndocker cp ./backup.db agentmemory:/data/memory.db\n```\n\n## 日志管理\n\n### 查看日志\n\n```bash\n# 实时日志\ndocker-compose logs -f\n\n# 错误日志\ndocker-compose logs --since 1h --filter \"level=error\"\n\n# 结构化日志输出\ndocker logs -f agentmemory --tail 200 --timestamps\n```\n\n### 日志级别\n\n| 级别 | 说明 | 使用场景 |\n|------|------|----------|\n| error | 错误信息 | 故障排查 |\n| warn | 警告信息 | 性能问题 |\n| info | 一般信息 | 正常运行监控 |\n| debug | 调试信息 | 开发调试 |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 服务无法启动 | 端口被占用 | 修改 PORT 环境变量 |\n| 数据库连接失败 | 权限问题 | 检查卷挂载权限 |\n| 健康检查失败 | 网络问题 | 检查容器网络配置 |\n| 前端加载失败 | 静态资源缺失 | 检查构建产物 |\n\n### 调试命令\n\n```bash\n# 进入容器调试\ndocker exec -it agentmemory sh\n\n# 检查网络连通性\ndocker exec agentmemory wget -O- http://localhost:3111/health\n\n# 检查文件权限\ndocker exec agentmemory ls -la /data\n\n# 验证配置\ndocker exec agentmemory env | grep -E \"PORT|DATA_DIR\"\n```\n\n## 安全建议\n\n### 生产环境配置\n\n1. **启用 TLS/SSL**：使用反向代理或配置 HTTPS\n2. **限制 CORS**：设置 `CORS_ORIGINS` 为可信域名\n3. **配置认证**：启用 API 令牌认证\n4. **定期备份**：配置自动化备份策略\n5. **监控告警**：设置资源使用和错误率告警\n\n### 网络安全\n\n```bash\n# 使用 Docker 网络隔离\ndocker network create --driver bridge agentmemory-net\n\n# 限制容器能力\ndocker run --cap-drop=ALL --security-opt=no-new-privileges \\\n agentmemory:latest\n```\n\n## 扩展运维\n\n### 水平扩展\n\n```yaml\nservices:\n agentmemory:\n deploy:\n replicas: 2\n # 需要外部负载均衡器配合\n```\n\n### 资源限制\n\n```yaml\ndeploy:\n resources:\n limits:\n cpus: '1'\n memory: 1G\n reservations:\n cpus: '0.5'\n memory: 512M\n```\n\n## 总结\n\nAgentMemory 提供灵活的部署方案，支持从本地开发到云端生产环境的全场景覆盖。通过 Docker 容器化和标准化的配置文件，用户可以在 Fly.io、Railway、Render、Coolify 等主流平台快速部署服务。内置的健康检查、日志管理和 Web 查看器功能为运维工作提供了便捷的监控和调试手段。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rohitg00/agentmemory\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Viewer tab bar is vertically clipped in the web UI。\n\n## 1. 安装坑 · 来源证据：Viewer tab bar is vertically clipped in the web UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：npm installs anthropic dependencies\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.9.14 — CLI installer first + agentmemory stop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.9.15 — DevEx overhaul\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.9.8 — local fallback tools/list returns 7 not 4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor\n\n## 8. 配置坑 · 来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\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:1166408297 | https://github.com/rohitg00/agentmemory | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c1b3cc10454e4fd09921e3748ad82305 | https://github.com/rohitg00/agentmemory/issues/433 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Support Ollama as a native LLM provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Ollama as a native LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c87cfb919d5049289e2beec7660ffcf0 | https://github.com/rohitg00/agentmemory/issues/232 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1bade4c29c91471284081588c913e17d | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.10 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_690933973fcf4eb5b034ab92a3c00d23 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.11 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dd621c8f5654b1f882800d15964ad46 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.9.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.13\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0eb3c158e9474ea95f58d6b01d4d0b | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf5c1b128a5e4e30bc8788b1fe501ce5 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.9.9 — pinned slot injection + MiniMax env loader\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.9 — pinned slot injection + MiniMax env loader\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e243f84c706f4fcc9bfe7f73f8467ffc | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.9 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:1166408297 | https://github.com/rohitg00/agentmemory | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | 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项目：rohitg00/agentmemory\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Viewer tab bar is vertically clipped in the web UI。\n\n## 1. 安装坑 · 来源证据：Viewer tab bar is vertically clipped in the web UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：npm installs anthropic dependencies\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.9.14 — CLI installer first + agentmemory stop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.9.15 — DevEx overhaul\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.9.8 — local fallback tools/list returns 7 not 4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor\n\n## 8. 配置坑 · 来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\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:1166408297 | https://github.com/rohitg00/agentmemory | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c1b3cc10454e4fd09921e3748ad82305 | https://github.com/rohitg00/agentmemory/issues/433 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Support Ollama as a native LLM provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Ollama as a native LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c87cfb919d5049289e2beec7660ffcf0 | https://github.com/rohitg00/agentmemory/issues/232 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1bade4c29c91471284081588c913e17d | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.10 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_690933973fcf4eb5b034ab92a3c00d23 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.11 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dd621c8f5654b1f882800d15964ad46 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.9.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.13\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0eb3c158e9474ea95f58d6b01d4d0b | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf5c1b128a5e4e30bc8788b1fe501ce5 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.9.9 — pinned slot injection + MiniMax env loader\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.9 — pinned slot injection + MiniMax env loader\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e243f84c706f4fcc9bfe7f73f8467ffc | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.9 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:1166408297 | https://github.com/rohitg00/agentmemory | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agentmemory - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agentmemory 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. data-flow：数据流与处理。围绕“数据流与处理”模拟一次用户任务，不展示安装或运行结果。\n5. memory-operations：记忆操作。围绕“记忆操作”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. data-flow\n输入：用户提供的“数据流与处理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. memory-operations\n输入：用户提供的“记忆操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / data-flow：Step 4 必须围绕“数据流与处理”形成一个小中间产物，并等待用户确认。\n- Step 5 / memory-operations：Step 5 必须围绕“记忆操作”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rohitg00/agentmemory\n- https://github.com/rohitg00/agentmemory#readme\n- plugin/skills/forget/SKILL.md\n- plugin/skills/recall/SKILL.md\n- plugin/skills/remember/SKILL.md\n- plugin/skills/session-history/SKILL.md\n- README.md\n- DESIGN.md\n- package.json\n- src/cli.ts\n- examples/python/quickstart.py\n- examples/python/observe_and_recall.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agentmemory 的核心服务。\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项目：rohitg00/agentmemory\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @agentmemory/agentmemory\n```\n\n来源：https://github.com/rohitg00/agentmemory#readme\n\n## 来源\n\n- repo: https://github.com/rohitg00/agentmemory\n- docs: https://github.com/rohitg00/agentmemory#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_8373d32d3bb24530a7e290750da6284c" }