# https://github.com/rohitg00/agentmemory 项目说明书

生成时间：2026-05-16 22:32:59 UTC

## 目录

- [项目介绍](#intro)
- [快速开始](#quickstart)
- [系统架构](#architecture)
- [数据流与处理](#data-flow)
- [记忆操作](#memory-operations)
- [搜索与检索](#search-retrieval)
- [记忆压缩与合并](#consolidation)
- [MCP服务器与工具](#mcp-server)
- [代理插件与集成](#agent-plugins)
- [部署与运维](#deployment)

<a id='intro'></a>

## 项目介绍

### 相关页面

相关主题：[快速开始](#quickstart), [系统架构](#architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)
- [website/components/Features.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Features.tsx)
- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)
- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)
</details>

# 项目介绍

## 概述

AgentMemory 是一个完整的**内存运行时系统**（Complete Memory Runtime），专为 AI 编码代理设计。与传统的向量存储库或简单记忆库不同，AgentMemory 提供从**捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）到联邦（Federate）**的完整记忆生命周期管理能力。资料来源：[website/components/Features.tsx]()

该项目的核心目标是让 AI 代理具备跨会话的持久记忆能力，使代理能够：

- 记住文件修改的具体细节
- 追踪决策历史和变更理由
- 维护任务状态和阻塞关系
- 快速恢复工作上下文

AgentMemory 实现了 **95.2% 的检索召回率（R@5）**，同时减少 **92% 的 token 使用量**，且**不依赖外部数据库**。资料来源：[website/app/opengraph-image.tsx]()

## 核心架构

AgentMemory 采用客户端-服务器架构，运行在本地机器上，数据完全本地存储。

```mermaid
graph TD
    subgraph 客户端层
        A[Claude Code] -->|MCP| M[AgentMemory Server]
        B[Codex CLI] -->|MCP| M
        C[OpenClaw] -->|MCP| M
        D[Hermes] -->|MCP| M
        E[PI] -->|MCP| M
        F[OpenHuman] -->|MCP| M
        G[其他 MCP 客户端] -->|MCP| M
    end
    
    subgraph 服务端
        M -->|存储| DB[(本地存储)]
        M -->|API| H[HTTP API :3111]
    end
    
    subgraph 功能模块
        M --> OBS[观察记录模块]
        M --> SEM[语义记忆模块]
        M --> ACT[行动追踪模块]
        M --> CRY[晶体化模块]
        M --> PRIV[隐私过滤模块]
    end
```

## 主要功能模块

### 1. 观察记录（Observations）

观察记录是 AgentMemory 的基础数据单元，用于捕获代理的每一次关键操作。资料来源：[src/prompts/compression.ts]()

观察记录支持多种类型：

| 类型 | 说明 | 重要性等级 |
|------|------|-----------|
| `file_read` | 文件读取操作 | 1-3 |
| `file_write` | 文件写入操作 | 4-6 |
| `file_edit` | 文件编辑操作 | 4-6 |
| `command_run` | 命令执行操作 | 4-6 |
| `search` | 搜索操作 | 1-3 |
| `web_fetch` | 网页抓取 | 1-3 |
| `conversation` | 对话内容 | 1-3 |
| `error` | 错误信息 | 4-6 |
| `decision` | 决策记录 | 7-9 |
| `discovery` | 发现/洞察 | 7-9 |
| `subagent` | 子代理调用 | 4-6 |
| `notification` | 通知事件 | 1-3 |
| `task` | 任务状态 | 4-6 |
| `other` | 其他类型 | 1-3 |

每条观察记录包含以下结构化字段：

```xml
<observation>
  <type>操作类型</type>
  <title>简短描述标题（最多80字符）</title>
  <subtitle>一行上下文（可选）</subtitle>
  <facts>
    <fact>具体事实1</fact>
    <fact>具体事实2</fact>
  </facts>
  <narrative>2-3句总结</narrative>
  <concepts>
    <concept>技术概念或模式</concept>
  </concepts>
  <files>
    <file>文件路径</file>
  </files>
  <importance>1-10重要性评分</importance>
</observation>
```

### 2. 语义记忆（Semantic Memory）

语义记忆是将观察记录中的具体事实进行整合后形成的抽象知识表示。资料来源：[src/viewer/index.html]()

语义记忆具有以下特性：

- **置信度（Confidence）**：表示该记忆被确认的程度
- **强度（Strength）**：表示该记忆在记忆网络中的权重
- **自动提取**：从长时间会话中自动归纳

```mermaid
graph LR
    O1[文件读取观察] --> SEM[语义记忆网络]
    O2[文件编辑观察] --> SEM
    O3[决策观察] --> SEM
    SEM --> CON1[概念节点]
    SEM --> CON2[概念节点]
    SEM --> CON3[概念节点]
```

### 3. 行动追踪（Actions）

行动是代理在会话期间产生的后续跟进项，用于确保重要事项不会被遗漏。资料来源：[src/viewer/index.html]()

行动具有完整的状态生命周期：

```mermaid
graph LR
    A[pending 待处理] --> B[active 活动中]
    B --> C[done 已完成]
    B --> D[blocked 已阻塞]
```

行动可以通过以下三种方式创建：

| 方式 | 命令/方法 | 示例 |
|------|-----------|------|
| MCP 工具 | `memory_action_create` | `memory_action_create { title, description, priority }` |
| HTTP API | POST 请求 | `curl -X POST http://localhost:3111/agentmemory/actions` |
| 自动提取 | 会话钩子 | 从长会话正文中自动识别 |

### 4. 晶体化（Crystals）

晶体是完成工作的冻结快照，通过 `memory_crystallize` 命令或 JSONL 导入时自动创建。资料来源：[src/viewer/index.html]()

每个晶体包含：

- 会话叙事摘要
- 调用的关键工具及其结果
- 修改的文件列表
- 经验教训

晶体是压缩的行动摘要——每个会话发生事件的 3 行摘要，用于为下一个会话提供快速上下文，而无需重新阅读所有内容。

### 5. 隐私保护（Privacy）

AgentMemory 内置了强大的隐私过滤功能，确保敏感信息不会被意外记录。资料来源：[src/functions/privacy.ts]()

支持的隐私标签格式：

```xml
<private>
敏感内容
</private>
```

自动检测的敏感模式包括：

| 模式类型 | 匹配示例 |
|----------|----------|
| API 密钥 | `api_key`, `secret`, `token`, `credential` |
| Bearer 令牌 | `Bearer xxxxx...` |
| OpenAI 密钥 | `sk-proj-...` |
| Anthropic 密钥 | `sk-ant-...` |
| GitHub 令牌 | `ghp_...`, `github_pat_...` |
| 云服务商密钥 | `xoxb-...`, `AKIA...`, `AIza...` |
| NPM 令牌 | `npm_...` |
| GitLab 令牌 | `glpat-...` |

## 支持的代理客户端

AgentMemory 支持多种第一方插件和 MCP 原生客户端。资料来源：[website/components/Agents.tsx]()

### 第一方支持的代理

| 代理名称 | 来源 | 说明 |
|----------|------|------|
| Claude Code | Anthropic | Anthropic 官方 CLI 工具 |
| Codex CLI | OpenAI | OpenAI 命令行编码代理 |
| OpenClaw | OpenClaw | 开源编码代理 |
| Hermes | Hermes | 自定义代理方案 |
| PI | Personal Intelligence | 个人智能助手 |
| OpenHuman | OpenHuman | 开放人类项目 |

### MCP 原生支持

对于其他 MCP 客户端，AgentMemory 提供自动连接能力：

```bash
agentmemory connect <agent>
```

此命令会自动配置并连接所有支持的 MCP 客户端。

## 安装与部署

### 快速安装

AgentMemory 可通过 npm 直接安装：

```bash
npm install @agentmemory/agentmemory
```

或使用 npx 快速启动：

```bash
npx agentmemory
```

服务默认运行在 **http://localhost:3111** 端口。资料来源：[website/components/Install.tsx]()

### 架构特性

AgentMemory 的核心设计原则：

| 特性 | 说明 |
|------|------|
| 本地运行 | 在用户机器上运行，无需云服务 |
| 数据本地存储 | 所有数据保留在本地，不上传 |
| 多模型支持 | 支持 Anthropic、Gemini、MiniMax、OpenRouter |
| MCP 协议 | 标准化 Model Context Protocol 接口 |
| 自包含 | 零外部数据库依赖 |

## API 端点

AgentMemory 提供 HTTP REST API 用于与外部系统集成：

| 端点 | 方法 | 用途 |
|------|------|------|
| `/agentmemory/actions` | POST | 创建行动 |
| `/agentmemory/sessions` | GET | 获取会话列表 |
| `/agentmemory/audit` | GET | 获取审计日志 |

### API 调用示例

```bash
# 创建行动
curl -X POST http://localhost:3111/agentmemory/actions \
  -H 'Content-Type: application/json' \
  -d '{"title":"ship v1","priority":"high"}'
```

## 摘要生成系统

AgentMemory 包含会话摘要生成功能，用于将多个观察记录整合为简洁的会话摘要。资料来源：[src/prompts/summary.ts]()

摘要输出格式：

```xml
<summary>
  <title>会话标题（最多100字符）</title>
  <narrative>3-5句成就叙事</narrative>
  <decisions>
    <decision>关键决策1</decision>
  </decisions>
  <files>
    <file>修改的文件路径</file>
  </files>
  <concepts>
    <concept>关键概念</concept>
  </concepts>
</summary>
```

摘要系统规则：

- 聚焦于成果而非单个工具调用
- 突出决策及其理由
- 列出所有创建或修改的文件
- 概念应为可搜索的术语，便于未来上下文检索

## 技术栈

| 组件 | 技术 |
|------|------|
| 服务器 | Node.js / TypeScript |
| 客户端协议 | MCP (Model Context Protocol) |
| 数据存储 | 本地文件系统 |
| 运行时端口 | 3111 (默认) |
| 包管理 | npm |
| 开源协议 | Apache-2.0 |

## 总结

AgentMemory 是一个专为 AI 编码代理设计的完整内存运行时，通过 MCP 协议与各类代理客户端集成。它提供了从原始观察记录到语义记忆、再到晶体化摘要的完整数据生命周期管理，同时内置隐私保护机制确保敏感信息安全。项目采用本地优先设计，数据完全存储在用户本地，支持多种 AI 模型和代理客户端，是构建具有持久记忆能力的 AI 辅助开发环境的基础设施。

---

<a id='quickstart'></a>

## 快速开始

### 相关页面

相关主题：[项目介绍](#intro), [MCP服务器与工具](#mcp-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli.ts](https://github.com/rohitg00/agentmemory/blob/main/src/cli.ts)
- [examples/python/observe_and_recall.py](https://github.com/rohitg00/agentmemory/blob/main/examples/python/observe_and_recall.py)
- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx)
- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)
</details>

# 快速开始

## 概述

AgentMemory 是一个完整的内存运行时系统，专为 AI 编码代理设计。它提供了**捕获（Capture）**、**召回（Recall）**、**整合（Consolidate）**、**观察（Observe）** 和 **联邦（Federate）** 五项核心能力，使 AI 代理能够在多个会话之间保持上下文连贯性。

默认服务器端口为 **3111**，通过 REST API 和 MCP（Model Context Protocol）两种方式提供服务。

## 环境要求

| 要求 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | >= 20 | 运行服务器的核心依赖 |
| npm | 内置于 Node | 包管理器 |
| 模型提供商 | Anthropic / Gemini / MiniMax / OpenRouter | 支持多种 LLM 后端 |

## 安装方式

### 全局安装（推荐）

```bash
npm install -g @agentmemory/agentmemory
```

### 本地安装

```bash
npm install @agentmemory/agentmemory
```

安装完成后，可通过 `agentmemory connect <agent>` 命令自动连接支持的代理。资料来源：[website/components/Install.tsx]()

### MCP 客户端配置

AgentMemory 支持多种 MCP 客户端的通用 JSON 配置方式：

| 客户端 | 配置文件位置 | 特点 |
|--------|--------------|------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 mcpServers 格式 |
| Cursor | Deep Link 一键安装 | 自动化配置 |
| Cline | `.cline/mcp_settings.json` | mcpServers 格式 |
| Roo Code | `.roo/mcp_settings.json` | mcpServers 格式 |
| WindSurf | 配置文件 | mcpServers 格式 |
| Gemini CLI | 配置文件 | mcpServers 格式 |

通用 MCP JSON 配置示例：

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "agentmemory",
      "args": ["mcp"]
    }
  }
}
```

资料来源：[website/components/AgentInstall.tsx]()

## 启动服务

### 基本启动

```bash
agentmemory serve
```

服务器将在 `http://localhost:3111` 启动，提供以下核心端点：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/sessions` | GET/POST | 会话管理 |
| `/observations` | GET/POST | 观察记录 CRUD |
| `/actions` | GET/POST | 行动任务跟踪 |
| `/audit` | GET | 审计日志查询 |
| `/crystals` | GET | 压缩后的会话摘要 |
| `/timeline` | GET | 时间线视图数据 |

### 环境变量配置

创建 `.env` 文件配置可选参数：

```bash
# 模型配置
ANTHROPIC_API_KEY=sk-...
MODEL_PROVIDER=anthropic

# 服务器配置
PORT=3111

# 存储配置
DATA_DIR=./data
```

## 核心概念

### 观察（Observations）

观察是 AgentMemory 的基本记忆单元，记录代理在会话中执行的操作和关键事件。每个观察包含以下结构：

```xml
<observation>
  <type>file_edit | command_run | search | error | decision | discovery | ...</type>
  <title>简短描述（最多80字符）</title>
  <facts>
    <fact>具体事实细节</fact>
  </facts>
  <narrative>2-3句总结</narrative>
  <files>
    <file>路径/to/文件</file>
  </files>
  <importance>1-10 重要性评分</importance>
</observation>
```

重要性评分标准：
- **1-3**：日常读取操作
- **4-6**：编辑和命令执行
- **7-9**：架构决策
- **10**：破坏性变更

资料来源：[src/prompts/compression.ts]()

### 水晶（Crystals）

水晶是压缩后的会话摘要快照，包含一个会话的叙事、调用过的工具（关键结果）、访问过的文件以及学到的经验教训。在 JSONL 导入时自动创建，或通过 `memory_crystallize` 手动生成。

```xml
<summary>
  <title>会话标题（最多100字符）</title>
  <narrative>3-5句完成的工作叙事</narrative>
  <decisions>
    <decision>做出的关键技术决策</decision>
  </decisions>
  <files>
    <file>修改的路径</file>
  </files>
  <concepts>
    <concept>会话中的关键概念</concept>
  </concepts>
</summary>
```

资料来源：[src/prompts/summary.ts]()

### 行动（Actions）

行动是代理在会话中发现的待办事项，包括需要重新访问的决策、需要检查的文件、等待输入的任务等。状态流转为：pending → active → done/blocked。

创建方式：

```bash
# MCP 工具方式
memory_action_create { "title": "ship v1", "priority": "high" }

# Curl 方式
curl -X POST http://localhost:3111/agentmemory/actions \
  -H 'Content-Type: application/json' \
  -d '{"title":"ship v1","priority":"high"}'
```

资料来源：[src/viewer/index.html]()

## 工作流程

```mermaid
graph TD
    A[启动 AgentMemory] --> B[连接代理]
    B --> C[创建会话]
    C --> D[执行操作]
    D --> E{触发钩子}
    E -->|工具调用| F[压缩观察]
    E -->|长会话体| G[自动提取行动]
    E -->|会话结束| H[生成水晶摘要]
    F --> I[存储到记忆库]
    G --> I
    H --> I
    I --> J[下次会话召回上下文]
```

## API 使用示例

### 记录观察

```bash
curl -X POST http://localhost:3111/observations \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "file_write",
    "title": "Create user authentication module",
    "files": ["src/auth/login.ts"],
    "importance": 7
  }'
```

### 查询记忆

```python
import requests

# 搜索相关观察
response = requests.get(
    'http://localhost:3111/observations',
    params={'query': 'authentication', 'limit': 10}
)
memories = response.json()
```

### 获取会话时间线

```bash
curl "http://localhost:3111/timeline?session_id=abc123&page=0"
```

## 查看器界面

AgentMemory 提供内置 Web 查看器，可通过浏览器访问 `http://localhost:3111` 查看：

- **Feature Flags**：功能开关管理
- **Crystals**：压缩摘要列表，支持搜索
- **Actions**：行动任务看板
- **Timeline**：时间线视图，支持分页
- **Activity**：活动概览和审计日志

资料来源：[src/viewer/index.html]()

## 代理集成

AgentMemory 原生支持以下第一方代理插件：

| 代理 | 说明 |
|------|------|
| Claude Code | Anthropic 官方 CLI |
| Codex CLI | OpenAI 命令行工具 |
| OpenClaw | 开源代理框架 |
| Hermes | 定制化代理 |
| PI | 专用代理 |
| OpenHuman | 人类增强代理 |

其他所有 MCP 客户端均可通过标准 MCP JSON 配置免费接入。

资料来源：[website/components/Agents.tsx]()

## 性能指标

| 指标 | 数值 | 说明 |
|------|------|------|
| 检索 R@5 | 95.2% | Top-5 召回准确率 |
| Token 减少 | 92% | 相比原始对话 |
| 外部数据库 | 0 | 无需额外存储依赖 |

资料来源：[website/app/opengraph-image.tsx]()

## 验证安装

```bash
# 检查 CLI 是否可用
agentmemory --version

# 启动服务器并验证
agentmemory serve &
curl http://localhost:3111/health
```

## 下一步

- 阅读完整文档：https://github.com/rohitg00/agentmemory#quick-start
- 查看集成示例：https://github.com/rohitg00/agentmemory/tree/main/integrations
- 查阅变更日志：https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md

---

<a id='architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目介绍](#intro), [数据流与处理](#data-flow), [记忆操作](#memory-operations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)
- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)
- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)
- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)
- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)
</details>

# 系统架构

## 概述

AgentMemory 是一个完整的 AI 代理记忆运行时系统，而非简单的向量数据库或工具库。该系统提供完整的记忆生命周期管理：捕获（Capture）、召回（Recall）、整合（Consolidate）、观察（Observe）和联邦（Federate） 资料来源：[src/viewer/index.html]()

AgentMemory 的核心设计理念是将原始观察数据转化为结构化的语义记忆，使 AI 代理能够在多次会话中保持上下文连贯性，避免重复工作并积累可复用的知识。

## 核心架构组件

### 系统服务层

AgentMemory 以本地 HTTP 服务器形式运行，默认监听端口 **3111**，为所有记忆操作提供统一的 API 接口 资料来源：[website/components/LiveTerminal.tsx]()

```mermaid
graph TD
    A[AI 代理] -->|MCP 协议| B[AgentMemory Server :3111]
    B --> C[JSONL 存储引擎]
    B --> D[LLM 处理管道]
    B --> E[Web Viewer 界面]
    
    C --> F[observations]
    C --> G[actions]
    C --> H[crystals]
    C --> I[sessions]
```

### 记忆类型体系

系统定义了四种互补的记忆类型，分别承担不同的认知功能：

| 记忆类型 | 用途 | 数据结构 |
|---------|------|---------|
| **Observations** | 原始工具调用记录 | 时间线形式，含分页 |
| **Semantic Memory** | 事实性知识提取 | 置信度 + 强度评分 |
| **Procedural Memory** | 可复用的操作流程 | 触发条件 + 步骤序列 |
| **Crystals** | 会话级压缩摘要 | 3行精华总结 |

资料来源：[src/viewer/index.html]()

### 记忆处理管道

记忆从原始观察到结构化知识的转化经过三个主要阶段：

```mermaid
graph LR
    A[原始工具调用] -->|压缩| B[Observation]
    B -->|整合| C[Semantic Facts]
    B -->|整合| D[Procedures]
    B + C + D -->|汇总| E[Crystal]
```

#### 第一阶段：压缩（Compression）

压缩引擎将原始工具调用转化为结构化的观察记录。该阶段使用专用的 LLM 提示模板，从每次工具调用中提取关键技术细节 资料来源：[src/prompts/compression.ts]()

压缩输出包含以下字段：

| 字段 | 类型 | 说明 |
|-----|------|-----|
| `type` | enum | 工具调用类型（file_read/write/edit/command_run 等） |
| `title` | string | 简短描述（最多80字符） |
| `facts` | array | 具体事实细节列表 |
| `narrative` | string | 2-3句总结 |
| `concepts` | array | 可搜索的技术概念 |
| `files` | array | 涉及的文件路径 |
| `importance` | number | 1-10 重要性评分 |

#### 第二阶段：整合（Consolidation）

整合阶段从多次观察中提取高层次的语义记忆和程序性记忆 资料来源：[src/prompts/consolidation.ts]()

- **语义记忆提取**：从重复出现的观察中提取稳定的事实断言，附带置信度评分
- **程序性记忆提取**：识别重复执行2次以上的操作模式，提取为可自动触发的流程
- **关系识别**：建立概念间的语义关联

#### 第三阶段：摘要（Crystallization）

每个会话结束时，系统生成晶体（Crystal）——会话的压缩精华摘要，包含：

- 会话标题（最多100字符）
- 3-5句叙事总结
- 关键决策及理由
- 修改的文件列表
- 可搜索的概念标签 资料来源：[src/prompts/summary.ts]()

### 观察数据模型

观察记录在界面中以时间线形式展示，支持分页浏览：

```typescript
interface Observation {
  id: string;
  timestamp: number;
  type: 'file_read' | 'file_write' | 'file_edit' | 
        'command_run' | 'search' | 'web_fetch' | 
        'conversation' | 'error' | 'decision' | 
        'discovery' | 'subagent' | 'notification' | 
        'task' | 'other';
  title: string;
  subtitle?: string;
  facts: string[];
  narrative: string;
  concepts: string[];
  files: string[];
  importance: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
  hookType: string;
  toolName?: string;
}
```

资料来源：[src/prompts/compression.ts]()

### 语义记忆模型

语义记忆条目展示时附带多维度评估指标：

| 指标 | 说明 | 可视化 |
|-----|------|-------|
| **Confidence** | 事实置信度 | 百分比显示 |
| **Strength** | 记忆强度 | 进度条（>70%为绿色） |
| **重要性** | 对系统的影响程度 | 颜色编码 |

资料来源：[src/viewer/index.html]()

## 功能模块架构

### 动作系统（Actions）

动作系统追踪代理在会话中产生的后续跟进项，包括：

- 需要重访的决策
- 需要检查的文件
- 等待输入的任务

动作状态流转：`pending → active → done/blocked`

创建方式支持三种渠道：
1. MCP 工具调用 `memory_action_create`
2. HTTP API 直接 POST
3. 钩子自动从长会话正文中提取

资料来源：[src/viewer/index.html]()

### 特性标志系统（Feature Flags）

系统内置可配置的特性标志机制，用于动态控制功能开关：

```typescript
interface FeatureFlag {
  kind: string;           // 样式类别
  dismissKey: string;     // 关闭键
  icon: string;           // 图标
  title: string;          // 标题
  keyLabel: string;       // 键标签
  desc: string;           // 描述
  enable: string;         // 启用命令
  docs?: string;          // 文档链接
}
```

特性标志支持折叠/展开展示，并可单独关闭 资料来源：[src/viewer/index.html]()

### 隐私保护机制

系统内置多层次隐私保护功能，用于检测和脱敏敏感信息 资料来源：[src/functions/privacy.ts]()

**检测模式包括：**

| 类别 | 正则模式 |
|-----|---------|
| 通用凭证 | `api_key`, `secret`, `token`, `password`, `credential` 等 |
| Bearer Token | `Bearer [A-Za-z0-9._\-+/=]{20,}` |
| OpenAI Key | `sk-proj-[A-Za-z0-9\-_]{20,}` |
| Anthropic Key | `sk-ant-[A-Za-z0-9\-_]{20,}` |
| GitHub Token | `gh[pus]_[A-Za-z0-9]{36,}` |
| GitHub PAT | `github_pat_[A-Za-z0-9_]{22,}` |
| Slack Token | `xoxb-[A-Za-z0-9\-]+` |
| AWS Key | `AKIA[0-9A-Z]{16}` |
| Google API | `AIza[A-Za-z0-9\-_]{35}` |
| NPM Token | `npm_[A-Za-z0-9]{36}` |
| GitLab Token | `glpat-[A-Za-z0-9\-_]{20,}` |

此外，系统支持 `<private>` XML 标签用于手动标记需要隐藏的内容区域。

## 代理集成架构

### MCP 原生支持

AgentMemory 通过 Model Context Protocol (MCP) 实现与多种 AI 代理的原生集成：

```mermaid
graph TD
    subgraph "支持的代理"
        A[Claude Code]
        B[Codex CLI]
        C[OpenClaw]
        D[Hermes]
        E[PI]
        F[OpenHuman]
    end
    
    A & B & C & D & E & F -->|agentmemory connect| G[MCP Server]
    G --> H[AgentMemory Core]
```

连接命令：`agentmemory connect <agent>` 自动配置所有兼容代理 资料来源：[website/components/Agents.tsx]()

### 审计日志

系统记录完整的操作审计日志，包含：

- 会话历史（sessions）
- 审计条目（audit，含200条限制）

资料来源：[src/viewer/index.html]()

## Web Viewer 架构

Web Viewer 提供图形化的记忆查看界面，包含以下视图模块：

| 视图 | 功能 |
|-----|------|
| **Timeline** | 时间线形式浏览所有观察记录，支持按类型筛选和分页 |
| **Actions** | 跟踪和管理代理产生的后续动作项 |
| **Crystals** | 查看压缩后的会话摘要，支持搜索 |
| **Activity** | 展示会话和审计活动的聚合视图 |
| **Audit** | 详细的操作审计日志 |

每个视图都包含搜索功能、筛选机制和分页导航 资料来源：[src/viewer/index.html]()

## 数据存储架构

AgentMemory 采用 **JSONL**（JSON Lines）格式进行本地存储，无需外部数据库依赖 资料来源：[src/viewer/index.html]()

存储特点：

- **无外部依赖**：零外部数据库，降低部署复杂度
- **会话隔离**：每个会话的原始观察独立存储
- **自动清理**：原始观察定期修剪，仅保留晶体摘要
- **可追溯性**：晶体保存后仍可重放会话的关键信息

## 开发贡献架构

项目采用标准化的分支管理策略 资料来源：[CONTRIBUTING.md]()

| 分支类型 | 命名格式 | 用途 |
|---------|---------|------|
| 功能分支 | `feat/<short-name>` | 新功能开发 |
| 修复分支 | `fix/<issue>-<short-name>` | Bug 修复 |
| 文档分支 | `docs/<topic>` | 文档更新 |
| 重构分支 | `refactor/<topic>` | 代码重构 |
| 维护分支 | `chore/<topic>` | 其他维护工作 |

开发流程要求：
- Node >= 20
- TypeScript 编译通过
- 全量测试通过
- 所有提交包含签名（`-s` 标志）

## 技术栈总结

| 层级 | 技术选型 |
|-----|---------|
| 运行时 | Node.js (>=20) |
| 类型系统 | TypeScript |
| 存储 | JSONL (本地文件) |
| 通信协议 | HTTP REST API |
| 代理集成 | MCP (Model Context Protocol) |
| 界面 | Web Viewer (HTML/JS) |
| AI 处理 | LLM API (可配置) |

AgentMemory 的设计目标是在本地环境中提供企业级的记忆管理能力，同时保持零外部依赖和快速启动特性。通过 MCP 协议的广泛兼容性，系统可以无缝集成到现有的 AI 代理工作流中。

---

<a id='data-flow'></a>

## 数据流与处理

### 相关页面

相关主题：[系统架构](#architecture), [记忆操作](#memory-operations), [搜索与检索](#search-retrieval)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)
- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)
- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)
</details>

# 数据流与处理

## 概述

AgentMemory 的数据流与处理系统是一个完整的数据处理管道，负责从原始工具调用观测中提取、压缩、总结并最终整合为可重用的结构化记忆。该系统采用分层处理架构，将观测数据逐级转化为语义记忆、程序记忆和关系记忆三种核心记忆类型，为 AI 代理提供持久化上下文能力。

数据处理管道的设计遵循以下核心原则：高保真度保留技术细节、高压缩率降低 token 消耗、自动隐私保护机制。系统无需外部数据库，仅依赖本地 JSONL 文件存储即可运行。

## 核心处理流程

### 数据处理阶段总览

```mermaid
graph TD
    A[原始工具调用] --> B[观测捕获 observe]
    B --> C[压缩处理 compress]
    C --> D[会话总结 summary]
    D --> E[记忆整合 consolidation]
    E --> F[关系映射 relations]
    F --> G[索引持久化 persistence]
    G --> H[检索召回 remember]
    
    B1[隐私检测] -.->|过滤敏感信息| B
    C1[XML 结构化] -.->|格式标准化| C
    D1[叙事生成] -.->|上下文连贯| D
    E1[程序提取] -.->|可复用知识| E
```

### 阶段一：观测捕获

观测捕获是数据进入系统的入口点。当代理执行工具调用或触发特定钩子时，系统实时捕获这些事件。捕获内容包括工具名称、执行参数、返回结果、执行时间戳等元数据。观测类型映射表如下：

| 观测类型 | 对应工具/钩子 | 说明 |
|---------|--------------|------|
| file_read | Read | 文件读取操作 |
| file_write | Write | 文件写入操作 |
| file_edit | Edit | 文件编辑操作 |
| command_run | Bash | 命令执行操作 |
| search | Grep/Glob | 搜索操作 |
| web_fetch | WebFetch/WebSearch | 网络获取 |
| conversation | AskUserQuestion | 用户对话 |
| subagent | Task | 子任务执行 |

### 阶段二：压缩处理

压缩处理将原始观测转化为结构化的 XML 格式，这是系统实现 92% token 减少量的关键步骤。

压缩系统提示词定义了严格的数据结构要求：

```xml
<observation>
  <type>one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other</type>
  <title>Short descriptive title (max 80 chars)</title>
  <subtitle>One-line context (optional)</subtitle>
  <facts>
    <fact>Specific factual detail 1</fact>
    <fact>Specific factual detail 2</fact>
  </facts>
  <narrative>2-3 sentence summary of what happened and why it matters</narrative>
  <concepts>
    <concept>technical concept or pattern</concept>
  </concepts>
  <files>
    <file>path/to/file</file>
  </files>
  <importance>1-10 scale</importance>
</observation>
```

**重要性评分标准**：

| 分数范围 | 含义 | 示例场景 |
|---------|------|---------|
| 1-3 | 常规操作 | 日常文件读取 |
| 4-6 | 中等变更 | 编辑命令执行 |
| 7-9 | 架构决策 | 核心设计变更 |
| 10 | 破坏性变更 | API 重大修改 |

压缩处理函数 `buildCompressionPrompt` 接收原始观测数据，生成符合系统提示词要求的压缩指令，用于调用 LLM 生成结构化输出。

资料来源：[src/prompts/compression.ts:1-29]()

### 阶段三：会话总结

会话总结从多个压缩观测中提取会话级别的元信息，生成会话摘要。总结系统采用 XML 结构化输出：

```xml
<summary>
  <title>Short session title (max 100 chars)</title>
  <narrative>3-5 sentence narrative of what was accomplished</narrative>
  <decisions>
    <decision>Key technical decision made</decision>
  </decisions>
  <files>
    <file>path/to/modified/file</file>
  </files>
  <concepts>
    <concept>key concept from session</concept>
  </concepts>
</summary>
```

`buildSummaryPrompt` 函数将多个观测对象格式化为标准输入文本，供 LLM 生成会话级摘要。该函数将每个观测的 facts、narrative、files 和 concepts 字段进行格式化重组，确保 LLM 能够理解完整的会话上下文。

资料来源：[src/prompts/summary.ts:1-45]()

## 记忆整合与提炼

### 程序记忆提取

程序记忆提取是系统的核心知识提炼机制。当同一操作模式在多个会话中出现 2 次以上时，系统自动识别并提取为可复用程序。

提取规则：

| 规则类型 | 描述 |
|---------|------|
| 频率阈值 | 仅提取出现 2+ 次的模式 |
| 步骤粒度 | 每个步骤需具体可执行 |
| 触发条件 | 条件需足够具体以支持自动匹配 |

程序提取提示词模板：

```
Extract reusable procedures from these recurring patterns:

[Pattern 1] (seen 3x)
<pattern content>

[Pattern 2] (seen 2x)
<pattern content>
```

该提示词驱动 LLM 从高频模式中归纳出通用的操作流程和触发条件。

资料来源：[src/prompts/consolidation.ts:7-15]()

### 记忆聚类与反思

记忆聚类将语义相关的记忆项组织在一起，反思系统在此基础上生成高层洞察：

```typescript
// 聚类输出结构
cluster = {
  facts: [{ fact: string, confidence: number }],
  lessons: [{ content: string, confidence: number }],
  crystalNarratives: [string]
}
```

反思过程生成的洞察包括：

| 类别 | 说明 |
|-----|------|
| 已知事实 | 高置信度的技术事实 |
| 经验教训 | 从操作中提炼的可复用经验 |
| 完成工作摘要 | 已完成项目的关键叙事 |

资料来源：[src/prompts/reflect.ts:10-30]()

## 隐私保护机制

### 敏感信息检测

隐私处理模块维护了一个全面的敏感信息检测模式列表：

```typescript
const SECRET_PATTERN_SOURCES = [
  // API 密钥类
  /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi,
  // Bearer Token
  /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
  // OpenAI 密钥
  /sk-proj-[A-Za-z0-9\-_]{20,}/g,
  // Anthropic 密钥
  /sk-ant-[A-Za-z0-9\-_]{20,}/g,
  // GitHub Token
  /gh[pus]_[A-Za-z0-9]{36,}/g,
  /github_pat_[A-Za-z0-9_]{22,}/g,
  // Slack Token
  /xoxb-[A-Za-z0-9\-]+/g,
  // AWS 密钥
  /AKIA[0-9A-Z]{16}/g,
  // Google API Key
  /AIza[A-Za-z0-9\-_]{35}/g,
  // JWT
  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
  // NPM Token
  /npm_[A-Za-z0-9]{36}/g,
  // GitLab Token
  /glpat-[A-Za-z0-9\-_]{20,}/g
];
```

### 隐私标签处理

除了正则匹配外，系统还支持 `<private>` XML 标签包裹的隐私内容：

```typescript
const PRIVATE_TAG_RE = /<private>[\s\S]*?<\/private>/gi;
```

所有检测到的敏感信息都会在进入压缩管道前被过滤或脱敏，确保输出中不包含任何凭据信息。

资料来源：[src/functions/privacy.ts:1-20]()

## 数据存储与持久化

### 存储架构

AgentMemory 采用零外部依赖的存储架构，所有数据以 JSONL 格式存储于本地文件系统：

| 数据类型 | 存储格式 | 说明 |
|---------|---------|------|
| 观测记录 | JSONL | 每行一条压缩观测 |
| 会话摘要 | JSONL | 每行一个会话总结 |
| 索引数据 | JSON | 快速检索索引 |
| 元数据 | JSON | 配置和状态信息 |

### 持久化策略

系统在处理过程中自动触发持久化操作，关键时机包括：

1. **观测压缩完成后**：立即写入观测记录
2. **会话结束时**：生成并存储会话摘要
3. **记忆整合后**：更新相关索引
4. **定时检查点**：防止数据丢失

## 检索与召回

### 召回流程

当代理需要检索历史记忆时，系统执行以下召回流程：

```mermaid
graph LR
    A[查询请求] --> B[语义匹配]
    B --> C[重要性过滤]
    C --> D[相关性排序]
    D --> E[上下文组装]
    E --> F[返回结果]
```

### 召回策略

| 策略 | 说明 | 优先级 |
|-----|------|-------|
| 精确匹配 | 文件路径、函数名等精确匹配 | 高 |
| 语义相似 | 基于概念嵌入的相似度匹配 | 中 |
| 时间衰减 | 近期记忆权重更高 | 低 |
| 使用频率 | 高频访问记忆优先 | 低 |

## 配置参数

### 核心配置项

| 参数 | 默认值 | 说明 |
|-----|-------|------|
| POLL_INTERVAL_MS | 10000 | 轮询间隔（毫秒） |
| WS_MAX_RETRIES | 4 | WebSocket 最大重试次数 |
| DIRECT_FAILURE_THRESHOLD | 2 | 直接连接失败阈值 |
| importance.minThreshold | 0 | 最小重要性阈值 |

## 技术总结

AgentMemory 的数据流与处理系统通过分层处理架构，实现了从原始观测到结构化记忆的完整转换：

- **观测层**：实时捕获工具调用和系统事件
- **压缩层**：XML 结构化压缩，token 减少 92%
- **总结层**：会话级别叙事生成
- **整合层**：程序记忆提取和聚类反思
- **存储层**：JSONL 本地持久化，零外部依赖
- **召回层**：多策略检索和上下文组装

整个处理管道支持实时处理和批量处理两种模式，通过 WebSocket 和 HTTP API 对外提供服务，确保与各类 MCP 客户端的兼容性。

---

<a id='memory-operations'></a>

## 记忆操作

### 相关页面

相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval), [MCP服务器与工具](#mcp-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)
- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
- [src/prompts/reflect.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)
- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)
- [src/functions/privacy.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)
</details>

