AMS

AMS（Agent Memory System）是一套给 Codex、Cursor、Claude Code、opencode、Gemini CLI 等开发 Agent 共用的项目记忆系统。

项目总纲

AMS 是给开发 Agent 用的“项目记忆账本”：它不是替代 Agent 推理能力的自动知识大脑，也不是把所有历史对话塞进上下文窗口的记录器，而是一层可审计、跨 Agent、可同步的项目记忆基础设施。

它的核心价值是让多个开发 Agent 共享同一套项目约定、历史决策、踩坑记录、任务摘要和后续事项。一次任务结束后，关键背景不会只留在某个 Agent 的临时会话里；下一次 Codex、Cursor、Claude Code、opencode 或其他 Agent 接手时，可以从同一个记忆仓库中检索、引用和延续这些知识。

AMS 以 Git 和 Markdown 作为长期事实源，以本地索引提供搜索、关联、上下文组装和最近记录能力，以 MCP、CLI、REST 等入口接入不同 Agent。读记忆可以自动发生，写入长期事实则需要经过 Session 记录、候选提炼和用户确认，避免 Agent 把临时判断、错误推断或过期信息直接沉淀成 canonical memory。

因此，AMS 最适合承担三类职责：

• 连续性：保存跨会话、跨工具、跨天仍然重要的项目背景和决策原因。
• 可审计性：每条长期记忆都落在可读、可 diff、可回滚的 Markdown/Git 事实源中。
• 协作性：让不同 Agent 和不同用户围绕同一个项目记忆仓库工作，而不是各自维护割裂的私有上下文。

它用记忆仓库中的 Markdown 作为长期事实源，用本地索引提供搜索、关联、上下文组装、Session 记录和长期记忆候选确认能力。未指定仓库时优先使用上次激活的记忆库；没有历史选择时才创建并使用 default_repo，默认目录是 .ams/repositories/default/；每个仓库可以被多个 user 共享，但记忆文件按 user 隔离。

安装

从本仓库本地使用：

npm install
npm link

发布成 npm 包后可全局安装：

npm install -g @piflow.org/ams

也可以在项目内作为开发依赖安装：

pnpm add -D @piflow.org/ams

快速开始

进入任意项目根目录：

ams user use rudy
ams project start

ams user use rudy 会把本机默认记忆用户写入全局配置 ~/.ams/config.json。ams project start 会自动：

• 选择当前项目要使用的记忆仓库，并初始化 .ams/config.json。如果当前目录已经有记忆仓库，会默认使用该仓库；如果没有，会提示创建新记忆库、使用本机已有记忆库或导入 GitHub 记忆库。
• 生成 Codex、Cursor、Claude Code、opencode 接入说明。
• 默认安装项目级 Agent MCP 配置，相当于执行 ams project install-agent。
• 建立本地索引。
• 启动或复用本机唯一 ams daemon，并注册当前项目。
• 由 daemon 监听当前记忆仓库中的 Markdown 变化、增量更新索引并调度同步/导入任务。

通常只需要在项目里执行一次 ams project start 完成接入。之后即使 Agent 重启，只要仍在这个项目下并重新读取项目级 MCP 配置，就会通过 HTTP MCP 连接本机 AMS daemon；记忆系统会持续生效，直到执行 ams project disable。

如果只想初始化：

ams project init

手动重建索引：

ams index

检查状态：

ams doctor

ams doctor 会返回当前记忆仓库、索引、Git 状态、文档数量、daemon 状态，以及 agent_mcp_configs 中的 Agent MCP 配置检查结果。

关闭当前项目的 AMS 记忆系统：

ams project disable

关闭后，AMS 不再在本项目中检索、写入、索引或维护记忆；已有记忆文件会保留，不会被删除或清空。重新启用：

ams project enable

查看启用状态、当前仓库和索引状态：

ams project status

单独重装 Agent MCP 接入配置：

ams project install-agent

ams project install-agent 默认会在当前项目内写入或更新常见 Agent 的专属 MCP 配置：

• .cursor/mcp.json
• .codex/mcp.json
• .opencode/mcp.json

可以用 --agent codex、--agent cursor 或 --agent opencode 只刷新某个 Agent，也可以用 --agent all 明确刷新全部专属配置。共享 .mcp.json 不再默认写入；只有显式加 --shared 时才会写入。

