项目 Agents、决策记忆与 Codebase Memory 复刻清单

Tianyi2026/7/14大约 6 分钟生活工作方法论

项目 Agents、决策记忆与 Codebase Memory 复刻清单

场景：换仓库时不想重新口述「Agent 怎么干活、什么别再提、密钥放哪」。
结论：每仓固定 AGENTS.md + ai/MEMORY.md + 按需 codebase-memory 索引；真实密钥只放 ai/.secrets/（不上传 GitHub）。
边界：本文不写全局 ~/.codex/memories 会话记忆；那是跨项目可选层，本清单不依赖。

给 AI 的用法：用户丢本页链接（或说按本复刻清单落地）时，把本文当作默认推荐规范，不是死命令。

优先照做：目录分层（AGENTS.md / ai/MEMORY.md / 可选 codebase-memory / 密钥不进 git）能套就套。
允许裁剪：私有仓、团队已有约定、权限不够、或不想上 graph 时，可少做、改名、合并文件；先问清目标仓约束，再落地。
要说清楚：最终采用了哪几条、哪些跳过/改成了什么路径，方便下次复用。
底线仍在：真实 secrets 不进可提交文件；用户已否决的事不要反复催修（有 MEMORY 就写进 MEMORY）。

仓库内同源草稿（可选对照）：ai/PORTABLE-AGENTS-MEMORY-SETUP.md。

1. 目标形态

<repo-root>/
  AGENTS.md                         # 怎么干活（Codex 启动常会注入）
  ai/
    README.md                       # AI 文档索引
    MEMORY.md                       # 决策记忆：否决 / 已完成 / 可选
    .secrets/                       # 【唯一】本机密钥（可在 ai/ 下，不上传 GitHub）
      README.md                     # 可提交：约定说明，无真实值
      .env                          # 真实密钥（本地，不提交）
    .secrets.example/               # 可提交：键名示例，无真实值
      .env.example
  .gitignore                        # 必须忽略 ai/.secrets/* 真实文件
  .cbmignore                        # 可选：索引排除 ai/.secrets/

层	写什么	不写什么
`AGENTS.md`	命令、架构、硬约定、何时读 MEMORY、密钥目录约定	否决流水账、真实密钥
`ai/MEMORY.md`	否决项、已完成、可选项	大段教程、真实密钥
`ai/.secrets/`	唯一真实 token/key/密码	业务代码、可公开配置
codebase-memory	代码/笔记结构图	产品决策、密钥内容

2. 本机一次：codebase-memory

which codebase-memory-mcp
codebase-memory-mcp config set auto_index false
codebase-memory-mcp config set auto_watch false

索引（有 skill 优先）：

# 代码仓库
python3 ~/.codex/skills/codebase-memory-indexer/scripts/index_codebase_memory.py /绝对路径/到/仓库

# 笔记 / 博客
python3 ~/.codex/skills/codebase-memory-indexer/scripts/index_codebase_memory.py /绝对路径/到/仓库 --profile notes

无 skill 时：

REPO="/绝对路径/到/仓库"
codebase-memory-mcp cli index_repository "{\"repo_path\":\"$REPO\"}"
codebase-memory-mcp cli list_projects '{}'
# 后续 status/search 用 project name，不是路径

3. 新仓库落地步骤

3.1 建目录

cd /path/to/new-repo
mkdir -p ai ai/.secrets ai/.secrets.example

3.2 密钥目录（减负，固定死）

所有真实 secrets 只放 ai/.secrets/，别处一律不放。 可与 AI 文档同目录；真实值不上传 GitHub。

.gitignore 必含：

