Agent Memory Workflow

本地优先的 Coding Agent 跨会话长期记忆与事实同步协议

将项目架构、技术事实与本地环境偏好沉淀为可版本化、可审查的标准文件。
使 Claude Code、Codex、Copilot 等各类 Agent 共享统一上下文，消除每次对话的全盘冷启动扫描。

规范标准 · CLI 参考 · FAQ 与设计哲学 · English

---

快速开始

方式 1：通过 NPX 无需克隆直接执行（推荐）

# 1. 在当前工作区初始化标准记忆协议
npx --yes agent-memory-workflow@latest init

# 2. 校验文件合规性与 Schema 完整度
npx --yes agent-memory-workflow@latest verify

方式 2：使用 PowerShell 7 脚本运行

git clone https://github.com/s1oopX/agent-memory-workflow.git
cd agent-memory-workflow

# 运行环境预检与目标项目初始化
pwsh ./scripts/agent-memory-workflow.ps1 preflight
pwsh ./scripts/agent-memory-workflow.ps1 init -TargetDir "D:\projects\my-app"

---

跨 Agent 协同架构

%%{init: {'theme': 'base', 'themeVariables': { 'edgeLabelBackground': '#ffffff', 'mainBkg': '#ffffff', 'lineColor': '#64748b' }}}%%
flowchart TB
    classDef verify fill:#ffffff,stroke:#10b981,stroke-width:1.5px,color:#047857,rx:5px,ry:5px;
    classDef memory fill:#ffffff,stroke:#f59e0b,stroke-width:1.5px,color:#b45309,rx:5px,ry:5px;
    classDef agent fill:#ffffff,stroke:#3b82f6,stroke-width:1.5px,color:#1e40af,rx:5px,ry:5px;
    classDef git fill:#ffffff,stroke:#64748b,stroke-width:1.5px,color:#334155,rx:5px,ry:5px;

    %% 1. 顶部运维
    CLI["CLI 引导工作流 (npx / pwsh)<br/>preflight · init · verify · upgrade"]:::verify

    %% 2. 核心事实层 (3 核心文件)
    M_JSON["agent-memory.json<br/>机器结构化事实 (依赖 · 端口 · 栈)"]:::memory
    M_MD["project-facts.md<br/>架构决策与业务边界 (人类/Agent 共读)"]:::memory
    M_ENV["local-env.md<br/>本机特有环境与工具链版本"]:::memory

    %% 3. 多端 Agent 消费
    A_CLAUDE["Claude Code"]:::agent
    A_CODEX["OpenAI Codex"]:::agent
    A_COPILOT["GitHub Copilot / 自定义 CLI"]:::agent

    %% 4. Git 治理
    GIT_LAYER["Git 仓库版本化追踪 & 增量合并 upgrade"]:::git

    %% 链路走向 (纯无框)
    CLI -->|"模板生成 / Schema 校验"| M_JSON & M_MD & M_ENV

    M_JSON -->|"机器事实装载"| A_CLAUDE
    M_MD -->|"架构约束直读"| A_CODEX
    M_ENV -->|"环境感知"| A_COPILOT

    M_JSON & M_MD & M_ENV -->|"提交与审计"| GIT_LAYER

Loading

---

关键决策

决策维度	采用方案	否决方案	代价与收益
存储介质	纯 Markdown / JSON 文件协议	本地向量数据库 (Chroma / Qdrant)	无法做复杂语义相似度查询，但彻底免除外部守护进程、完全受 Git 版本控制且人类随时可读可审
生效方式	显式文件契约引导	隐式全盘递归扫描 / AST 解析	需在初始化时执行一次规范生成，但将 Agent 冷启动耗时从数十秒降为毫秒级
机器事实与人类描述隔离	agent-memory.json + project-facts.md 物理分离	单一臃肿的混合配置文件	增加了多文件维护成本，但确保 Agent 结构化解析与人类阅读各取所需
版本演进策略	增量备份合并（upgrade 命令）	强制全量覆盖重置	升级脚本需编写复杂的 JSON 合并算法，但确保用户自定义事实永不丢失

---

协议文件结构

在目标工作区执行 init 后，将生成如下标准结构：

.agents/
├── README.md               # 记忆工作流指引与人类维护须知
├── agent-memory.json       # 机器可读核心事实（元数据、技术栈、依赖路径、端口）
├── project-facts.md        # 项目架构事实与关键技术决策（供 Agent 快速阅读）
└── local-env.md            # 本机特有配置（工具链版本、本地服务、环境变量）

向任何新接入的 Agent 发送：

"请先读取当前项目 .agents/agent-memory.json 与 .agents/project-facts.md，基于已有事实开展工作，避免重复执行全盘环境探测。"

---

CLI 命令清单

命令	行为说明	典型场景
preflight	检查本地 PowerShell 7 与工具链依赖	环境首次初始化前自检
init	初始化 .agents 标准记忆文件结构（不覆盖已有事实）	新项目接入工作流
verify	验证 JSON Schema 合规性与必填字段完整度	CI/CD 流程中强校验
status	查询当前目录记忆协议版本与激活状态	快速审计当前工作区
upgrade	在保留用户自定义内容前提下升级协议规范	协议大版本迁移
prompt	打印用于快速复制给 Agent 的标准化引导语	快速交互接入

---

许可

本项目基于 MIT License 开源。