写入内容为 mcpServers.ams，默认使用 HTTP MCP 直连本机 daemon，例如 http://127.0.0.1:8765/mcp，并通过 X-AMS-Project 固定当前项目目录。已有其他 MCP server 和未知字段会被保留；如果目标 JSON 文件无效，AMS 会先把原文件重命名为 *.invalid-<timestamp>，再写入新的配置。ams doctor 会在发现旧 direct stdio 配置或重复配置时返回 warning。

CLI 使用

AMS 默认使用 ~/.ams/config.json 中的本机默认用户，以及 .ams/config.json 中的当前记忆仓库。也可以用 --repo 临时指定仓库：

ams --repo personal search "鉴权 API"

命令总览

多数项目级命令既可以写成 ams <command>，也可以写成 ams project <command>，例如 ams status 和 ams project status 等价。全局选项 --repo / --repository 可临时选择记忆仓库，--user 可临时选择记忆用户。

| 命令 | 典型用法 | 功能说明 | | --- | --- | --- | | ams help | ams help | 显示 CLI 帮助和主要命令列表。未知命令也会返回帮助。 | | ams user use | ams user use rudy | 设置本机默认记忆用户，写入 ~/.ams/config.json。 | | ams user current | ams user current | 查看本机当前默认记忆用户。 | | ams project start | ams project start | 初始化当前项目、安装 Agent MCP 配置、启动或复用本机 daemon，并注册当前项目。 | | ams project init | ams project init | 初始化当前项目的 .ams/config.json、记忆仓库目录、索引和 Agent 使用说明。 | | ams project enable | ams project enable | 启用当前项目的 AMS 记忆系统。 | | ams project disable | ams project disable | 禁用当前项目的 AMS 记忆系统；保留已有记忆文件。 | | ams project status | ams project status | 查看当前项目健康状态，包括仓库、索引、Git、daemon、同步和 MCP 配置。 | | ams doctor | ams doctor | status 的诊断别名，用于排查当前项目 AMS 状态。 | | ams project install-agent | ams project install-agent --agent codex | 写入或刷新 Agent MCP 配置；支持 --agent codex\|cursor\|opencode\|all、--transport http、--shared。 | | ams daemon start | ams daemon start | 启动本机单例 AMS daemon。 | | ams daemon status | ams daemon status | 查看 daemon 运行状态、端口、已注册项目等信息。 | | ams daemon stop | ams daemon stop | 停止本机 AMS daemon。 | | ams daemon restart | ams daemon restart | 重启本机 AMS daemon。 | | ams repo list | ams repo list | 查看全局注册的记忆仓库。 | | ams repo current | ams repo current | 查看当前激活记忆仓库。 | | ams repo add | ams repo add company /path/to/memory [index-dir] | 添加一个命名记忆仓库，可指向项目内目录或外部目录；同名仓库已存在时提示 ams repo use <name> 复用。 | | ams repo import | ams repo import personal [email protected]:org/repo.git --user rudy | 克隆并全局注册已有 Git 记忆仓库；同名仓库已存在时提示复用，支持 --dir、--dry-run、--force。 | | ams repo use | ams repo use company | 切换全局默认记忆仓库。 | | ams index | ams index | 扫描当前记忆仓库 Markdown，重建本地索引。 | | ams search | ams search "鉴权 API" | 搜索当前 user 的记忆内容，返回相关文档和片段。 | | ams recent | ams recent session 5 | 查看最近记忆记录；可指定类型和数量。 | | ams related | ams related decisions/auth.md 10 | 根据路径或 id 查找相关记忆内容。 | | ams graph | ams graph architecture.md 2 | 查看某条记忆的关系图，第二个参数是深度。 | | ams context | ams context "实现鉴权 API" | 为任务组装上下文包，包含相关记忆和来源路径。 | | ams begin | ams begin "实现鉴权 API" | Agent 任务开始入口；返回健康状态、任务相关上下文、近期 Session、来源和 token 开销。 | | ams session add | ams session add session.json | 写入 Session Summary；参数可为 JSON 文件、JSON 字符串或 - 从 stdin 读取。 | | ams propose | ams propose proposal.json | 创建待审查的长期记忆修改 Proposal。 | | ams review | ams review 10 | 查看待确认长期记忆候选。 | | ams approve | ams approve <id> approve | 对候选执行 approve、edit、skip 或 never 决策。 | | ams history import | ams history import --agent codex --since 30d | 导入当前项目相关的 Agent 历史对话，生成摘要和候选记忆；支持 --dry-run。 | | ams history status | ams history status | 查看历史对话导入状态、统计和错误。 | | ams history reset | ams history reset --before 2026-07-01 | 重置历史导入记录，不删除 canonical memory。 | | ams docs import | ams docs import --path README.md | 分析并导入项目 Markdown 文档，生成摘要和候选记忆；支持 --since、--max、--dry-run。 | | ams docs status | ams docs status | 查看项目文档导入状态。 | | ams docs reset | ams docs reset --path README.md | 重置项目文档导入记录，不删除 canonical memory。 | | ams sync | ams sync --pull --push | 同步当前记忆仓库与远端 Git；支持 --status、--pull、--push、--dry-run、--force。 | | ams usage | ams usage --week --date 2026-07-02 | 汇总记忆上下文 token 开销；支持日、周、月统计和日报开关。 | | ams mcp-proxy | ams mcp-proxy --project /path/to/project | 显式启动 stdio 到 daemon HTTP MCP 的轻量桥接，主要用于调试或特殊客户端。 | | ams mcp | ams mcp | 已移除 direct stdio 项目入口；会返回 DIRECT_STDIO_REMOVED，请使用 daemon 或 mcp-proxy。 | | ams rest | ams rest | 启动 REST API 服务，默认监听 127.0.0.1:8765。 |