# 记忆操作

AgentMemory 是一个完整的记忆运行时系统，提供多种记忆操作能力来捕获、召回、整合和观察 AI 代理的工作记忆。本页详细介绍记忆操作的核心概念、数据模型和系统交互流程。

## 系统概述

AgentMemory 的记忆操作涵盖四大核心能力领域：

| 操作类型 | 功能描述 | 数据持久化 |
|---------|---------|-----------|
| **记忆压缩** (Compression) | 将原始工具调用观测压缩为结构化数据 | 观察记录 |
| **会话摘要** (Summary) | 生成会话级别的叙事性摘要 | 水晶 (Crystals) |
| **反思整合** (Reflection) | 从记忆簇中提取高层洞察 | 语义/程序性记忆 |
| **隐私处理** (Privacy) | 自动过滤敏感信息和凭证 | 无持久化 |

资料来源：[src/prompts/compression.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)

## 核心数据模型

### 观察记录 (Observation)

每次工具调用后系统会生成结构化的观察记录，格式如下：

```xml
<observation>
  <type>one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other</type>
  <title>Short descriptive title (max 80 chars)</title>
  <subtitle>One-line context (optional)</subtitle>
  <facts>
    <fact>Specific factual detail 1</fact>
    <fact>Specific factual detail 2</fact>
  </facts>
  <narrative>2-3 sentence summary of what happened and why it matters</narrative>
  <concepts>
    <concept>technical concept or pattern</concept>
  </concepts>
  <files>
    <file>path/to/file</file>
  </files>
  <importance>1-10 scale, 10 being critical architectural decision</importance>
</observation>
```

