agent-memory

<p align="center"> <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >=22"> <img src="https://img.shields.io/badge/pnpm-11.3-F69220?style=flat-square&logo=pnpm&logoColor=white" alt="pnpm 11.3"> <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"> <img src="https://img.shields.io/badge/status-production--grade-6f42c1?style=flat-square" alt="Production Grade"> </p> # 代理内存 > 面向编码代理的本地优先项目内存系统。捕获持久知识，检索相关上下文，防止重复错误，并生成可审计的协议收据 — 所有这些都来自本地 SQLite 存储。 Agent Memory 是一个 CLI-first 工具。它将审查的项目规则、决策、命令策略、失败尝试、修复和可重用的经验教训存储在 `.agent-memory/` 下。代理在规划之前检索该上下文，在运行高风险命令之前，提出不受信任的内存候选，并生成显示实际发生情况的会话收据。 无需托管服务。无需云同步。默认情况下，无外部嵌入调用。完整的 MCP 表面，代理适配器，生命周期管理，导入/导出，备份/恢复/修复和可复制的实时代理证明框架。 --- ## 目录 - [安装](#installation) - [快速开始](#quick-start) - [CLI 命令](#cli-commands) - [协议主干](#protocol-spine) - [检索引擎](#retrieval-engine) - [安全模型](#safety-model) - [MCP 服务器](#mcp-server) - [代理适配器](#agent-adapters) - [内存生命周期](#memory-lifecycle) - [导入/导出](#import--export) - [备份/恢复/迁移](#backup--restore--migrations) - [评估和基准](#evaluations--benchmarks) - [存储库布局](#repository-layout) - [开发](#development) - [文档](#documentation) - [贡献](#contributing) - [许可证](#license) --- ## 安装 ```bash # 从源码 git clone https://github.com/hemang-doshi/agent-memory.git cd agent-memory pnpm install --frozen-lockfile pnpm build pnpm cli --help # 或通过 npm（发布后） npm install -g agent-memory-preflight agentmem --help ``` **要求**: Node.js ≥22, pnpm 11.x。 --- ## 快速开始 ```bash # 初始化项目 agentmem init # 将代理路由器安装到 AGENTS.md agentmem install-instructions # 存储内存 agentmem add "使用 pnpm 进行包操作。" --type workflow_rule --tag package-manager # 检索相关内存 agentmem retrieve "更新包操作" --file package.json --json # 检索混合模式 + 说明 agentmem retrieve "更新包操作" --mode hybrid --explain --json # 生成内存包（markdown） agentmem inject "更新包操作" --format markdown # 在运行命令之前检查 agentmem preflight --command "pnpm test" --json ``` --- ## CLI 命令 ### 核心操作 ```text agentmem init [--git-init] [--json] 初始化 Agent Memory agentmem install-instructions 安装路由器到 AGENTS.md agentmem uninstall-instructions 删除路由器从 AGENTS.md agentmem doctor [--index|--deep] [--json] 检查项目健康状况 ``` ### 内存 CRUD ```text agentmem add <content> --type <type> [--source <source>] 创建活动内存 agentmem update <id> --reason <r> [--content ...] 更新内存 agentmem forget <id> --reason <r> 存档内存（非破坏性） agentmem list [--type <t>] [--all] [--json] 列出内存 agentmem search <query> [--type <t>] [--json] 搜索内存 agentmem explain <memory-id> 显示内存和事件 agentmem stale <memory-id> --reason <r> 将内存标记为过期 ``` ### 快捷内存命令 ```text agentmem decision <content> decision 类型快捷方式 agentmem failed <content> failed_attempt 类型快捷方式 agentmem policy <content> --match <pattern> 命令策略类型快捷方式 agentmem remember <content> --type <type> add 别名 ``` ### 检索和注入 ```text agentmem retrieve <task> [--mode determ|keyword|hybrid|vector] 检索内存 [--rerank] [--reranker none|noop|mock] [--explain] [--file <p>] [--command <c>] [--limit n] [--json] agentmem explain-retrieval <task> [--mode ...] [--json] 检索并显示完整解释 agentmem pack <task> [--session <id>] [--json] 生成内存包 agentmem inject <task> [--session <id>] [--json|--format md] 生成并注入包 agentmem preflight --command <cmd> [--session <id>] [--json] 检查命令是否符合策略 ``` ### 索引 ```text agentmem index [--rebuild|--vector] [--json] 重建关键字或向量索引 ``` ### 协议和会话 ```text agentmem session start <task> [--json] 启动会话 agentmem session finish --session <id> --summary "..." [--json] 结束会话 agentmem session receipt --session <id> [--json] 查看会话收据 agentmem protocol start <task> [--json] 会话 + 初始包 agentmem protocol check --session <id> [--json] 检查协议合规性 agentmem dogfood report --session <id> [--json] 生成 dogfood 报告 agentmem event record --session <id> --type <t> --summary "..." 记录证据 agentmem event list --session <id> [--json] 列出事件 ``` ### 候选人审查 ```text agentmem candidate propose --session <id> --type <t> --content "..." 提出候选人 [--evidence "..."] [--evidence-event <id>] [--json] agentmem candidate list [--status proposed] [--json] 列出候选人 agentmem candidate approve <id> [--json] 批准候选人 → 活动内存 agentmem candidate reject <id> --reason "..." [--json] 拒绝候选人 agentmem manage --plan [--json] 查看候选人审查计划 ``` ### 生命周期 ```text agentmem review [--json] 标记需要审查的内存 agentmem dedupe [--resolve] [--json] 查找（或解决）重复内存 agentmem merge --target <a> --source <b> --reason <r> [--json] 合并两个内存 agentmem supersede --old <a> --new <b> --reason <r> [--json] 替换旧内存为新内存 agentmem quality [--json] 生成质量报告 agentmem purge-expired [--json] 存档过期内存 ``` ### 吸收和导入/导出 ```text agentmem ingest <file> --as candidates [--json] 吸收文件为候选人 agentmem ingest-log <file> --as candidates [--json] 吸收日志为候选人 agentmem export [--output <file>] [--json] 导出内存存储 agentmem import <file> [--json] 导入内存存储 ``` ### 安全 ```text agentmem scan [--deep] [--json] 扫描秘密和提示注入 agentmem audit [--json] 完整安全审计报告 agentmem quarantine <id> --reason <r> [--redact] [--json] 从注入中删除不安全的内存 agentmem unquarantine <id> --reason <r> [--json] 恢复隔离的内存 ``` ### 操作 ```text agentmem migrate status|up [--json] 查看或应用迁移 agentmem backup [--output <dir>] [--json] 备份 .agent-memory/ 存储 agentmem restore <backup-path> [--json] 从备份恢复 agentmem repair [--json] 修复索引 + 检查损坏 ``` ### 评估和基准 ```text agentmem eval [--json] 运行 V1 确定性评估（5 项检查） agentmem eval live [--write-report] [--json] 运行实时代理证明框架（8 种场景） agentmem benchmark run --fixture <path> [--json] 运行单个基准测试固件 agentmem benchmark run --all [--json] 运行所有协议基准测试 ``` ### MCP 和适配器 ```text agentmem mcp serve [--json] 启动 MCP 服务器（stdio） agentmem adapters list [--json] 列出可用的代理适配器 agentmem adapters install <adapter> [--json] 安装适配器说明 agentmem adapters uninstall <adapter> [--json] 删除适配器说明 ``` --- ## 协议主干 协议主干添加本地审计轨迹。启动会话并加载内存包： ```bash START=$(agentmem protocol start "Implement feature X" --json) SESSION=$(printf '%s' "$START" \ | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>console.log(JSON.parse(s).sessionId))') # 在规划前使用返回的内存包 agentmem preflight --command "pnpm test" --session "$SESSION" --json agentmem event record --session "$SESSION" --type command_result --summary "Tests pass." --json agentmem candidate propose --session "$SESSION" --type known_fix \ --content "Reusable lesson learned." --evidence "Details..." --json agentmem session finish --session "$SESSION" --summary "Feature X implemented." --json agentmem protocol check --session "$SESSION" --json ``` 合规的最小会话有：`session_started`, `pack_loaded`, 和 `session_finished`. --- ## 检索引擎 Agent Memory 支持四种检索模式，均为本地： | 模式 | 描述 | |------|-------------| | `deterministic` | **默认**。令牌重叠 + 类型/严重性/置信度评分 + 固定/优先级 + 最近 + 命令匹配。无外部依赖。 | | `keyword` | SQLite FTS5 全文搜索，BM25 排名。 | | `hybrid` | 可加性地合并确定性、关键字和向量结果。 | | `vector` | 基于本地哈希的 64 维嵌入 + 余弦相似度。无外部调用。 | **重排序**：可选，默认为关闭。支持 `none`/`noop` （保留顺序），`mock` （词法重排序）。外部 LLM 重排序需要提供适配器 — 默认不连接。 **安全门**：所有模式共享一个可见性门（`isAgentVisibleMemory`），排除存档、拒绝、隔离、取代、过期、编辑、秘密标记、不安全、提示注入标记和不受信任的内存。 --- ## 安全模型 Agent Memory 设计用于本地项目状态，而不是秘密管理。 - **写入时阻止**：在内存创建和候选人提案中拒绝明显的秘密（API 密钥、令牌、密码）。 - **深度扫描**：`agentmem scan --deep` 在内存、事件和候选人中检测 14 个秘密模式 + 4 个提示注入模式。 - **可见性门**：`isAgentVisibleMemory()` 确定性地排除所有检索、注入、预检、向量搜索和 MCP 路径中的不安全内存。无 LLM 依赖。 - **隔离**：`agentmem quarantine` 非破坏性地从所有路径中删除不安全的内存。`agentmem unquarantine` 在审查后恢复。 - **信任级别**：`trusted`、`reviewed`、`low`、`untrusted`。不受信任的内存从所有检索路径中排除。 - **候选人默认不受信任**：代理提出的内存必须在成为活动内存之前进行审查。 - **存档记录，不删除**：保留审计轨迹。 - **编辑**：支持 `redacted` 和 `blocked` 状态 — 均从注入中排除。 内存内容是数据，不是权威。检索的内存不会覆盖受信任的命令策略或用户指令层次。 --- ## MCP 服务器 `agentmem mcp serve` 启动 JSON-lines stdio MCP 环路。 | 功能 | 行为 | |---------|----------| | 默认只读 | 7 个资源和 9 个读取工具可用，无需配置 | | 写工具配置门控 | 需要 `mcp.write_tools_enabled` 在项目配置中 | | 候选人批准单独门控 | 还需要 `mcp.candidate_approval_enabled` | | 无 shell 执行 | MCP 不暴露命令执行表面 | | 项目隔离 | 所有查询范围限定为项目；未初始化的根目录被拒绝 | **资源**：项目、内存、包、会话收据、候选人、扫描、检索说明。 **工具**：协议启动、检索、注入、预检、事件记录、候选人提案/列表/批准/拒绝、协议检查、扫描、创建/更新/忘记内存。 --- ## 代理适配器 六个适配器生成幂等安装/卸载块： | 适配器 | 目标 | |---------|--------| | `codex` | `AGENTS.md` | | `claude-code` | `CLAUDE.md` | | `cursor` | `.cursor/rules/agent-memory.mdc` | | `command-code` | `.commandcode/taste/agent-memory.md` | | `opencode` | `AGENTS.md` | | `generic` | `AGENTS.md` | 所有适配器都使用适配器特定的 HTML 标记 — 多个适配器可以在同一个文件中共存而不会冲突。安装是幂等的；卸载保留用户在受控块之外的内容。 --- ## 内存生命周期 - **审查**：标记需要关注的内存（未经验证、过期、隔离、低置信度、安全标志、编辑、低/不受信任的信任级别）。 - **重复检测**：通过规范化 `type:content` 检测重复项。 `--resolve` 自动合并组。 - **合并**：合并标签、路径和关系；存档源。 - **取代**：用新内存替换旧内存；旧内存从所有检索路径中排除。 - **质量**：计算总内存、可注入、重复、过期、不安全和低信任内存。 - **过期**：`purge-expired` 存档内存超过其 `expiresAt` 时间戳。 每个生命周期变化都会创建审计事件。 --- ## 导入/导出 ```bash agentmem export --output backup.json agentmem import backup.json ``` - **格式**：`agent-memory-v2-json` 信封，具有溯源块。 - **安全**：导入的内容会进行秘密扫描；重复项被跳过（可配置）。 - **溯源**：每个导入记录都带有 `agentMemoryProvenance` 元数据，链接回源项目和时间戳。 - **候选人默认**：导入的文件和日志成为候选人，而不是活动内存。 --- ## 备份/恢复/迁移 ```bash agentmem backup # 备份到 .agent-memory/backups/ agentmem backup --output /safe/path # 自定义备份位置 agentmem restore .agent-memory/backups/...agentmem repair # 重建索引，检查 JSON 损坏 agentmem migrate status # 查看架构版本 + 待处理迁移 agentmem migrate up # 应用待处理列迁移 ``` - 备份是 `.agent-memory/` 目录的文件副本。 - 恢复在覆盖之前创建当前状态的安全备份。 - 修复重建关键字和向量索引，并通过名称显示损坏的 JSON 字段。 - 开放时间迁移是幂等的，并自动添加缺少的列。 --- ## 评估和基准 ### V1 确定性评估（5 项检查） ```bash agentmem eval --json ``` 检查：基本检索、固定包含、冲突处理、秘密编辑、上下文增量。所有确定性，无外部代理。 ### 实时代理证明框架（8 种场景） ```bash agentmem eval live --write-report --json ``` 场景：避免 npm 在 pnpm 仓库中、避免脆弱文件、避免已知失败方法、尊重架构决策、尊重命令预检、提出可重用学习、忽略过期/取代的内存、避免包含秘密的内存。本地确定性框架超过脚本化场景 — 不调用外部模型。 ### 协议基准测试（4 个固件） ```bash agentmem benchmark run --all --json ``` 固件：旧错误避免、噪声控制、基于事件的候选人、命令预检警告。 在隔离的临时工作空间中运行。 --- ## 存储库布局 ``` src/ cli/ 命令解析和终端输出 core/ 内存 CRUD、检索、包、会话、候选人、预检、扫描 vector/ 嵌入提供者 + 本地向量索引 ranking/ 重新排序接口 + 模拟/ noop 实现 safety/ 审计报告、隔离/取消隔离 lifecycle/ 审查、重复检测、合并、取代、质量、过期清除 消化/ 文件/日志消化、块状处理、JSON导入/导出、溯源 运营/ 迁移状态、备份、恢复、修复 MCP/ MCP清单、项目加载器、资源、工具、参数、服务器 适配器/ 适配器注册 + 幂等安装/卸载 评估/ 确定性评估 + 实时代理证明框架 数据库/ SQLite 模式、迁移、存储库访问 域/ 类型、枚举、默认值、守卫、验证器 格式化/ Markdown/文本输出格式化 测试/ 31 个测试文件，181 个测试（单元、集成、CLI、安全、黄金、MCP、适配器） 基准测试/ 确定性基准测试固件 + 黄金测试数据 文档/ 13 个文档文件 + 6 个生产跟踪文件 ``` --- ## 开发 ```bash pnpm install --frozen-lockfile pnpm typecheck pnpm test pnpm build pnpm cli --help ``` **验证清单： ```bash pnpm typecheck # 零错误 pnpm test # 31 文件，181 个测试 pnpm build # 清洁 dist/ pnpm cli eval --json # 5/5 V1 检查 pnpm cli eval live --json # 8/8 实时场景 pnpm cli benchmark run --all # 4/4 固件 node dist/cli/main.js --help # 构建 CLI 匹配源 npm pack --dry-run --json # 清洁包内容 ``` --- ## 文档 | 文档 | 描述 | |----------|-------------| | [快速入门](docs/getting-started.md) | 首次设置和工作流 | | [概念](docs/concepts.md) | 内存、候选人、包、协议收据 | | [架构](docs/architecture.md) | 模块边界和设计决策 | | [检索](docs/retrieval.md) | 所有四种模式 + 重新排序 | | [MCP](docs/mcp.md) | MCP 服务器、资源、工具、安全姿态 | | [适配器](docs/adapters.md) | 代理适配器安装/卸载流程 | | [安全](docs/security.md) | 扫描、审计、隔离、信任模型 | | [评估](docs/evals.md) | 评估命令和证明框架 | | [配置](docs/config.md) | 项目配置模式 | | [迁移](docs/migrations.md) | 备份、恢复、修复、迁移 | | [故障排除](docs/troubleshooting.md) | 常见问题和解决方案 | | [比较](docs/comparison.md) | 与纯文档和外部服务对比 | | [证明报告](docs/proof/live-agent-eval-report.md) | 实时代理评估结果和局限性 | **生产跟踪：** 查看 `docs/production/` 中的实现矩阵、架构决策、验证记录和发布就绪清单。 --- ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)，了解开发设置、工作流期望、测试标准和发布流程。 - 保持更改小、确定性、可审计。 - 为新行为添加测试。 - 不要引入托管服务或云依赖。 - 在报告漏洞之前阅读 [安全策略](SECURITY.md)。 --- ## 许可证 MIT &copy; [Hemang Doshi](https://github.com/hemang-doshi)