设置或查看本机默认用户：

ams user use rudy
ams user current

ams project init 和非交互式 ams project start --repository <name> 不会自动创建未知仓库。新仓库必须由用户显式注册或导入：

ams repo add proj_ams .ams/repositories/proj_ams
ams project init --repository proj_ams

如果指定的仓库尚未通过 ams repo add 注册、通过 ams repo import 导入，或在交互式启动中选择创建，命令会返回 UNKNOWN_REPOSITORY。

ams project start 未指定 --repo / --repository 时，会先查找当前目录下已经存在的记忆库。如果找到了，就直接使用该记忆库启动项目；如果当前目录还没有记忆库，则进入交互选择：

1. Create a new memory repository
2. Use an existing local memory repository
3. Import a GitHub memory repository

在非交互环境中，如果当前目录没有记忆库且未指定 --repo，ams project start 会返回 START_REPOSITORY_REQUIRED，提示显式指定仓库或改用交互模式。

如果全局配置中还没有 activeUser，ams project init 和 ams project start 会交互式提示你输入用户名，并写入 ~/.ams/config.json：

Choose an AMS memory username:

也可以通过环境变量指定：

ams repo add proj_ams .ams/repositories/proj_ams
AMS_USER=rudy ams project start --repository proj_ams

搜索记忆：

ams search "鉴权 API"

查看最近记录：

ams recent session 5

生成任务上下文：

ams context "实现 MCP memory_search 工具"

按 Agent 任务开始语义读取当前激活记忆库：

ams begin "实现 MCP memory_search 工具"

ams begin 和 MCP 工具 memory_begin_task 使用同一套 workflow，会返回任务相关上下文、近期 Session、健康状态和来源路径。它主要用于 Agent 没有直接发现 MCP memory 工具时的 fallback；只要项目已经存在 .ams/config.json 且 enabled 不是 false，Agent 应默认先用 memory_begin_task，不可用时再运行 ams begin "<task>"。

返回结果包含 memory_prompt_overhead，用于让 Agent 在最终回复中说明本次记忆系统带来的提示词开销：

{
  "memory_prompt_overhead": {
    "tokens": 320,
    "token_count": 320,
    "tokenizer": "ams-estimate-v1",
    "is_estimate": true,
    "bytes": 1234,
    "encoding": "utf8",
    "included": true,
    "measured_fields": ["context_pack.sections", "recent_sessions", "sources"]
  }
}

token_count 是基于可注入提示词的记忆 payload 计算的 token 数量，bytes 是同一 payload 的 UTF-8 字节数，两者都不包含 health 诊断信息。默认 tokenizer 是本地确定性估算器 ams-estimate-v1，因此 is_estimate 为 true；如果后续接入模型专用 tokenizer，可以把该字段标成精确计数。Agent 最终回复应使用紧凑格式报告 token 开销，例如 mem:320 tkns；如果没有把记忆内容整合进本次工作或回复，应报告 mem:0 tkns。

写入 Session Summary：