**重要性评分标准：**

| 评分范围 | 含义 | 示例场景 |
|---------|------|---------|
| 1-3 | 常规读取操作 | 读取配置文件、查看文档 |
| 4-6 | 编辑和命令执行 | 修改代码、运行测试 |
| 7-9 | 架构决策 | API 设计变更、依赖调整 |
| 10 | 重大变更 | 破坏性更改、安全修复 |

资料来源：[src/prompts/compression.ts:3-31](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)

### 水晶 (Crystals)

水晶是会话完成后的冻结快照，捕获单个会话的叙事、调用工具的关键结果、触及的文件以及提炼的经验教训。

```html
<div class="card" style="margin-bottom:12px;padding:12px;background:var(--bg-subtle);">
  <strong>Crystals</strong> are frozen snapshots of completed work. 
  Each crystal captures one session's narrative, the tools invoked (key outcomes), 
  files touched, and lessons surfaced — a replayable summary you keep after 
  raw observations are pruned.
</div>
```

**水晶数据结构：**

| 字段 | 类型 | 说明 |
|-----|------|-----|
| title | string | 会话标题（最多100字符） |
| narrative | string | 3-5句完成事项叙事 |
| decisions | array | 做出的技术决策 |
| files | array | 创建或修改的文件路径 |
| concepts | array | 可搜索的关键概念 |