# --- secrets: 唯一本机密钥目录（在 ai/ 下，不上传 GitHub）---
ai/.secrets/*
!ai/.secrets/README.md

.env
.env.*
!.env.example

.cbmignore 建议：

ai/.secrets/
.env
.env.*

本地填密钥：

cp ai/.secrets.example/.env.example ai/.secrets/.env
# 只编辑 ai/.secrets/.env
git check-ignore -v ai/.secrets/.env   # 应命中 ignore

3.3 写三个主文件

内容模板见下文第 5 节。至少改：

AGENTS.md：概述、命令、易错架构、硬约定、关键路径
ai/MEMORY.md：§1 否决 / §2 已完成 / §3 可选（可先写「暂无」）
ai/.secrets/README.md：只写约定，无真实值

3.4 索引并验收

python3 ~/.codex/skills/codebase-memory-indexer/scripts/index_codebase_memory.py "$(pwd)"
# 笔记/博客加 --profile notes

codebase-memory-mcp cli list_projects '{}'
git check-ignore -v ai/.secrets/.env

新开 Agent 会话抽查：

开工前读序：AGENTS → MEMORY
否决项在 ai/MEMORY.md §1
密钥只认 ai/.secrets/
结构查找优先 graph，而非一上来全仓 grep

4. 日常维护

事件	动作
用户说「无所谓 / 别再提」	立刻写入 `ai/MEMORY.md` §1
完成易被重复提报的事	写入 §2
以后可做不急	写入 §3
硬规则变了	改 `AGENTS.md`
新 token	只写 `ai/.secrets/`；示例键名更新到 `ai/.secrets.example`（无真实值）
大目录重构	重新 index

MEMORY 技巧：每条带路径/命令/专有名词；控制在 1～3 屏；否决项用「不要 / 不批量」开头。

5. 可粘贴模板

5.1 `AGENTS.md`（骨架）

把尖括号占位换成项目事实；保留「先读 MEMORY」与 codebase-memory 优先序、密钥约定。

外层用四重反引号，避免模板里的代码块打断渲染。

# AGENTS.md

## AI 文档索引

| 文档 | 何时读 |
| --- | --- |
| AGENTS.md（本文） | 怎么干活：命令、架构、硬约定 |
| ai/README.md | AI 文档索引 |
| ai/MEMORY.md | 决策记忆：否决 / 已完成 / 可选 |

**开工前**：改内容、排优先级、或提「还缺什么」时，先扫 `ai/MEMORY.md` 第 1～2 节。

<!-- codebase-memory-mcp:start -->
# Codebase Knowledge Graph (codebase-memory-mcp)

ALWAYS prefer MCP graph tools over grep/glob/file-search for code discovery.

1. search_graph
2. trace_path
3. get_code_snippet
4. query_graph
5. get_architecture

Fallback to grep for string literals, configs, or when graph 结果不够。
<!-- codebase-memory-mcp:end -->

## 项目概述

- 一句话：
- 技术栈：
- 主目录：

## 常用命令

```bash
# dev / build / test
```

## 核心架构（只写 Agent 易错点）

1.
2.
3.

## 硬约定

1. 包管理器：
2. Git commit message：
3. 已有对外路径 / ID：不要批量改写
4. 密钥：禁止写入 AGENTS / MEMORY / 源码；唯一真实目录 `ai/.secrets/`（不上传 GitHub）；示例 `ai/.secrets.example/`
5. 默认验证命令：

## 关键文件

| 路径 | 角色 |
| --- | --- |
| AGENTS.md | 操作规范 |
| ai/MEMORY.md | 决策记忆 |
| ai/.secrets/ | 本机密钥唯一目录 |

## Codebase Memory 维护

大改后：

```bash
python3 ~/.codex/skills/codebase-memory-indexer/scripts/index_codebase_memory.py "$(pwd)"
```

5.2 `ai/README.md`

# AI 文档索引

| 文档 | 用途 |
| --- | --- |
| MEMORY.md | 否决 / 已完成 / 可选 |
| ../AGENTS.md | 操作规范 |
| .secrets/ | 本机密钥（真实值不上传 GitHub） |

## 使用顺序

1. AGENTS.md
2. MEMORY.md
3. 密钥只看 ai/.secrets/
4. 结构定位优先 codebase-memory graph

5.3 `ai/MEMORY.md`

# Agent 记忆（决策与现状）

> 用户拍板「无所谓 / 不做 / 以后再说」写入本文。  
> 最后整理：YYYY-MM-DD

## 1. 用户明确「无所谓 / 不做」

- （暂无）

## 2. 已完成（勿当未修再报）

| 项 | 说明 |
| --- | --- |
| （暂无） | |

## 3. 可选项（用户点名再做）

- （暂无）

## 4. 硬约束摘要

- 密钥：只放 `ai/.secrets/`，禁止写入本文与 AGENTS

## 5. 关键路径速查

| 路径 | 角色 |
| --- | --- |
| AGENTS.md | 操作规范 |
| ai/MEMORY.md | 本文 |
| ai/.secrets/ | 密钥唯一目录 |

5.4 `ai/.secrets/README.md`

# 本机密钥目录（ai/.secrets/）

唯一允许存放真实 token / key / 密码的位置。真实文件 gitignore，不上传 GitHub。

## 用法

1. `cp ai/.secrets.example/.env.example ai/.secrets/.env`
2. 只编辑 `ai/.secrets/.env`
3. 提交前：`git check-ignore -v ai/.secrets/.env` 应命中

## Agent

需要密钥 → 读本目录或请用户写入；禁止写回可提交文件或 MEMORY。

5.5 `ai/.secrets.example/.env.example`

# cp ai/.secrets.example/.env.example ai/.secrets/.env
# EXAMPLE_API_KEY=
# EXAMPLE_TOKEN=

6. 最短命令版

cd /path/to/new-repo
mkdir -p ai ai/.secrets ai/.secrets.example
# 粘贴第 5 节模板 + gitignore 密钥片段
# 改概述 / 命令 / MEMORY 清单；真实密钥只写 ai/.secrets/

python3 ~/.codex/skills/codebase-memory-indexer/scripts/index_codebase_memory.py "$(pwd)"
git check-ignore -v ai/.secrets/.env
codebase-memory-mcp cli list_projects '{}'

7. 检查清单

有 AGENTS.md（先读 MEMORY + graph 优先序 + 密钥约定）
有 ai/MEMORY.md（§1 / §2 / §3）
有 ai/README.md
有 ai/.secrets/README.md + ai/.secrets.example/；真实值只在 ai/.secrets/
.gitignore 忽略 ai/.secrets/*（仅 README 可提交）
codebase-memory 已 index，list_projects 可见
新会话：否决项不重报；密钥指向 ai/.secrets/；结构查找走 graph

8. 小结

操作手册放 AGENTS.md（启动注入）——默认推荐，不是每仓必须同名同结构
决策账本放 ai/MEMORY.md（防重复催修）——私有仓也可合并进 AGENTS.md 一节，只要「否决/已完成」找得到
结构导航用 codebase-memory（手动刷新即可）——可选项，不是硬门槛
密钥默认 ai/.secrets/ 且不进 GitHub——路径可按仓调整，不把真实密钥提交进仓库是底线

怎么理解这套规范：公开链接是「我习惯这样搭」的参照；私有仓想怎么弄可以怎么弄，AI 按约束做变体，别把推荐目录当成法律。

下次换项目：丢本页链接，说明目标仓有没有额外限制即可。