ams session add '{
  "agent": "codex",
  "task": "实现基础搜索",
  "completed": ["完成 Markdown 扫描", "完成关键词搜索"],
  "changed_files": ["src/core/search.js"],
  "decisions": ["MVP 暂不引入向量搜索"],
  "failed_attempts": [],
  "risks": [],
  "todos": ["补充 BM25"],
  "next_actions": ["完善测试"],
  "suggested_candidates": [{
    "content": "AMS MVP 暂不引入向量搜索，先使用 Markdown 分块和关键词加权排序。",
    "target_path": "architecture.md",
    "reason": "长期搜索实现决策",
    "risk": "low",
    "confidence": 0.86,
    "action": "append"
  }]
}'

查看待确认长期记忆：

ams review

确认写入长期记忆：

ams approve <candidate-id>

导入当前项目下 Codex、Cursor、Claude Code、opencode 的历史对话：

ams history import
ams history import --agent codex --since 30d
ams history import --dry-run
ams history status
ams history reset --before 2026-07-01

ams project start 会注册当前项目，并由本机 ams daemon 在后台触发历史对话导入。导入过程按对话时间排序、按来源 hash 去重，只保存摘要、来源引用和长期记忆候选；长期记忆候选仍需通过 ams review 与 ams approve 人工确认。

分析并导入当前项目的 Markdown 文档：

ams docs import
ams docs import --path README.md
ams docs import --since 30d --dry-run
ams docs status
ams docs reset --path README.md

ams project start 默认也会让 daemon 在后台触发项目 Markdown 分析。默认会排除 .ams/、Agent 配置目录、docs/plans/、依赖目录和构建产物；导入结果同样以摘要和候选长期记忆为主，不会直接把未经确认的长期规则写入正式记忆。

同步当前记忆仓库和远端 Git 仓库：

ams sync --status
ams sync --pull
ams sync --push
ams sync --pull --push
ams sync --dry-run --pull --push

ams project start 会确保本机 daemon 正在运行，并由 daemon 启动同步调度：启动和定期检查会后台拉取远端变更；读记忆前会按节流规则触发轻量后台检查，不阻塞当前搜索或上下文组装；写 Session、确认候选、创建 Proposal、历史导入和项目文档导入完成后会触发去抖后的本地提交与推送。同步只作用于记忆仓库的 Git 根目录，不会提交当前项目代码仓库。index/、cache/、embeddings/ 和 sync/ 是运行时目录，不会被自动提交；远端拉取成功后会重建本地索引。

同步失败不会阻止本地读写。网络不可用、非快进或冲突会记录在 ams sync --status、ams project status 和 ams doctor 的 sync 字段中；默认使用 pull --ff-only，不会自动覆盖用户记忆或执行 force push。--dry-run 只返回计划，不创建 commit、不写状态、不执行 Git 写操作。

查看记忆系统带来的 token 开销统计：

ams usage --day 2026-07-02
ams usage --week --date 2026-07-02
ams usage --month 2026-07

ams usage 会读取当前记忆仓库和当前 user 的 usage 事件，返回调用次数、总 token、平均 token、最大 token、总 bytes、tokenizer 和 top tasks。统计事件只保存元数据，不保存完整 prompt、记忆正文或上下文片段。关闭或重新开启次日首次使用时的自动昨日报告：

ams usage --disable-report
ams usage --enable-report

创建 Proposal：

ams propose '{
  "title": "补充搜索排序策略",
  "reason": "实现过程中确认 MVP 需要稳定排序规则",
  "target_paths": ["architecture.md"],
  "proposed_changes": "建议补充关键词、路径、标签的权重规则。",
  "impact": "影响基础搜索实现和测试用例。"
}'

记忆仓库

查看已配置的记忆仓库：

ams repo list

ams repo list 只显示全局注册的记忆仓库。记忆仓库不再分项目级和全局级；项目配置只保存启用状态、Agent MCP 配置等项目上下文。全局配置会在仓库的 locations 中保留使用过该仓库的项目目录，便于排障和迁移。

全局配置中的 repositories.<name> 是本机记忆库的命名注册表。ams repo add、ams repo import、交互式 ams project start 创建新库，以及 ams repo rename 的目标名称都会按 name 去重：如果已有同名记忆库，命令会返回该记忆库的 memoryDir、githubUrl、locations 等信息，并提示运行 ams repo use <name> 共享复用。ams repo import --force 可用于明确接受更新已有导入元数据或远端设置。