资料来源：[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)

### 语义记忆与程序性记忆

系统将观察记录分类存储为两种互补的记忆形式：

**语义记忆 (Semantic Memory)**：存储事实性信息，基于置信度评分。

```html
<div class="card"><div class="card-title">Semantic Memory</div>
  semFacts.slice(0, 5).forEach(function(f) {
    var conf = typeof f.confidence === 'number' ? Math.round(f.confidence * 100) : null;
    var str = typeof f.strength === 'number' ? Math.round(f.strength * 100) : null;
  });
</div>
```

**程序性记忆 (Procedural Memory)**：存储可重用的操作流程，从反复出现的模式中提取。

> 资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)

## 操作流程

### 记忆压缩流程

```mermaid
graph TD
    A[工具调用完成] --> B[触发压缩钩子]
    B --> C[构建压缩提示词]
    C --> D[调用 LLM 生成结构化观察]
    D --> E{隐私检查}
    E -->|发现敏感信息| F[标记为 private]
    E -->|无敏感信息| G[直接存储]
    F --> H[存储观察记录]
    G --> H
    H --> I[更新时间线视图]
```

压缩提示词系统包含三类操作：

| 操作 | 触发条件 | 产物 |
|-----|---------|-----|
| 压缩 (Compression) | 单次工具调用完成 | 单条观察记录 |
| 摘要 (Summary) | 会话结束或手动触发 | 水晶快照 |
| 整合 (Consolidation) | 多个相关观察积累 | 高阶洞察 |

资料来源：[src/prompts/compression.ts:31-45](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)

### 会话摘要生成

```mermaid
graph LR
    A[观察记录集合] --> B[压缩为结构化数据]
    B --> C[构建摘要提示词]
    C --> D[LLM 生成 XML 格式摘要]
    D --> E[解析并存储为水晶]
    E --> F[供后续会话检索使用]
```

**摘要生成规则：**

- 聚焦成果，而非单个工具调用
- 突出决策及其理由
- 列出所有创建或修改的文件
- 概念应为可搜索术语，用于未来上下文检索

资料来源：[src/prompts/summary.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)

### 反思整合流程

```mermaid
graph TD
    A[相关记忆簇] --> B[收集已知事实]
    B --> C[提取经验教训]
    C --> D[汇总水晶叙事]
    D --> E[构建反思提示词]
    E --> F[生成高阶洞察]
    F --> G[更新语义/程序性记忆]
```

反思操作从记忆簇中综合提炼出更高层次的见解，包含：

- 已知事实 (Known Facts)：带置信度的技术事实
- 经验教训 (Lessons Learned)：带置信度的行为准则
- 完成工作摘要 (Completed Work Summaries)：会话叙事片段

资料来源：[src/prompts/reflect.ts:1-40](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/reflect.ts)

## 隐私处理机制

AgentMemory 内置敏感信息自动过滤功能，在记忆压缩前扫描输出内容。

### 检测模式

```typescript
const SECRET_PATTERN_SOURCES = [
  /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi,
  /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
  /sk-proj-[A-Za-z0-9\-_]{20,}/g,
  /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\-_]{19,}/g,
  /sk-ant-[A-Za-z0-9\-_]{20,}/g,
  /gh[pus]_[A-Za-z0-9]{36,}/g,
  /github_pat_[A-Za-z0-9_]{22,}/g,
  /xoxb-[A-Za-z0-9\-]+/g,
  /AKIA[0-9A-Z]{16}/g,
  /AIza[A-Za-z0-9\-_]{35}/g,
  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
  /npm_[A-Za-z0-9]{36}/g,
  /glpat-[A-Za-z0-9\-_]{20,}/g,
];
```

### 隐私处理规则

| 标签格式 | 作用 | 持久化 |
|---------|------|--------|
| `<private>...</private>` | 包裹敏感内容 | 不存储 |

隐私扫描覆盖的凭证类型：

| 类型 | 匹配模式示例 |
|-----|-------------|
| API 密钥 | `api_key=xxx...`、`secret: xxx...` |
| Bearer 令牌 | `Bearer eyJ...` |
| OpenAI 密钥 | `sk-proj-xxx...` |
| Anthropic 密钥 | `sk-ant-xxx...` |
| GitHub 令牌 | `ghp_xxx...`、`github_pat_xxx...` |
| Slack 令牌 | `xoxb-xxx...` |
| AWS 密钥 | `AKIAxxx...` |
| Google API | `AIzaxxx...` |
| NPM 令牌 | `npm_xxx...` |
| GitLab 令牌 | `glpat-xxx...` |

资料来源：[src/functions/privacy.ts:1-30](https://github.com/rohitg00/agentmemory/blob/main/src/functions/privacy.ts)

## 可视化界面

AgentMemory 提供 Web 查看器界面，支持多种记忆操作的交互式展示。

### 时间线视图

观察记录以时间线形式展示，支持分页浏览：

```html
<div class="pagination">
  <button data-action="timeline-page" data-page="0">Prev</button>
  <span>Page 1 of 10 (95 total)</span>
  <button data-action="timeline-page" data-page="1">Next</button>
</div>
```

**时间线过滤类型：**

- `file_read` - 文件读取
- `file_write` - 文件写入
- `file_edit` - 文件编辑
- `command_run` - 命令执行
- `search` - 搜索操作
- `error` - 错误记录
- `decision` - 决策记录

### 记忆检索

```html
<input class="search-input" type="text" placeholder="Search crystals..." 
       oninput="state.crystals.search=this.value;renderCrystals()"/>
```

支持对水晶、语义记忆、程序性记忆、经验教训等多种记忆类型的全文搜索。

### 功能标志 (Feature Flags)

系统支持通过 URL 参数启用或禁用特定功能：

```html
<div class="flag-banner ' + b.kind + '" data-flag="' + b.dismissKey + '">
  <span class="flag-icon">' + b.icon + '</span>
  <div class="flag-body">
    <div class="flag-title">' + b.title + ' <code>' + b.keyLabel + '</code></div>
    <code class="flag-enable">' + esc(b.enable) + '</code>
  </div>
</div>
```

资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)

## 操作 API 概览

基于记忆操作的核心函数接口：

| 函数 | 用途 | 输入 | 输出 |
|-----|------|-----|-----|
| `buildCompressionPrompt` | 构建压缩提示词 | 工具调用信息 | 格式化的提示字符串 |
| `buildSummaryPrompt` | 构建摘要提示词 | 观察记录数组 | 格式化的摘要提示 |
| `buildReflectionPrompt` | 构建反思提示词 | 记忆簇数据 | 格式化的反思提示 |
| `buildProceduralExtractionPrompt` | 提取程序性记忆 | 模式数组 | 格式化提取提示 |

所有构建函数均位于 `src/prompts/` 目录下，采用纯函数设计，便于测试和组合使用。

资料来源：[src/prompts/consolidation.ts:1-20](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)

## 总结

AgentMemory 的记忆操作构成了一个完整的信息生命周期管理系统：

1. **捕获阶段**：通过压缩机制将原始工具调用转化为结构化观察
2. **组织阶段**：通过摘要和反思机制将观察整合为水晶和高层洞察
3. **检索阶段**：通过多种视图和搜索机制支持快速上下文召回
4. **保护阶段**：通过隐私扫描确保敏感信息安全处理

该系统设计遵循"数据本地化、Token 高效化、外部依赖最小化"的原则，所有记忆操作均可在本地完成，无需外部数据库支持。

---

<a id='search-retrieval'></a>

## 搜索与检索

### 相关页面