添加公司、项目或个人记忆仓库：

ams repo add company /path/to/company-memory
ams repo add personal /path/to/personal-memory

导入已有 Git 记忆仓库：

ams repo import personal https://github.com/example/ams-memory.git --user rudy

ams repo import 默认会 clone 到 ~/.ams/repositories/<name>/，并写入全局 ~/.ams/config.json。后续同一台电脑的其他项目可以直接使用该全局仓库；另一台电脑只需要再次执行同一条 import 命令即可 clone 并注册已有仓库。

可选参数：

ams repo import personal [email protected]:example/ams-memory.git --user rudy --dir ~/.ams/repositories/personal
ams repo import personal https://github.com/example/ams-memory.git --user rudy --dry-run

--dry-run 只返回计划动作，不 clone、不写配置、不创建 user 目录。Git URL 不能包含 Token、用户名密码或 query 参数；AMS 不会把凭据写入配置、输出或导入命令元数据。同名仓库已注册时，默认不会再次 clone 或覆盖配置；确认要更新已有注册信息时再使用 --force。

切换当前默认记忆仓库：

ams repo use company

查看当前仓库：

ams repo current

仓库路径可以在当前项目内，也可以是绝对路径或 ~ 路径指向另一个 Git 仓库或本机目录。每个仓库都有独立的记忆目录、索引目录、本地 Git 仓库和可选 GitHub 远端地址。

第一次创建记忆仓库时，AMS 会初始化该目录为本地 Git 仓库，并尝试通过 GitHub CLI 创建默认私有远端仓库。默认 GitHub 仓库名由 user 和记忆仓库名共同生成，例如 ams-rudy-team_memory。创建成功后，远端地址会写入该仓库的 githubUrl。如果本机未安装或未登录 gh，本地仓库仍会创建成功，GitHub 远端创建会被跳过并返回原因。

如果希望显式指定仓库目录，使用 ams repo add <name> <memory-dir> [index-dir]。如果想快速创建并启动一个新仓库，可以运行交互式 ams project start，然后选择 Create a new memory repository。

User 隔离

仓库根目录是共享的，记忆文件按 user 存放：

.ams/repositories/proj_ams/
  .git/
  repo.json
  users/
    rudy/
      memory/
        project.md
        architecture.md
        sessions/
        proposals/
        index/
    bob/
      memory/
        project.md
        architecture.md
        sessions/
        proposals/
        index/
  shared/
    memory/

repo.json 记录仓库中的 user：

{
  "name": "proj_ams",
  "users": {
    "rudy": {
      "memoryDir": "users/rudy/memory",
      "role": "member"
    }
  },
  "shared": {
    "enabled": true,
    "memoryDir": "shared/memory",
    "writePolicy": "review"
  }
}

默认搜索和写入当前 user 的记忆。可以用 --user 临时切换：

ams search "架构" --repository proj_ams --user bob

在候选记忆和 Proposal 中，target_path / target_paths 表示所选记忆仓库内的相对路径，例如 architecture.md 或 decisions/adr-auth.md。历史写法 .memory/architecture.md 仍兼容。

MCP 使用

启动或查看本机单例 daemon：

ams daemon start
ams daemon status

项目级 MCP 配置默认使用 HTTP MCP 直连 daemon：

{
  "mcpServers": {
    "ams": {
      "transport": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "X-AMS-Project": "/path/to/project"
      }
    }
  }
}

如果要访问指定记忆仓库，在工具参数中传 repository：

{"id":1,"tool":"memory_search","params":{"repository":"personal","query":"架构","limit":3}}

HTTP MCP 支持标准 MCP JSON-RPC 风格方法：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"memory_begin_task","arguments":{"repository":"company","task":"实现自动记忆接入"}}}

标准 MCP tools/call 返回 structuredContent，其中包含原始工具结果。ams mcp-proxy --project <path> 可作为 stdio 到 daemon 的轻量桥接；它只转发请求，不启动索引监听、同步调度或导入 worker。旧的 direct stdio ams mcp 不再作为项目入口。

可用工具：

• memory_begin_task
• memory_search
• memory_related
• memory_recent
• memory_context_pack
• memory_finish_task
• memory_add_session
• memory_propose_update
• memory_review_proposals
• memory_confirm_candidate
• memory_approve_proposal
• memory_graph
• memory_health
• memory_sync
• memory_sync_status
• memory_usage_report
• memory_usage_report_notice

推荐 Agent 工作流：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_begin_task","arguments":{"task":"实现鉴权 API"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_finish_task","arguments":{"agent":"codex","task":"实现鉴权 API","completed":["完成登录接口"],"changed_files":["src/api/auth.js"],"decisions":["登录接口使用 Token 鉴权"],"failed_attempts":[],"risks":[],"todos":[],"next_actions":[]}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"memory_confirm_candidate","arguments":{"id":"<candidate-id>","decision":"approve"}}}

memory_confirm_candidate 必须带有用户明确选择的 decision，支持 approve、edit、skip、never。不要在没有用户确认时自动 approve。

REST API

ams project start 启动的本机 daemon 同时提供 REST 路由；通常直接访问该 daemon 即可：

curl 'http://127.0.0.1:8765/api/v1/health'

ams rest 仅用于独立调试服务：

ams rest

它默认也监听 127.0.0.1:8765，因此 daemon 正在运行时不要同时执行该命令；如需独立运行，请先停止 daemon 或在 .ams/config.json 中设置不同的 rest.port。

daemon 默认监听：

http://127.0.0.1:8765

示例：

curl 'http://127.0.0.1:8765/api/v1/memory/search?query=架构&limit=3'
curl 'http://127.0.0.1:8765/api/v1/memory/search?repository=personal&query=架构&limit=3'
curl 'http://127.0.0.1:8765/api/v1/memory/usage?period=day&date=2026-07-02'
curl 'http://127.0.0.1:8765/api/v1/health'

配置

配置文件：

.ams/config.json
~/.ams/config.json

默认项目配置会由 ams project init 生成。AMS 会按 defaultConfig -> ~/.ams/config.json -> .ams/config.json -> CLI 参数 的顺序合并配置。默认 user 和记忆仓库注册只来自全局配置、环境变量或 CLI 参数；项目级 .ams/config.json 不保存也不覆盖默认 user、默认仓库或仓库列表。不要把密钥、Token 或其他敏感凭据写入任何 AMS 配置。

全局配置示例 ~/.ams/config.json：

{
  "activeUser": "rudy",
  "activeRepository": "default_repo",
  "repositories": {
    "default_repo": {
      "memoryDir": "~/.ams/repositories/default",
      "indexDir": "~/.ams/repositories/default/index",
      "githubUrl": ""
    },
    "company": {
      "memoryDir": "/path/to/company-memory",
      "indexDir": "/path/to/company-memory/index",
      "githubUrl": "https://github.com/example/company-memory.git"
    },
    "personal": {
      "memoryDir": "~/.ams/repositories/personal",
      "indexDir": "~/.ams/repositories/personal/index",
      "githubUrl": "https://github.com/example/personal-memory.git",
      "source": {
        "type": "git",
        "url": "https://github.com/example/personal-memory.git",
        "importCommand": "ams repo import personal https://github.com/example/personal-memory.git --user rudy",
        "importedAt": "2026-07-01T09:50:00.000Z"
      }
    }
  }
}

项目配置示例 .ams/config.json：

{
  "enabled": true
}

• enabled: 当前项目是否启用 AMS 记忆系统。ams project disable 会把它设为 false，但不会删除已有记忆。
• activeRepository: 本机默认使用的记忆仓库名，只写在 ~/.ams/config.json。ams repo use <name>、ams project init --repository <name> 和 ams project start --repository <name> 会更新全局默认仓库。
• activeUser: 本机默认记忆用户，只写在 ~/.ams/config.json。使用 ams user use <user> 修改；项目级配置不会保存该字段。
• memoryDir / indexDir: 全局仓库的记忆目录和索引目录，兼容旧配置。
• repositories: 全局命名仓库列表。default_repo 是内置默认仓库，和其他仓库使用相同结构；也可以继续添加公司知识、项目知识、个人偏好等独立仓库。
• githubUrl: 该记忆仓库对应的 GitHub 远端地址。首次创建仓库且 GitHub CLI 可用时会自动写入。
• source: 可选导入元数据。repo import 会写入清洗后的 Git URL、导入命令和导入时间，便于排障和迁移。
• usageStats.enabled: 是否记录记忆 token 开销 usage 事件。关闭后 ams usage 返回禁用状态，历史 usage 文件保留。
• usageStats.dailyReport.enabled: 是否在次日首次 memory_begin_task / ams begin 时返回昨日报告提示。
• usageStats.dailyReport.autoOnFirstUse: 是否自动在首次使用时附带 usage_report_notice。