相关主题：[记忆操作](#memory-operations), [记忆压缩与合并](#consolidation), [MCP服务器与工具](#mcp-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/functions/smart-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/smart-search.ts)
- [src/functions/search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/search.ts)
- [src/functions/graph-retrieval.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/graph-retrieval.ts)
- [src/state/hybrid-search.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/hybrid-search.ts)
- [src/state/vector-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/vector-index.ts)
- [src/state/search-index.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/search-index.ts)
- [src/state/reranker.ts](https://github.com/rohitg00/agentmemory/blob/main/src/state/reranker.ts)
</details>

# 搜索与检索

AgentMemory 的搜索与检索系统是整个记忆运行时的核心能力之一，负责从语义记忆、程序性记忆、关系网络等多种数据存储中高效定位并召回相关信息。该系统采用混合检索架构，结合向量相似度搜索、关键词倒排索引和图关系遍历，为 AI 编码代理提供精准的上下文召回能力。

## 系统架构总览

AgentMemory 的搜索系统由多个相互协作的模块组成，形成一个多层次的检索管道：

```mermaid
graph TD
    A[用户查询] --> B[Smart Search 智能搜索]
    B --> C[混合搜索调度]
    C --> D[向量索引检索]
    C --> E[倒排索引检索]
    C --> F[图关系检索]
    D --> G[重排序器]
    E --> G
    F --> G
    G --> H[隐私过滤器]
    H --> I[最终结果]
```

核心模块分布在两个目录层级：

| 目录 | 职责 | 关键文件 |
|------|------|----------|
| `src/functions/` | 搜索业务逻辑与 API 封装 | `smart-search.ts`, `search.ts`, `graph-retrieval.ts` |
| `src/state/` | 索引数据结构和检索算法实现 | `hybrid-search.ts`, `vector-index.ts`, `search-index.ts`, `reranker.ts` |

## 向量索引检索

向量索引是语义相似度搜索的基础设施。AgentMemory 使用向量嵌入表示语义记忆中的事实、概念和叙述文本，支持基于余弦相似度或欧氏距离的近似最近邻搜索。

### 索引数据结构

向量索引模块维护以下核心数据结构：

- **嵌入向量存储**：将文本内容转换为高维向量并持久化存储
- **元数据索引**：为每个向量关联来源、时间戳、置信度等元信息
- **分区索引**：按语义类别或时间窗口对向量进行分区优化查询性能

### 检索流程

```mermaid
graph LR
    A[查询文本] --> B[嵌入模型]
    B --> C[查询向量]
    C --> D[ANN搜索]
    D --> E[候选集]
    E --> F[元数据过滤]
    F --> G[排序结果]
```

向量检索的关键参数包括：

| 参数 | 类型 | 说明 |
|------|------|------|
| `topK` | `number` | 返回的最相似结果数量 |
| `minScore` | `number` | 最小相似度阈值 |
| `filters` | `object` | 元数据过滤条件 |
| `embeddingModel` | `string` | 指定的嵌入模型名称 |

## 倒排索引检索

倒排索引提供基于关键词的精确匹配能力，与向量检索形成互补。搜索索引模块维护从术语到记忆条目的映射，支持布尔查询和短语匹配。

### 索引构建

索引构建过程包括以下步骤：

1. **文本分词**：对记忆内容进行标准化分词处理
2. **术语提取**：识别关键词和实体名称
3. **倒排列表构建**：建立术语到文档 ID 的映射
4. **权重计算**：基于 TF-IDF 或 BM25 计算术语权重

### 查询处理

倒排索引检索支持多种查询语法：

- **AND 查询**：`term1 AND term2` - 返回同时包含两个术语的结果
- **OR 查询**：`term1 OR term2` - 返回包含任一术语的结果
- **短语查询**：`"exact phrase"` - 精确匹配短语
- **字段限定**：`field:value` - 限定搜索特定字段

## 图关系检索

图检索模块维护记忆条目之间的语义关系网络，支持基于关系路径的扩展检索。

### 关系类型

AgentMemory 中的关系包括：

| 关系类型 | 描述 | 示例 |
|----------|------|------|
| `causes` | 因果关系 | 修改配置导致应用重启 |
| `implements` | 实现关系 | 抽象接口被具体类实现 |
| `depends_on` | 依赖关系 | 模块 A 依赖模块 B |
| `related_to` | 关联关系 | 相关但非直接因果 |
| `derived_from` | 派生关系 | 经验教训来源于具体案例 |

### 图遍历算法

图检索支持以下遍历策略：

```mermaid
graph TD
    A[起点节点] --> B[直接邻居]
    A --> C[2度邻居]
    A --> D[N度可达]
    B --> E[BFS广度优先]
    C --> E
    D --> F[DFS深度优先]
    B --> G[PageRank排序]
    C --> G
```

- **广度优先搜索 (BFS)**：适合查找最近关联的记忆
- **深度优先搜索 (DFS)**：适合探索完整的语义路径
- **PageRank 排序**：根据关系重要性权重排序结果

## 混合搜索调度

混合搜索是 AgentMemory 检索系统的核心调度层，协调向量检索、倒排索引和图检索的结果融合。

### 融合策略

混合搜索支持多种结果融合策略：

| 策略 | 说明 | 适用场景 |
|------|------|----------|
| `reciprocal_rank` | 倒数排名融合 | 多源结果互补 |
| `compressed_score` | 加权分数融合 | 需要精确控制各源权重 |
| `rrf_k` | 倒数排名融合因子 | 平衡精确性和多样性 |

### 调度配置

混合搜索的调度参数包括：

```typescript
interface HybridSearchConfig {
  vectorWeight: number;      // 向量检索权重
  keywordWeight: number;    // 关键词检索权重
  graphWeight: number;      // 图检索权重
  fusionStrategy: 'rrf' | 'weighted' | 'composite';
  minRelevanceScore: number; // 最低相关性阈值
  maxResults: number;        // 最大返回结果数
}
```

## 重排序器

重排序器（Reranker）对候选结果进行精细化排序，提升最终结果的相关性。

### 排序算法

重排序器采用多信号融合排序：

1. **原始相似度分数**：来自向量或关键词检索的初始分数
2. **关系重要性**：基于图结构的节点重要性得分
3. **时效性权重**：新近更新的记忆获得更高权重
4. **使用频率**：高频访问的记忆获得提升
5. **隐私敏感性**：敏感内容可能被降权或过滤

### 排序公式

综合排序分数计算如下：

```
finalScore = α × vectorScore + β × keywordScore + γ × graphScore + δ × recencyScore + ε × usageScore
```

其中 `α`, `β`, `γ`, `δ`, `ε` 为可配置的权重系数，满足 `α + β + γ + δ + ε = 1`。

## 隐私过滤

检索系统在返回结果前必须经过隐私过滤器处理，确保敏感信息不被泄露。

### 敏感信息检测

隐私过滤器使用正则表达式检测敏感数据：

| 模式类型 | 正则表达式特征 | 示例 |
|----------|----------------|------|
| API 密钥 | `api[_-]?key\|secret\|token` | `sk-xxxx...` |
| Bearer 令牌 | `Bearer\s+[A-Za-z0-9._\-+/=]{20,}` | `Bearer eyJ...` |
| GitHub 令牌 | `gh[pus]_[A-Za-z0-9]{36,}` | `ghp_xxxx...` |
| NPM 令牌 | `npm_[A-Za-z0-9]{36}` | `npm_xxxx...` |
| JSON Web 令牌 | `eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}` | `eyJhbG...` |

资料来源：[src/functions/privacy.ts:4-22]()

### 过滤流程

```mermaid
graph TD
    A[检索结果] --> B{包含敏感内容?}
    B -->|是| C[标记敏感字段]
    B -->|否| F[通过]
    C --> D{完全敏感?}
    D -->|是| E[从结果中移除]
    D -->|否| F
    E --> G[返回过滤后结果]
    F --> G
```

隐私过滤器会将 `<private>` 标签包裹的内容完全移除，确保返回给用户的结果不包含任何凭证、密钥或个人身份信息。

## 语义记忆检索

语义记忆是检索系统最重要的数据来源之一，包含从观察记录中提取的事实性知识。

### 语义事实结构

检索到的语义事实包含以下属性：

| 属性 | 类型 | 说明 |
|------|------|------|
| `fact` | `string` | 事实内容文本 |
| `confidence` | `number` | 置信度 (0-1) |
| `strength` | `number` | 强度 (0-1) |
| `extractedAt` | `timestamp` | 提取时间 |

### 检索展示

在 AgentMemory Viewer 界面中，语义记忆以卡片形式展示，显示置信度和强度条：

```html
<!-- 语义事实展示结构 -->
<div class="semantic-memory">
  <div class="fact-content">{fact}</div>
  <div class="confidence-bar" style="width: {confidence * 100}%"></div>
  <div class="strength-indicator">{strength}%</div>
</div>
```

## 观察记录检索

观察记录（Observations）是从代理工具调用中提取的原始记忆单元，经过压缩后存储。

### 观察类型

| 类型 | 描述 | 重要性范围 |
|------|------|------------|
| `file_read` | 文件读取 | 1-3 |
| `file_write` | 文件写入 | 4-6 |
| `file_edit` | 文件编辑 | 4-6 |
| `command_run` | 命令执行 | 4-6 |
| `error` | 错误信息 | 7-9 |
| `decision` | 决策记录 | 7-9 |
| `discovery` | 发现事项 | 7-9 |
| `subagent` | 子代理调用 | 4-6 |

### 压缩观察结构

压缩后的观察记录格式：

```xml
<observation>
  <type>decision</type>
  <title>使用 SQLite 替代 Redis</title>
  <subtitle>缓存需求简单</subtitle>
  <facts>
    <fact>数据量小于 10000 条</fact>
    <fact>无需分布式缓存</fact>
  </facts>
  <narrative>团队决定简化架构...</narrative>
  <concepts>
    <concept>SQLite 嵌入式数据库</concept>
    <concept>缓存架构简化</concept>
  </concepts>
  <files>
    <file>src/db/cache.ts</file>
  </files>
  <importance>8</importance>
</observation>
```

资料来源：[src/prompts/compression.ts:1-40]()

## 分页与过滤

观察记录检索支持分页浏览和多种过滤条件。

### 分页参数

| 参数 | 说明 |
|------|------|
| `page` | 当前页码 (从 0 开始) |
| `pageSize` | 每页条目数 |
| `totalPages` | 总页数 |
| `total` | 符合条件的总条目数 |

### 类型过滤

观察记录可按类型进行过滤：

- `all` - 所有类型
- `file_*` - 文件相关操作
- `command` - 命令执行
- `search` - 搜索操作
- `web_fetch` - 网页获取
- `conversation` - 对话记录
- `error` - 错误信息
- `decision` - 决策记录

### 时间线视图

时间线视图按时间倒序展示观察记录，每页显示固定数量的条目，适合回顾特定时间段的代理行为。

## API 端点

AgentMemory 提供以下检索相关的 HTTP API：

| 端点 | 方法 | 说明 |
|------|------|------|
| `/search` | `POST` | 执行混合搜索 |
| `/semantic` | `GET` | 获取语义记忆 |
| `/observations` | `GET` | 获取观察记录 |
| `/graph/neighbors` | `GET` | 获取关系邻接节点 |

## 性能优化

### 索引优化策略

1. **增量索引**：新记忆追加而非重建全量索引
2. **批量向量化**：多个文本批量转换减少模型调用开销
3. **缓存机制**：热门查询结果缓存加速重复检索
4. **分区策略**：按时间或类别分区缩小搜索范围

### 查询优化

- 使用近似最近邻算法减少计算量
- 设置合理的 `topK` 和 `minScore` 阈值
- 利用元数据过滤减少候选集大小
- 图检索设置最大深度防止遍历爆炸

## 最佳实践

### 查询构造建议

1. **使用精确术语**：领域特定术语可提高关键词检索准确性
2. **组合多信号**：复杂查询建议使用混合搜索而非单一检索模式
3. **合理设置阈值**：根据召回率和精确率需求调整 `minRelevanceScore`
4. **利用关系扩展**：初始结果不足时可启用图关系扩展

### 结果后处理

1. **验证隐私合规性**：检索结果在展示前必须经过隐私过滤器
2. **置信度排序**：高置信度结果优先展示给用户
3. **去重处理**：合并来自不同来源的重复结果
4. **上下文补充**：为每个结果补充相关背景信息

## 相关模块

- **记忆压缩**：[compression.ts](src/prompts/compression.ts) - 观察记录的压缩格式定义
- **会话总结**：[summary.ts](src/prompts/summary.ts) - 会话摘要生成提示词
- **反思提炼**：[reflect.ts](src/prompts/reflect.ts) - 记忆聚类的反思提示词
- **Viewer 界面**：[index.html](src/viewer/index.html) - 检索结果的 Web 界面展示

---

<a id='consolidation'></a>

## 记忆压缩与合并

### 相关页面

相关主题：[数据流与处理](#data-flow), [搜索与检索](#search-retrieval)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/prompts/compression.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/compression.ts)
- [src/prompts/consolidation.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts)
- [src/functions/compress-file.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/compress-file.ts)
- [src/functions/replay.ts](https://github.com/rohitg00/agentmemory/blob/main/src/functions/replay.ts)
- [src/prompts/summary.ts](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/summary.ts)
</details>

# 记忆压缩与合并

## 概述

记忆压缩与合并（Memory Compression and Consolidation）是 AgentMemory 系统中用于管理长期记忆的核心机制。该系统通过多层次的处理流程，将原始观察数据转化为结构化、可检索的高价值记忆单元，从而在保持上下文完整性的同时显著降低存储和检索开销。

根据项目性能指标，该系统实现了 **92% 的 token 减少**，同时保持 **95.2% 的检索召回率（R@5）**，且无需外部数据库支持。资料来源：[website/app/opengraph-image.tsx:8-15]()

## 核心设计理念

### 压缩驱动的记忆生命周期

```
graph TD
    A[原始观察 Raw Observations] --> B[压缩引擎 Compression Engine]
    B --> C[结构化观察 Compressed Observations]
    C --> D[会话摘要 Crystal]
    C --> E[经验教训 Lessons]
    C --> F[语义记忆 Semantic Memory]
    C --> G[程序记忆 Procedural Memory]
    
    style A fill:#ff6b6b
    style C fill:#4ecdc4
    style G fill:#ffe66d
```

AgentMemory 采用**压缩优先**的策略，将 AI 编码代理在会话中产生的每一次工具调用、文件操作、命令执行等原始观察数据，通过 LLM 驱动的压缩引擎提取关键信息，生成包含类型、标题、事实、叙述、概念、文件路径和重要性评分等结构化字段的观察记录。资料来源：[src/prompts/compression.ts:1-30]()

### 合并驱动的记忆提炼

合并机制将重复出现的模式识别并提炼为可复用的程序记忆。系统仅提取出现 2 次及以上的模式，确保提炼出的程序具有足够的实践验证。资料来源：[src/prompts/consolidation.ts:12-20]()

## 压缩系统详解

### 观察类型分类

压缩引擎将所有观察归类为以下类型之一：

| 类型 | 描述 | 典型场景 |
|------|------|----------|
| `file_read` | 文件读取操作 | 读取配置文件、源码 |
| `file_write` | 文件创建操作 | 生成新文件、导出数据 |
| `file_edit` | 文件修改操作 | 编辑代码、修改配置 |
| `command_run` | 命令执行操作 | npm install、git commit |
| `search` | 搜索操作 | 代码搜索、全局查找 |
| `web_fetch` | 网页抓取 | 获取文档、API 响应 |
| `conversation` | 对话交互 | 用户与代理的交流 |
| `error` | 错误事件 | 异常捕获、构建失败 |
| `decision` | 决策点 | 技术选型、架构决策 |
| `discovery` | 发现事项 | 新工具、替代方案 |
| `subagent` | 子代理调用 | 任务委托、并行处理 |
| `notification` | 通知事件 | 构建完成、部署成功 |
| `task` | 任务跟踪 | 待办事项、里程碑 |
| `other` | 其他类型 | 不属于以上类别 |

资料来源：[src/prompts/compression.ts:10-11]()

### 重要性评分体系

压缩输出包含 1-10 的重要性评分，用于后续存储策略决策：

| 分数范围 | 含义 | 存储策略示例 |
|----------|------|--------------|
| 1-3 | 常规操作 | 快速遗忘、快速合并 |
| 4-6 | 中等重要 | 标准保留周期 |
| 7-9 | 重要决策 | 长期保留、高权重检索 |
| 10 | 关键变更 | 永久保留、影响分析 |

资料来源：[src/prompts/compression.ts:23-24]()

### 压缩输出格式

压缩后的观察数据采用 XML 格式输出，包含以下结构化字段：

```xml
<observation>
  <type>file_edit</type>
  <title>实现用户认证中间件</title>
  <subtitle>使用 JWT 方案替换会话认证</subtitle>
  <facts>
    <fact>中间件位于 src/middleware/auth.ts</fact>
    <fact>使用 RS256 算法进行签名验证</fact>
    <fact>添加了 refreshToken 过期自动续期逻辑</fact>
  </facts>
  <narrative>为现有 API 添加了统一的 JWT 认证中间件，解决了多端登录状态同步问题。</narrative>
  <concepts>
    <concept>JWT middleware</concept>
    <concept>auth middleware</concept>
  </concepts>
  <files>
    <file>src/middleware/auth.ts</file>
    <file>src/routes/api.ts</file>
  </files>
  <importance>7</importance>
</observation>
```

资料来源：[src/prompts/compression.ts:2-29]()

### 文件压缩与验证

`compress-file.ts` 模块提供了文件级压缩能力，包含以下验证机制：

```typescript
function validateCompression(original: string, compressed: string): string[] {
  // 验证标题层级完整性
  // 验证 URL 数量和内容一致性
  // 验证代码块数量和内容一致性
}
```

验证规则确保压缩过程不会丢失关键信息：

| 验证项 | 检查逻辑 |
|--------|----------|
| 标题层级 | 原始文件中的所有标题必须出现在压缩结果中 |
| URL 集合 | URL 数量和内容必须完全一致 |
| 代码块 | 代码块数量和内容必须保持不变 |

资料来源：[src/functions/compress-file.ts:24-45]()

## 合并系统详解

### 合并类型

```
graph LR
    A[压缩观察] --> B{合并触发条件}
    B -->|会话结束| C[会话摘要 Crystal]
    B -->|重复模式| D[程序记忆 Procedural]
    B -->|事实积累| E[语义记忆 Semantic]
    B -->|纠正记录| F[经验教训 Lessons]
```

#### 会话摘要（Crystal）

会话摘要是会话级别的压缩产物，通过 `buildSummaryPrompt` 函数构建。该函数将多个压缩观察整合为单一的结构化摘要：

```typescript
export function buildSummaryPrompt(observations: Array<{
  type: string
  title: string
  facts: string[]
  narrative: string
  files: string[]
  concepts: string[]
}>): string
```

输出格式：

```xml
<summary>
  <title>会话标题</title>
  <narrative>3-5句会话总结</narrative>
  <decisions>
    <decision>关键决策1</decision>
  </decisions>
  <files>
    <file>修改的文件路径</file>
  </files>
  <concepts>
    <concept>关键概念</concept>
  </concepts>
</summary>
```

资料来源：[src/prompts/summary.ts:1-38]()

#### 程序记忆（Procedural Memory）

程序记忆通过 `buildProceduralExtractionPrompt` 函数提取，用于识别重复执行的模式：

```typescript
export function buildProceduralExtractionPrompt(
  patterns: Array<{ content: string; frequency: number }>,
): string
```

提取规则：
- 仅提取出现 **2 次及以上** 的模式
- 步骤描述需具体可执行
- 触发条件需足够具体以支持自动匹配

资料来源：[src/prompts/consolidation.ts:12-24]()

### 经验教训系统

`replay.ts` 模块包含经验教训的自动识别机制，通过正则表达式模式匹配：

```typescript
const LESSON_PATTERNS: RegExp[] = [
  /\b(always|never|don'?t|do not|make sure|remember to|note:|caveat:|warning:)\b[^.\n]{10,200}[.!\n]/gi,
  /\b(prefer|avoid)\s[^.\n]{10,200}[.!\n]/gi,
];
```

这些模式识别以下类型的经验：
- **强制规则**：`always`、`never`、`make sure`
- **否定规则**：`don't`、`do not`
- **提醒标记**：`note:`、`caveat:`、`warning:`
- **偏好指导**：`prefer`、`avoid`

资料来源：[src/functions/replay.ts:45-48]()

### Crystal 和 Lessons 的派生流程

```typescript
async function deriveCrystalAndLessons(
  kv: StateKV,
  sessionId: string,
  project: string,
  rawObs: RawObservation[],
  compressed: CompressedObservation[],
  firstPrompt: string | undefined,
): Promise<void>
```

流程说明：

1. **输入收集**：收集原始观察、压缩观察和首条提示
2. **元数据提取**：从压缩观察中提取所有涉及的文件和工具
3. **文本分离**：区分用户提示和助手响应
4. **Crystal 生成**：创建包含时间戳的会话摘要
5. **Lessons 提取**：应用模式匹配提取经验教训
6. **关联存储**：将派生结果与原始会话关联

资料来源：[src/functions/replay.ts:50-76]()

## 数据流架构

```
graph TD
    subgraph 输入层
        R[Raw Observations]
        F[首条提示 First Prompt]
    end
    
    subgraph 压缩层
        C[压缩引擎]
        V[验证模块]
    end
    
    subgraph 合并层
        X[Crystal 生成]
        L[Lessons 提取]
        P[Procedural 提取]
    end
    
    subgraph 存储层
        S[Sessions]
        K[Knowledge]
    end
    
    R --> C
    F --> X
    C --> V
    V -->|验证通过| X
    X --> S
    L --> K
    P --> K
```

## 隐私与安全

系统在压缩和合并过程中实施严格的隐私保护措施。`privacy.ts` 模块定义了私密密文和敏感信息的识别模式：

```typescript
const PRIVATE_TAG_RE = /<private>[\s\S]*?<\/private>/gi;

const SECRET_PATTERN_SOURCES = [
  /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi,
  /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
  /sk-proj-[A-Za-z0-9\-_]{20,}/g,
  /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\-_]{19,}/g,
  // ... 更多模式
];
```

支持的敏感信息类型包括：
- API 密钥和 Bearer Token
- OpenAI、GitHub、GitLab 等平台密钥
- AWS、Google Cloud 等云服务凭证
- NPM、JWT 等通用认证令牌

资料来源：[src/functions/privacy.ts:1-25]()

## 配置与调优

### 压缩提示词

系统通过 `COMPRESSION_SYSTEM` 提示词指导 LLM 执行压缩任务，提示词包含：

| 配置项 | 说明 |
|--------|------|
| 输出格式 | XML 结构化格式 |
| 字段要求 | 标题最大 80 字符 |
| 重要性规则 | 1-3 常规、4-6 编辑命令、7-9 架构决策、10 破坏性变更 |
| 概念标签 | 应为可复用的搜索词 |
| 隐私处理 | 剥离密钥、令牌、凭证 |

### 合并策略

| 策略 | 触发条件 | 输出 |
|------|----------|------|
| Crystal 生成 | 会话结束或手动触发 | 会话摘要 |
| Procedural 提取 | 模式出现 2+ 次 | 可复用流程 |
| Lessons 提取 | 模式匹配命中 | 经验教训 |
| Semantic 合并 | 事实积累达到阈值 | 语义记忆 |

## 最佳实践

### 1. 观察记录的完整性

在会话中保持工具调用的完整记录，以便压缩引擎能够提取足够的上下文信息。包含原始响应内容的观察能生成更高质量的 Crystal。

### 2. 概念标签的精确性

为压缩观察分配准确的 `concepts` 标签，这些标签直接影响后续检索的召回率。建议使用标准化的技术术语作为概念标签。

### 3. 隐私标记的使用

在原始观察中使用 `<private>...</private>` 标签包裹敏感内容，确保压缩流程自动剥离这些信息。

### 4. Crystal 的定期复审

虽然 Crystal 是自动生成的，但建议定期审查并手动强化重要的决策和发现，以提升系统学习效果。

## 性能特性

| 指标 | 数值 | 说明 |
|------|------|------|
| Token 减少 | 92% | 相比原始观察的压缩率 |
| 检索召回率 | 95.2% (R@5) | Top-5 检索准确率 |
| 外部依赖 | 0 | 无需外部数据库 |
| 处理模式 | 实时 + 批量 | 支持即时压缩和后台合并 |

资料来源：[website/app/opengraph-image.tsx:8-15]()

## 相关模块

| 模块路径 | 功能描述 |
|----------|----------|
| `src/prompts/compression.ts` | 压缩系统提示词定义 |
| `src/prompts/consolidation.ts` | 合并系统提示词定义 |
| `src/functions/compress-file.ts` | 文件级压缩与验证 |
| `src/functions/replay.ts` | Crystal 和 Lessons 派生 |
| `src/prompts/summary.ts` | 会话摘要提示词 |
| `src/functions/privacy.ts` | 隐私保护与敏感信息识别 |

---

<a id='mcp-server'></a>

## MCP服务器与工具

### 相关页面

相关主题：[记忆操作](#memory-operations), [搜索与检索](#search-retrieval), [代理插件与集成](#agent-plugins)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx) — 展示MCP兼容代理列表及集成方式
- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx) — 各代理的MCP配置示例
- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md) — MCP包发布流程
- [integrations/pi/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/pi/README.md) — PI扩展与MCP的关系说明
- [website/components/Install.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Install.tsx) — 安装入口及npm包信息
</details>

# MCP服务器与工具

## 概述

MCP（Model Context Protocol）服务器是 AgentMemory 的核心组件之一，它为 AI 代理提供标准化的记忆工具接口。通过 MCP 协议，AgentMemory 能够与各种 AI 代理客户端（如 Claude Desktop、Cursor、Windsurf、VS Code 等）实现无缝集成，使代理能够在对话过程中持久化存储和检索记忆。

AgentMemory 的 MCP 实现包含两个层面：一是作为 MCP 服务器运行，接受代理的工具调用请求；二是通过 MCP 协议与支持该协议的各种代理客户端建立连接。资料来源：[website/components/Agents.tsx:17-21]()

> "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."

## 架构设计

### 协议层结构

AgentMemory 的 MCP 实现采用分层架构设计：

```mermaid
graph TD
    A[MCP客户端<br/>Claude Desktop / Cursor / Cline等] --> B[MCP协议层]
    B --> C[AgentMemory MCP服务器]
    C --> D[REST API层]
    D --> E[记忆存储引擎]
    E --> F[SQLite/文件存储]
    
    G[原生插件<br/>Claude Code / Codex CLI / Hermes等] --> H[直接API调用]
    H --> D
```

### MCP 服务器角色

MCP 服务器在 AgentMemory 架构中承担以下职责：

| 职责 | 说明 |
|------|------|
| 工具注册 | 将记忆操作封装为 MCP 标准工具 |
| 请求路由 | 解析 MCP 请求并分发到对应处理函数 |
| 响应格式化 | 将记忆数据转换为 MCP 协议格式 |
| 连接管理 | 维护与多个客户端的会话状态 |

资料来源：[website/components/Agents.tsx:22-35]()

## 支持的 MCP 客户端

### 一线原生插件（内置支持）

AgentMemory 为以下代理提供原生插件支持：

- **Claude Code** — Anthropic 官方 CLI 代理
- **Codex CLI** — OpenAI 官方代理
- **OpenClaw** — 开源代理
- **Hermes** — 开源代理框架
- **PI** — 代理框架
- **OpenHuman** — 开源项目

```mermaid
graph LR
    A[Claude Code] --> B[原生插件]
    A2[Codex CLI] --> B
    A3[OpenClaw] --> B
    A4[Hermes] --> B
    A5[PI] --> B
    A6[OpenHuman] --> B
    
    B --> C[agentmemory connect命令<br/>自动配置所有插件]
```

资料来源：[website/components/Agents.tsx:17-21]()

### MCP 协议客户端（开箱即用）

以下客户端通过标准 MCP JSON 配置即可使用 AgentMemory：

| 客户端 | 配置文件 | 特殊说明 |
|--------|----------|----------|
| Claude Desktop | `claude_desktop_config.json` | 标准 mcpServers 格式 |
| Cursor | deeplink 一键连接 | 支持 mcpServers |
| Cline | `~/.cursor/mcp.json` | 标准格式 |
| Roo Code | `~/. Roo Code/mcp.json` | 标准格式 |
| Windsurf | `~/.codeium/windsurf/mcp.json` | 标准格式 |
| Gemini CLI | `~/.gemini/mcp.json` | 标准格式 |

资料来源：[website/components/AgentInstall.tsx:8-25]()

## 通用 MCP JSON 配置

### 标准配置格式

大多数 MCP 客户端使用以下配置格式：

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### OpenCode 配置

OpenCode 使用略有不同的配置格式：

```json
{
  "mcp": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### VS Code 配置

VS Code 的 MCP 配置文件位于 `.vscode/mcp.json`，使用 `servers` 键而非 `mcpServers`：

```json
{
  "servers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

资料来源：[website/components/AgentInstall.tsx:26-50]()

## NPM 包分发

### 包信息

MCP 服务器作为独立的 npm 包分发：

| 属性 | 值 |
|------|-----|
| 包名 | `@agentmemory/mcp` |
| 入口文件 | `packages/mcp/bin.mjs` |
| 用途 | MCP 协议服务器实现 |

### 发布流程

MCP 包的发布集成到 AgentMemory 的标准发布流程中：

1. 更新 `packages/mcp/package.json` 中的版本号
2. 同步主包的 `~x.y.z` 版本依赖
3. GitHub Release 触发自动发布

> "The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance."

资料来源：[CONTRIBUTING.md:58-64]()

## MCP 工具接口

### 核心工具列表

通过 MCP 协议暴露的核心记忆工具：

| 工具名 | 功能描述 |
|--------|----------|
| `memory_remember` | 存储新的记忆条目 |
| `memory_recall` | 检索相关记忆 |
| `memory_search` | 基于关键词搜索记忆 |
| `memory_consolidate` | 合并和压缩记忆 |
| `memory_action_create` | 创建待办事项 |

资料来源：[src/viewer/index.html:1-10]()

### 创建 Action 的 MCP 调用示例

```javascript
// MCP 工具调用格式
memory_action_create({ 
  title: "ship v1", 
  description: "完成v1版本发布",
  priority: "high" 
})
```

也可以通过 REST API 调用：

```bash
curl -X POST http://localhost:3111/agentmemory/actions \
  -H 'Content-Type: application/json' \
  -d '{"title":"ship v1","priority":"high"}'
```

资料来源：[src/viewer/index.html:1-10]()

## 与 PI 扩展的关系

PI 代理使用独特的扩展 API 而非 MCP 协议：

> "This extension uses pi's extension API, not MCP, so it can hook directly into the agent lifecycle."

这意味着 PI 代理可以直接访问 AgentMemory 的内部 API，绕过 MCP 协议层，获得更深入的生命周期集成能力。

**共享架构优势**：尽管使用不同协议，一个本地 AgentMemory 服务器可以被 PI、PI2、Hermes、OpenClaw、Claude Code、Codex CLI 和 Gemini CLI 共享。

资料来源：[integrations/pi/README.md:1-10]()

## 快速开始

### 安装 MCP 服务器

```bash
# 通过 npx 直接运行
npx -y @agentmemory/mcp

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

### 配置客户端

1. 打开目标代理的配置界面
2. 找到 MCP 服务器配置区域
3. 添加 AgentMemory 服务器配置
4. 重启代理以加载新配置

资料来源：[website/components/Install.tsx:1-45]()

## 配置示例汇总

### Claude Desktop（macOS）

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### Claude Desktop（Windows）

`%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### Codex CLI（TOML 格式）

`~/.codex/config.toml`:

```toml
[server.agentmemory]
command = "npx"
args = ["-y", "@agentmemory/mcp"]
```

### Hermes（YAML 格式）

`integrations/hermes/plugin.yaml`:

```yaml
# AgentMemory 插件配置
```

### OpenClaw（YAML 格式）

`integrations/openclaw/plugin.yaml`:

```yaml
# AgentMemory 插件配置
```

资料来源：[website/components/AgentInstall.tsx:51-70]()

## 注意事项

1. **数据本地性**：所有记忆数据默认存储在本地机器上，不会上传到第三方服务。

2. **共享服务器**：一个 AgentMemory 服务器实例可以同时为多个代理提供服务。

3. **健康检查**：使用 `/agentmemory-status` 端点验证服务器状态，应返回 `agentmemory healthy`。

4. **协议选择**：
   - 原生插件 → 直接 API 调用
   - MCP 客户端 → MCP 协议层
   - PI 代理 → 扩展 API（非 MCP）

5. **版本同步**：确保 MCP 包版本与主包版本保持一致以获得最佳兼容性。

资料来源：[integrations/pi/README.md:1-5]()

## 相关资源

- [安装指南](../安装指南.md)
- [记忆系统架构](./记忆系统架构.md)
- [集成目录](https://github.com/rohitg00/agentmemory/tree/main/integrations)
- [npm 包页面](https://www.npmjs.com/package/@agentmemory/mcp)

---

<a id='agent-plugins'></a>

## 代理插件与集成

### 相关页面

相关主题：[MCP服务器与工具](#mcp-server), [快速开始](#quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/components/Agents.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/Agents.tsx)
- [website/components/AgentInstall.tsx](https://github.com/rohitg00/agentmemory/blob/main/website/components/AgentInstall.tsx)
- [integrations/openclaw/README.md](https://github.com/rohitg00/agentmemory/blob/main/integrations/openclaw/README.md)
- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)
- [CONTRIBUTING.md](https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md)
</details>

# 代理插件与集成

## 概述

AgentMemory 项目提供了一套完整的代理（Agent）插件与集成系统，支持六种第一方原生插件，并通过 MCP（Model Context Protocol）协议实现对其他第三方代理的广泛兼容。核心通过 `agentmemory connect <agent>` 命令实现自动连接配置，同时支持 MCP 桥接方式和直接插件方式两种深度集成模式。

项目采用统一的内存后端服务（默认运行于 `http://localhost:3111`），所有集成的代理共享相同的记忆存储、检索和检索增强生成（RAG）能力，实现跨代理的上下文一致性。

## 支持的代理类型

### 第一方原生插件

AgentMemory 为以下六个第一方代理提供原生深度集成：

| 代理名称 | 插件类型 | 连接方式 | 特点 |
|---------|---------|---------|------|
| Claude Code | 原生插件 | `agentmemory connect claude-code` | 完整记忆功能，Hook 深度集成 |
| Codex CLI | 原生插件 | `agentmemory connect codex` | 完整记忆功能，Hook 深度集成 |
| OpenClaw | 原生插件/直接插件 | `agentmemory connect openclaw` | 支持直接内存插件模式 |
| Hermes | 原生插件 | `agentmemory connect hermes` | 完整记忆功能 |
| PI | 原生插件 | `agentmemory connect pi` | 完整记忆功能 |
| OpenHuman | 原生插件 | `agentmemory connect openhuman` | 完整记忆功能 |

资料来源：[website/components/Agents.tsx:19-21]()

### MCP 协议兼容代理

除第一方插件外，AgentMemory 通过 MCP 协议实现对所有 MCP 兼容客户端的零成本接入：

| 客户端 | 配置方式 | 连接难度 |
|-------|---------|---------|
| Claude Desktop | DeepLink 一键安装 | ⭐ |
| Cursor | DeepLink 一键安装 | ⭐ |
| VS Code (MCP) | mcp.json 配置文件 | ⭐ |
| Cline | MCP JSON 配置 | ⭐⭐ |
| Roo Code | MCP JSON 配置 | ⭐⭐ |
| Windsurf | MCP JSON 配置 | ⭐⭐ |
| Gemini CLI | MCP JSON 配置 | ⭐⭐ |
| OpenCode | mcp.json (特殊格式) | ⭐⭐ |

资料来源：[website/components/AgentInstall.tsx:1-150]()

## 集成架构

### 系统架构图

```mermaid
graph TD
    subgraph "MCP 客户端层"
        A[Claude Code] --> B[MCP Bridge]
        C[Cursor] --> B
        D[VS Code] --> B
        E[其他 MCP 客户端] --> B
    end
    
    subgraph "第一方插件层"
        F[Claude Code 插件]
        G[Codex CLI 插件]
        H[OpenClaw 插件]
        I[Hermes 插件]
        J[PI 插件]
        K[OpenHuman 插件]
    end
    
    subgraph "集成中间件"
        L[MCP Bridge]
        M[直接插件接口]
    end
    
    subgraph "AgentMemory 核心服务"
        N[API Server :3111]
        O[SQLite 存储引擎]
        P[向量索引]
        Q[记忆整合引擎]
    end
    
    B --> L
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    
    L --> N
    M --> N
    
    N --> O
    N --> P
    Q --> O
```

### MCP 桥接集成模式

MCP 桥接模式适用于所有标准 MCP 客户端，通过 MCP JSON 配置实现连接：

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

通用 MCP JSON 配置兼容以下客户端：
- Claude Desktop
- Cursor
- Cline
- Roo Code
- Windsurf
- Gemini CLI

资料来源：[website/components/AgentInstall.tsx:35-40]()

### 直接插件集成模式

对于支持插件系统的代理（如 OpenClaw），可采用直接插件模式实现更深度的集成：

```json
{
  "plugins": {
    "slots": {
      "memory": "agentmemory"
    },
    "entries": {
      "agentmemory": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:3111",
          "token_budget": 2000,
          "min_confidence": 0.5,
          "fallback_on_error": true,
          "timeout_ms": 5000
        }
      }
    }
  }
}
```

| 配置参数 | 类型 | 默认值 | 说明 |
|---------|------|-------|------|
| base_url | string | http://localhost:3111 | AgentMemory 服务地址 |
| token_budget | number | 2000 | 单次检索的最大 Token 预算 |
| min_confidence | number | 0.5 | 最小置信度阈值 |
| fallback_on_error | boolean | true | 服务不可用时的降级策略 |
| timeout_ms | number | 5000 | 请求超时时间（毫秒） |

资料来源：[integrations/openclaw/README.md:25-45]()

## 插件机制

### 技能系统（Skills）

AgentMemory 的插件系统基于技能（Skills）模块化组织，每个技能封装特定功能：

| 技能名称 | 功能描述 | 触发方式 |
|---------|---------|---------|
| recall | 长期记忆检索 | 自动 RAG / 手动调用 |
| remember | 记忆编码与存储 | 会话结束自动触发 |
| forget | 记忆遗忘与衰减 | 手动调用 / 自动清理 |
| session-history | 会话历史管理 | 跨会话上下文 |

资料来源：[integrations/openclaw/README.md:8-12]()

### 钩子系统（Hooks）

AgentMemory 通过钩子（Hooks）机制实现会话生命周期的深度集成：

```mermaid
graph LR
    A[会话开始] --> B[before_agent_start Hook]
    B --> C[记忆检索]
    C --> D[Agent 执行]
    D --> E[Agent 结束]
    E --> F[agent_end Hook]
    F --> G[记忆整合]
    G --> H[长期存储]
```

| 钩子名称 | 触发时机 | 功能 |
|---------|---------|------|
| before_agent_start | Agent 启动前 | 检索相关长期记忆，构建上下文 |
| agent_end | Agent 完成后 | 捕获对话轮次，执行记忆整合 |

直接插件模式通过 `api.registerMemoryCapability({ promptBuilder })` 注册记忆能力，使代理系统能够识别 AgentMemory 作为活动内存插件。

资料来源：[integrations/openclaw/README.md:47-54]()

## 连接命令

### 快速连接

使用 `agentmemory connect` 命令可自动配置与目标代理的连接：

```bash
# 连接 Claude Code
agentmemory connect claude-code

# 连接 Codex CLI
agentmemory connect codex

# 连接 OpenClaw
agentmemory connect openclaw

# 连接 Hermes
agentmemory connect hermes
```

该命令自动检测代理环境，生成对应的配置文件并完成必要的初始化步骤。

资料来源：[website/components/Agents.tsx:19-21]()

## 记忆运行时

### 记忆运行时后端

AgentMemory 提供统一的记忆运行时后端，所有集成的代理共享相同的记忆存储：

- **语义记忆**：结构化的事实知识，支持置信度评分
- **程序记忆**：可复用的操作步骤和流程
- **关系记忆**：实体间的关联网络
- **观察记录**：原始会话数据，包含工具调用和文件操作
- **水晶（Crystals）**：会话压缩摘要，3 行长度的工作总结
- **教训（Lessons）**：模式纠正记录，带置信度衰减机制
- **行动（Actions）**：待跟进任务，支持状态流转（pending → active → done/blocked）

资料来源：[src/viewer/index.html:150-200]()

### 记忆检索配置

| 参数 | 说明 | 影响 |
|-----|------|-----|
| token_budget | 检索结果的最大 Token 数 | 控制上下文长度 |
| min_confidence | 检索结果的最小置信度 | 过滤低质量记忆 |
| token_limit | 向量检索的 Token 上限 | 控制单次检索范围 |

### 记忆生命周期

```mermaid
stateDiagram-v2
    [*] --> RawObservation: 会话进行中
    RawObservation --> SemanticFact: 整合引擎处理
    RawObservation --> Procedure: 重复模式提取
    RawObservation --> Crystal: 会话结束压缩
    SemanticFact --> ConfidenceDecay: 长期未使用
    Procedure --> ConfidenceDecay: 长期未使用
    Crystal --> [*]: 旧水晶被清理
    ConfidenceDecay --> [*]: 置信度归零删除
```

## 隐私与安全

### 敏感信息处理

AgentMemory 在存储记忆前自动扫描并过滤敏感信息：

```typescript
const SECRET_PATTERN_SOURCES = [
  /(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi,
  /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
  /sk-proj-[A-Za-z0-9\-_]{20,}/g,
  /(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\-_]{19,}/g,
  /gh[pus]_[A-Za-z0-9]{36,}/g,
  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
];
```

同时支持 `<private>` 标签自动过滤：

```xml
<private>
这里的内容不会被存储
</private>
```

资料来源：[src/functions/privacy.ts:1-25]()

## 扩展开发

### 添加新的代理插件

根据 CONTRIBUTING.md 的规范，添加新代理插件需要：

1. **定义钩子类型**：在 `src/types.ts` 的 HookType 联合类型中添加新类型
2. **实现钩子处理器**：在 `src/hooks/<hook-name>.ts` 中编写处理器逻辑
3. **编写测试用例**：使用 Vitest 编写单元测试，验证观察记录正确写入

```typescript
// 1. 添加 HookType
type HookType = 'before_agent_start' | 'agent_end' | 'your_new_hook';

// 2. 实现处理器 src/hooks/your_new_hook.ts
export async function handleYourNewHook(params: HookParams): Promise<void> {
  // 处理逻辑
}

// 3. 编写测试
describe('your_new_hook', () => {
  it('writes observation on trigger', async () => {
    // 测试断言
  });
});
```

### 版本发布

插件系统与主版本同步发布，每次版本更新需要同步修改 8 个文件：

| 文件 | 修改内容 |
|-----|---------|
| package.json | 版本号更新 |
| package-lock.json | 锁文件更新 |
| plugin/.claude-plugin/plugin.json | 插件元数据 |
| packages/mcp/package.json | MCP 包版本 |
| src/version.ts | 版本常量定义 |
| src/types.ts | 导出数据类型 |
| src/functions/export-import.ts | 支持版本列表 |
| test/export-import.test.ts | 版本断言测试 |

资料来源：[CONTRIBUTING.md:1-30]()

## 配置参考

### Claude Desktop 配置

```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### OpenCode 配置

```json
{
  "mcp": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

### VS Code 配置

需要在 `.vscode/mcp.json` 中使用 `servers` 键而非 `mcpServers`：

```json
{
  "servers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}
```

资料来源：[website/components/AgentInstall.tsx:60-90]()

## 总结

AgentMemory 的代理插件与集成系统通过双轨制设计实现了广泛的兼容性：

- **MCP 桥接模式**：一行配置即可连接任何 MCP 兼容客户端
- **直接插件模式**：为支持的代理提供更深的集成能力

所有集成共享同一个记忆后端服务，实现跨代理的上下文连续性，同时通过隐私保护机制确保敏感信息的安全。插件系统采用模块化设计，便于扩展新的代理支持和自定义钩子逻辑。

---

<a id='deployment'></a>

## 部署与运维

### 相关页面

相关主题：[快速开始](#quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)
- [deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)
- [deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)
- [deploy/render/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/render/Dockerfile)
- [deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)
- [deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)
- [src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)
- [src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)
</details>

# 部署与运维

## 概述

AgentMemory 是一个完整的记忆运行时系统，支持多种部署方式以满足不同场景的需求。项目提供了 Docker 容器化部署方案，覆盖本地开发、云平台托管和自托管等多种部署环境。

核心服务默认运行在 **localhost:3111** 端口，提供 HTTP REST API 和 Web 可视化界面。部署架构采用前后端分离设计，后端服务处理记忆存储和检索，前端通过静态资源提供服务。

## 部署架构

### 系统组件

```mermaid
graph TD
    A[客户端] -->|HTTP API| B[AgentMemory 服务 :3111]
    B --> C[SQLite 数据库]
    B --> D[语义记忆存储]
    B --> E[程序记忆存储]
    B --> F[时序图谱存储]
    
    G[Web 查看器] --> B
    
    H[记忆动作系统] --> B
    
    I[MCP 协议接口] --> B
```

| 组件 | 说明 | 默认端口 |
|------|------|----------|
| REST API | 记忆 CRUD 操作接口 | 3111 |
| Web 查看器 | 可视化记忆面板 | 3111 |
| SQLite 存储 | 本地持久化数据库 | - |
| MCP 服务 | 模型上下文协议支持 | - |

### 服务端口配置

服务默认监听 **3111** 端口，Web 查看器通过 `src/viewer/server.ts` 启动静态文件服务器。资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)

```typescript
// 端口配置通过环境变量或默认值设置
const PORT = process.env.PORT || 3111;
```

## Docker 部署

### 多平台 Dockerfile

项目为不同部署平台提供了优化的 Dockerfile 配置：

| 平台 | Dockerfile 路径 | 特点 |
|------|-----------------|------|
| Fly.io | deploy/fly/Dockerfile | 轻量级多阶段构建 |
| Railway | deploy/railway/Dockerfile | 标准 Node.js 镜像 |
| Render | deploy/render/Dockerfile | 兼容 Render 平台 |
| Coolify | deploy/coolify/Dockerfile | 自托管优化 |

#### Fly.io Dockerfile

```dockerfile
# deploy/fly/Dockerfile
FROM node:20-alpine

WORKDIR /app

# 复制 package 文件
COPY package*.json ./

# 安装依赖
RUN npm ci --only=production

# 复制应用代码
COPY dist ./dist
COPY src/viewer ./src/viewer

# 暴露端口
EXPOSE 3111

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3111/health || exit 1

CMD ["node", "dist/index.js"]
```

资料来源：[deploy/fly/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/Dockerfile)

#### Railway Dockerfile

```dockerfile
# deploy/railway/Dockerfile
FROM node:20-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 3111

CMD ["node", "dist/index.js"]
```

资料来源：[deploy/railway/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/railway/Dockerfile)

#### Coolify Dockerfile

```dockerfile
# deploy/coolify/Dockerfile
FROM node:20-alpine

RUN apk add --no-cache dumb-init

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

COPY dist ./dist
COPY src/viewer ./src/viewer

EXPOSE 3111

USER node

ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "dist/index.js"]
```

资料来源：[deploy/coolify/Dockerfile](https://github.com/rohitg00/agentmemory/blob/main/deploy/coolify/Dockerfile)

### 镜像构建

```bash
# 构建本地镜像
docker build -t agentmemory:latest .

# 带平台指定构建
docker buildx build --platform linux/amd64,linux/arm64 -t agentmemory:latest .
```

## Docker Compose 部署

### 本地开发环境

项目根目录的 `docker-compose.yml` 提供了开箱即用的本地部署配置：

```yaml
# docker-compose.yml
version: '3.8'

services:
  agentmemory:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3111:3111"
    environment:
      - NODE_ENV=production
      - PORT=3111
      - DATA_DIR=/data
    volumes:
      - agentmemory-data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3111/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  agentmemory-data:
    driver: local
```

资料来源：[docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/docker-compose.yml)

### Fly.io 部署配置

```yaml
# deploy/fly/docker-compose.yml
services:
  agentmemory:
    build:
      context: ../..
      dockerfile: deploy/fly/Dockerfile
    ports:
      - -3111:3111
    env_file:
      - .env
    volumes:
      - agentmemory-data:/data
    restart: always

volumes:
  agentmemory-data:
    name: agentmemory_data
```

资料来源：[deploy/fly/docker-compose.yml](https://github.com/rohitg00/agentmemory/blob/main/deploy/fly/docker-compose.yml)

### 启动命令

```bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f agentmemory

# 停止服务
docker-compose down

# 重建并启动
docker-compose up -d --build
```

## 环境变量配置

### 核心配置项

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `PORT` | 3111 | 服务监听端口 |
| `NODE_ENV` | production | 运行环境 |
| `DATA_DIR` | ./data | 数据存储目录 |
| `LOG_LEVEL` | info | 日志级别 |
| `MAX_MEMORY_SIZE` | - | 最大记忆存储大小 |
| `DB_PATH` | - | SQLite 数据库路径 |

### 安全配置

```bash
# 设置管理员令牌
export ADMIN_TOKEN=your-secure-token

# 配置 CORS 策略
export CORS_ORIGINS=https://your-domain.com

# 启用 SSL
export HTTPS_ENABLED=true
export SSL_CERT_PATH=/path/to/cert.pem
export SSL_KEY_PATH=/path/to/key.pem
```

## Web 查看器运维

### 静态资源服务

Web 查看器通过 `src/viewer/server.ts` 提供可视化界面：

```mermaid
graph LR
    A[浏览器] -->|HTTP| B[查看器服务器]
    B --> C[index.html]
    B --> D[CSS/JS 资源]
    B --> E[API 数据]
```

资料来源：[src/viewer/server.ts](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/server.ts)

### 查看器功能

Web 界面 (`src/viewer/index.html`) 提供以下运维功能：

- **记忆概览**：查看语义记忆、程序记忆、关系图谱
- **特征标志**：管理功能开关和实验性功能
- **行动追踪**：监控待处理任务和决策
- **会话历史**：查看压缩后的观察记录

资料来源：[src/viewer/index.html](https://github.com/rohitg00/agentmemory/blob/main/src/viewer/index.html)

### 界面渲染逻辑

```javascript
// 查看器渲染核心逻辑
function renderFlags(flags) {
  const pills = flags.map(b => 
    `<span class="flag-pill">${b.icon} ${b.title}</span>`
  ).join('');
  
  const html = `
    <button type="button" class="flag-summary" data-action="toggle-flags">
      ${pills}
      <span class="flag-count">Feature flags</span>
    </button>
  `;
  
  host.innerHTML = html;
}
```

## 健康检查与监控

### 健康检查端点

```bash
# 检查服务健康状态
curl http://localhost:3111/health

# 预期响应
{
  "status": "ok",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "uptime": 3600
}
```

### Docker 健康检查配置

```yaml
healthcheck:
  test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3111/health"]
  interval: 30s      # 检查间隔
  timeout: 10s       # 超时时间
  retries: 3         # 重试次数
  start_period: 10s  # 启动等待时间
```

### 容器状态监控

```bash
# 查看容器健康状态
docker inspect --format='{{.State.Health.Status}}' agentmemory-agentmemory-1

# 查看资源使用
docker stats agentmemory-agentmemory-1

# 查看详细日志
docker logs agentmemory-agentmemory-1 --tail 100 --details
```

## 平台特定部署

### Fly.io 部署

```bash
# 安装 Fly CLI
curl -L https://fly.io/install.sh | sh

# 登录
fly auth login

# 部署应用
fly deploy --config deploy/fly/docker-compose.yml

# 查看部署状态
fly status

# 打开应用
fly open
```

### Railway 部署

1. 连接 GitHub 仓库
2. 选择 `deploy/railway/Dockerfile`
3. 配置环境变量
4. Railway 自动构建和部署

### Render 部署

1. 创建新的 Web Service
2. 连接 GitHub 仓库
3. 设置构建命令：`npm run build`
4. 设置启动命令：`node dist/index.js`
5. 配置环境变量

### Coolify 自托管

1. 添加新项目
2. 配置 Dockerfiles 路径：`deploy/coolify/Dockerfile`
3. 设置端口映射：`3111:3111`
4. 配置持久化存储卷

## 数据持久化

### 存储卷配置

```yaml
volumes:
  agentmemory-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/host/data
```

### 备份策略

```bash
# 备份数据库
docker cp agentmemory:/data/memory.db ./backup-$(date +%Y%m%d).db

# 备份整个数据目录
tar -czf agentmemory-data-$(date +%Y%m%d).tar.gz ./data/

# 恢复数据
docker cp ./backup.db agentmemory:/data/memory.db
```

## 日志管理

### 查看日志

```bash
# 实时日志
docker-compose logs -f

# 错误日志
docker-compose logs --since 1h --filter "level=error"

# 结构化日志输出
docker logs -f agentmemory --tail 200 --timestamps
```

### 日志级别

| 级别 | 说明 | 使用场景 |
|------|------|----------|
| error | 错误信息 | 故障排查 |
| warn | 警告信息 | 性能问题 |
| info | 一般信息 | 正常运行监控 |
| debug | 调试信息 | 开发调试 |

## 故障排查

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 服务无法启动 | 端口被占用 | 修改 PORT 环境变量 |
| 数据库连接失败 | 权限问题 | 检查卷挂载权限 |
| 健康检查失败 | 网络问题 | 检查容器网络配置 |
| 前端加载失败 | 静态资源缺失 | 检查构建产物 |

### 调试命令

```bash
# 进入容器调试
docker exec -it agentmemory sh

# 检查网络连通性
docker exec agentmemory wget -O- http://localhost:3111/health

# 检查文件权限
docker exec agentmemory ls -la /data

# 验证配置
docker exec agentmemory env | grep -E "PORT|DATA_DIR"
```

## 安全建议

### 生产环境配置

1. **启用 TLS/SSL**：使用反向代理或配置 HTTPS
2. **限制 CORS**：设置 `CORS_ORIGINS` 为可信域名
3. **配置认证**：启用 API 令牌认证
4. **定期备份**：配置自动化备份策略
5. **监控告警**：设置资源使用和错误率告警

### 网络安全

```bash
# 使用 Docker 网络隔离
docker network create --driver bridge agentmemory-net

# 限制容器能力
docker run --cap-drop=ALL --security-opt=no-new-privileges \
  agentmemory:latest
```

## 扩展运维

### 水平扩展

```yaml
services:
  agentmemory:
    deploy:
      replicas: 2
    # 需要外部负载均衡器配合
```

### 资源限制

```yaml
deploy:
  resources:
    limits:
      cpus: '1'
      memory: 1G
    reservations:
      cpus: '0.5'
      memory: 512M
```

## 总结

AgentMemory 提供灵活的部署方案，支持从本地开发到云端生产环境的全场景覆盖。通过 Docker 容器化和标准化的配置文件，用户可以在 Fly.io、Railway、Render、Coolify 等主流平台快速部署服务。内置的健康检查、日志管理和 Web 查看器功能为运维工作提供了便捷的监控和调试手段。

---

---

## Doramagic 踩坑日志

项目：rohitg00/agentmemory

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Viewer tab bar is vertically clipped in the web UI。

## 1. 安装坑 · 来源证据：Viewer tab bar is vertically clipped in the web UI

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Viewer tab bar is vertically clipped in the web UI
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2d86f30f32284839bbe09e2f4fa891fe | https://github.com/rohitg00/agentmemory/issues/421 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：npm installs anthropic dependencies

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm installs anthropic dependencies
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5b3aa48c14c3427eb437cdd6d0c8df4f | https://github.com/rohitg00/agentmemory/issues/430 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：v0.9.14 — CLI installer first + agentmemory stop

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.14 — CLI installer first + agentmemory stop
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e87ad4aec26441b791f40bc56394fd76 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.14 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：v0.9.15 — DevEx overhaul

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.15 — DevEx overhaul
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0e8ac022dc044da69396edcdaffdc338 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：v0.9.16 — DevEx polish + agent-memory.dev refresh

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.16 — DevEx polish + agent-memory.dev refresh
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e111eca849634a3c8183575e4a95a54f | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：v0.9.8 — local fallback tools/list returns 7 not 4

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.8 — local fallback tools/list returns 7 not 4
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_25f0b48068964348b51485d9d6a2e0ba | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | host_targets=claude, cursor

## 8. 配置坑 · 来源证据：Viewer tab bar collapses/clips on Windows/Chromium layout

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Viewer tab bar collapses/clips on Windows/Chromium layout
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_db100da50a1d4445a0b58a06dac93baf | https://github.com/rohitg00/agentmemory/issues/422 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | README/documentation is current enough for a first validation pass.

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | last_activity_observed missing

## 11. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose agent_id / session_id in /agentmemory/audit so external rate-limiters can scope per-agent
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c1b3cc10454e4fd09921e3748ad82305 | https://github.com/rohitg00/agentmemory/issues/433 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安全/权限坑 · 来源证据：Support Ollama as a native LLM provider

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Ollama as a native LLM provider
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c87cfb919d5049289e2beec7660ffcf0 | https://github.com/rohitg00/agentmemory/issues/232 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.10 — distroless volume perms + viewer reverse proxy + budget loop
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1bade4c29c91471284081588c913e17d | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.10 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.11 — Codex plugin platform + OpenClaw slot fix + website star button
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_690933973fcf4eb5b034ab92a3c00d23 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.11 | 来源类型 github_release 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.12 — BM25 unicode + vector live-write + viewer hardening + plaintext-bearer guard
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9dd621c8f5654b1f882800d15964ad46 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：v0.9.13

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.13
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3c0eb3c158e9474ea95f58d6b01d4d0b | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.17 — OpenAI-compat provider + telemetry id + Compare polish
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bf5c1b128a5e4e30bc8788b1fe501ce5 | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 20. 安全/权限坑 · 来源证据：v0.9.9 — pinned slot injection + MiniMax env loader

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.9 — pinned slot injection + MiniMax env loader
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e243f84c706f4fcc9bfe7f73f8467ffc | https://github.com/rohitg00/agentmemory/releases/tag/v0.9.9 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 21. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | issue_or_pr_quality=unknown

## 22. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1166408297 | https://github.com/rohitg00/agentmemory | release_recency=unknown

<!-- canonical_name: rohitg00/agentmemory; human_manual_source: deepwiki_human_wiki -->