default_repo 是内置默认仓库，默认指向全局配置中的仓库路径。额外仓库通过 ams repo add <name> <memory-dir> [index-dir] 写入全局配置。

工作流程

AMS 的完整工作流程分为项目启用、Agent 接入、任务开始、任务执行、任务结束、长期记忆确认和维护检查七步。

1. 项目启用

在项目根目录执行：

ams project start

AMS 会先初始化项目记忆目录和默认配置：

• 当前记忆仓库：长期记忆、Session、Proposal 等 Markdown 事实源。默认是 .ams/repositories/default/。
• .ams/config.json: 当前项目的 AMS 配置。
• AGENTS.md、CLAUDE.md、.cursor/rules/ams.md、OPENCODE_AMS.md: Agent 侧使用说明。

随后 AMS 会建立本地索引，启动或复用本机 ams daemon，由 daemon 监听当前记忆仓库中的 Markdown 变化并提供 HTTP MCP 服务。

2. Agent 接入

ams project start 默认会执行 ams project install-agent，在当前项目内写入 Agent 专属 HTTP MCP 配置。Agent 读取这些配置后，会直接连接本机 AMS daemon，发现并调用 AMS 工具。

这一步是持久配置：后续 Agent 或对话重启后，不需要再次手动运行 ams project start 才能使用记忆。只要项目级 MCP 配置仍存在且 .ams/config.json 的 enabled 不是 false，AMS 记忆系统就会继续工作；执行 ams project disable 后，除健康检查外的记忆工具会返回 MEMORY_DISABLED。

如果 MCP 配置需要修复或刷新，可以单独执行：

ams project install-agent

3. 任务开始

Agent 开始处理一个非平凡任务前，应先调用：

memory_begin_task

AMS 会根据任务描述搜索当前记忆仓库，返回任务相关上下文、近期 Session、健康状态和来源路径。Agent 在回答或改代码时应保留来源路径，方便审计。

当 Agent 使用这些记忆上下文完成回答或代码修改时，最终回复必须用 mem:<memory_prompt_overhead.token_count> tkns 报告本次记忆系统带来的 token 提示词开销。如果返回的记忆上下文为空，或未把记忆内容整合到提示词中，应报告 mem:0 tkns。bytes 可以作为辅助诊断信息展示，但不再是默认回复口径。

如果 usage 统计开启，AMS 会为本次 begin 写入一条 usage event。若自动日报开启且昨天有 usage 数据，AMS 会在每天首次 begin 时返回 usage_report_notice，Agent 可简短展示，例如 AMS yesterday: 8 calls, mem:12000 tkns。

如果当前对话没有把 MCP memory 工具直接暴露给 Agent，但项目根目录已经配置并启用了 AMS，Agent 应从项目根目录运行：

ams begin "<task>"

并在继续工作前使用返回的上下文。这让“已激活记忆库的项目默认先读记忆”不完全依赖宿主是否成功加载 MCP 工具。

4. 任务执行中

如果任务中需要更多项目知识，Agent 可以按需调用：

• memory_search: 搜索相关记忆。
• memory_recent: 查看近期记录。
• memory_related: 查找与某个记忆文件相关的内容。
• memory_context_pack: 重新组装任务上下文。

5. 任务结束

Agent 完成任务后调用：

memory_finish_task

AMS 会写入一条 Session Summary，并从 decisions 或 suggested_candidates 中生成长期记忆候选。候选只会进入待确认状态，不会直接覆盖长期记忆。

6. 用户确认长期记忆

如果 memory_finish_task 返回候选，Agent 应在当前对话中让用户选择：

• approve: 写入长期记忆。
• edit: 使用用户编辑后的内容写入。
• skip: 本次跳过。
• never: 不再记录这类候选。

Agent 必须先把每条候选的可决策信息展示给用户，不能只输出 candidate id。至少包含：

• id
• content
• target_path
• reason
• risk
• confidence
• action
• recommended_decision
• recommendation_reason

Agent 应基于 recommended_decision 给出明确建议，例如“建议 approve，因为置信度高且风险低”；但仍必须等待用户显式确认，不能自动执行建议。

用户确认后，Agent 才能调用：

memory_confirm_candidate

AMS 写入当前记忆仓库中的目标 Markdown 文件，并重建索引。

7. 状态检查和维护

可随时执行：

ams doctor

它会检查当前记忆仓库、索引、Git 状态、文档数量，以及项目级 Agent MCP 配置是否存在和是否包含 ams server。

工作原理

AMS 的核心原则是：Markdown 是事实源，索引是缓存，Agent 通过 MCP/API 访问，长期记忆写入必须经过治理。

目录和事实源

当前 user 的记忆目录是 canonical source。默认项目仓库位于 .ams/repositories/default/，默认 user 的记忆位于 users/<user>/memory/。常见内容包括：

• project.md: 项目背景和边界。
• architecture.md: 架构和关键模块。
• conventions.md: 编码、测试、提交和文档约定。
• decisions/: 长期技术决策。
• sessions/: Agent 任务执行摘要。
• proposals/: 待确认的长期记忆候选和修改提案。

AMS 不把索引或向量结果当作事实源。索引可以删除后重建，长期事实以记忆仓库中的 Markdown 为准。

索引和检索

ams index 或 ams project start 会扫描当前记忆仓库中的 Markdown，解析 front matter、标题、正文分块和关联字段，生成本地索引。

检索时 AMS 会结合：

• 标题、路径、标签和正文关键词。
• 本地 term-frequency 向量相似度。
• 文档状态，例如 deprecated 或 superseded 会降权。
• related、module、tags 等显式关系。

memory_context_pack 和 memory_begin_task 会基于搜索结果组装带来源路径的上下文包，而不是把整个记忆仓库塞给 Agent。

MCP 和 REST 访问层

AMS 提供两类访问入口：

• HTTP MCP: 给 Codex、Cursor、Claude Code、opencode 等 Agent 调用。
• REST API: 给脚本、调试工具或外部系统调用。

MCP 层支持：

• 标准 MCP JSON-RPC 风格的 initialize、tools/list、tools/call，适合 Agent 自动发现工具。

MCP 工具参数支持可选的 repository 字段。未指定时使用 .ams/config.json 中的 activeRepository。

Session 和长期记忆候选

任务结束时，Agent 调用 memory_finish_task 或 memory_add_session。AMS 会将任务目标、完成内容、修改文件、关键决策、风险、TODO 和后续动作写入当前记忆仓库的 sessions/YYYY/MM/DD/。

长期记忆候选来自两类输入：

• Agent 显式提交的 suggested_candidates。
• Session 中的 decisions，AMS 会默认转成写入当前记忆仓库 decisions/auto-decisions.md 的候选。

候选会保存到当前记忆仓库的 proposals/candidates.json，等待 review/approve。

memory_finish_task 会同时返回 confirmation_request，其中包含面向用户展示的候选详情和允许的决策值。Agent 应优先使用该结构组织确认问题，避免只把 id 抛给用户。

Safe 写入治理

AMS 默认采用 safe 模式：

• 读可以自动。
• Session 写入可以自动。
• 长期记忆候选可以自动生成。
• canonical memory 不能自动覆盖，必须由用户确认。

memory_confirm_candidate 和 memory_approve_proposal 都要求明确的用户决策。确认后，AMS 才会把内容 append 或 create 到目标记忆文件，并重建索引。

安全边界

AMS 在写 Session、Proposal 或长期记忆前会执行 secret scan。检测到疑似密钥时，根据配置阻止写入，避免把 Token、密钥或隐私信息沉淀进项目记忆。

记忆维护流程

AMS 默认采用 safe 模式：

1. Agent 任务开始前调用 memory_begin_task。
2. 如果 MCP 工具不可见，但项目已启用 AMS，Agent 任务开始前运行 ams begin "<task>" 作为 fallback。
3. Agent 任务中按需调用 memory_search、memory_recent 或 memory_related。
4. Agent 完成任务后调用 memory_finish_task。
5. AMS 写入 Session Summary 并自动提炼长期记忆候选。
6. Agent 在当前对话中展示每条候选的 id、content、target_path、reason、risk、confidence 和 action，再提示用户 approve、edit、skip 或 never。
7. 用户确认后，Agent 调用 memory_confirm_candidate，AMS 写入 canonical memory 并重建索引。

长期事实不会默认被 Agent 直接覆盖。

自测

npm test