project-memory

Project Memory

At the project root's ./tmp/ , maintain aprocess memory: project memory, research explanations, scripts, experiment records, experiment results, current status and future directions.

Itis notproject documentation../docs/ is the conclusions for project readers, and./tmp/ is the process that produced those conclusions.

Core rules

./tmp/ only holds process; the project ./docs/ only holds conclusions. Anything exploratory, failed, temporary, or not yet settled goes into ./tmp/; only content that is stable and valuable to the project "graduates" to ./docs/, with a note recorded in STATE.md .
Experiment definitions and run artifacts are separate. Definitions live in experiments/(small, stable, human-readable), artifacts live in outputs/(many, append-only, written by programs).
Capture is cheap; only settled material gets formatted. Day to day, only append a line to journal/ ; write docs/only once the conclusion is stable. Don't write docs while still doing the work.
Artifacts are not overwritten. Program artifacts are written into outputs/, and their internal structure is decided by the program; the skill does not restrict it — but don't overwrite historical artifacts.
Single entry point. Whenever you need to "understand the current state", read ./tmp/STATE.mdfirst; don't read through the entire ./tmp/。
Deletion is a last resort. Move completed / abandoned things into archive/; don't delete them — the value of memory often lies in "remembering why we gave up back then".
Initialization is lazy. Read only; don't create anything. On the firstwrite, create only the minimal set (.gitignore rules,README.md、STATE.md); create the other directories only as they are used.
Multiple agents only touch their own turf. Open agents/only when multiple agents work in parallel: claim on the task's agents/BOARD.md (claiming is locking), write progress to your own agents/<agent-id>/; the global STATE.md is only summarized at wrap-up.

Directory structure

./tmp/ is the sole root of this memory;the entire directory is by default not committed to version control. The top level (except for scratch/ ) is protected by the "do not delete casually" convention; do not use git clean, cleanup scripts, or manual bulk deletion.

Directoriesare created on demand: what is listed below is "where things should go", not "what must all be created at startup". A directory that doesn't appear simply hasn't been used yet; create it when needed. Whether it actually exists doesn't affect these conventions.

./tmp/
├── README.md            # 这目录是什么、"顶层不可随意删"的约定、入口指引（人读一次）
├── STATE.md             # 【必读】现在 / 进行中 / 下一步 / 待决 / 关键链接
├── journal/
│   └── 2026-09-27.md    # 追加式时间线，一天一个文件
├── docs/                # 沉淀后的稳定内容；演示材料等也放这，形式自由
│   ├── memory/          # 决策、架构、约定、踩过的坑
│   ├── research/        # 研究讲解 / 分析长文 / 论文笔记
│   └── plans/           # 不动手验证的方案、路线图、想法（动手验证就开实验）
├── experiments/         # 实验的「定义与结论」——小、稳定、人读
│   └── EXP-0001-slug/
│       ├── README.md    # 问题/假设/方法/结果/结论/未决
│       ├── config.yaml  # 该实验固定参数
│       └── scripts/     # 实验专属脚本（可复用时才提升到顶层 scripts/）
├── outputs/             # 所有程序产物；内部结构自定
├── annotated/           # 需着重讲解 / 强调的代码
├── agents/              # 多 agent 协作：BOARD.md 任务板 + 各 agent 子目录（并行干活才建）
├── scripts/             # 跨实验复用的工具
├── scratch/             # 真正的草稿，允许随时删
└── archive/             # 完成 / 废弃的东西移到这里，不删

Why artifacts are independent of experiments

Experimentdefinitionsand runartifactshave opposite lifecycles: definitions are few, stable, small, human-readable; artifacts are many, append-only, possibly huge, written by programs. Soartifacts are written into a fixed outputs/ root, do not write into experiments/—this way large files can be cleaned up centrally, and when archiving experiments you won't miss anything or accidentally carry along a pile of data.

outputs/ No conventions are set internally; it is decided by the program that produces it. The cost is that inferring which experiment a product belongs to from the product itself requires finding other clues, so the discipline rests with whoever writes it: product locationrecord in one place—those with an owning experiment go into the experiment's README.md"run log"; those without an owner go into that day's journal/, do not record in both places, and do not record in neither.

Write protocol

Defaultappend only to journal/; only when the conclusion is stable and will still be referenced later, upgrade to docs/(thresholds below).

Lifecycle	When	Where to write	What to put in · what not to put in
Entry	Session wrap-up	`STATE.md`	Now / in progress / next steps / pending decisions / key links; overwrite updates, <150 lines; do not put in the knowledge itself or details
Entry	Write once on first use	`README.md`	Declare that this is memory, list the directory and conventions
Append only, never modify	Any observation / thought / progress that "might be useful later"	`journal/YYYY-MM-DD.md`	One line per item, no formatting; do not put in long formatted text
Append only, never modify	Program-produced products	`outputs/`	Internal structure is self-defined; do not overwrite historical products
Append only, never modify	Experiment finished / idea abandoned	`archive/`	Move, do not delete; do not put in work still in progress
Few and stable	Starting a new experiment	`experiments/EXP-XXXX-slug/`	Definitions and conclusions; do not put in run products
Few and stable	When a tool is reused a second time	`scripts/`	Tools reused across experiments; do not put in scripts specific to a single experiment
Settle after stabilizing	A decision / convention / architecture / pitfall is settled	`docs/memory/`	Background → decision → rationale and cost → source
Settle after stabilizing	Research explanation / analysis / paper notes	`docs/research/`	One sentence → body → evidence → unresolved
Settle after stabilizing	New plans / roadmaps / ideas not yet verified by doing	`docs/plans/`	Goal → plan → alternatives and trade-offs → verification method; once verified by doing, start an experiment
Settle after stabilizing	Want to explain a piece of code clearly	`annotated/<slug>(.md \| .<ext> \| /)`	Explain around the code; for any excerpted code, always record the source
Parallel collaboration	Multiple agents working at the same time	`agents/`	Tasks are claimed in `agents/BOARD.md` (claiming is locking); progress is written to each one's own subdirectory; do not put in single-agent workflows
Disposable	Casual drafts	`scratch/`	The only area that can be deleted at will

A few easy-to-get-wrong points：

Products never go into experiments/, always go into outputs/; how they are organized internally is decided by the program.
Experiment-specific scripts go in the experiment directory, and are only promoted to scripts/。
annotated/ when reused by a second experiment; code in there must record its source(original file path + commit/date), otherwise it will quietly drift from the real source; what you excerpted is a copy, not the true source—make changes back in the project source.
docs/ and annotated/ are distinguished by "what state the reader is in when reading"：docs/ is a reference to consult at any time (demo materials, finished products, and scripts also go here),annotated/ is for explaining the implementation around the code. If unsure, ask "who is this for, and on what occasion will it be used?"

Cold-start protocol

When you need to understand the project's current state, or continue previous work:

Read ./tmp/STATE.md. If it doesn't exist, that means there is no memory yet; continue as an empty state—read only, do not initialize。
Read the tail of the latest ./tmp/journal/*.md .
According to STATE.md 's "key links", read the corresponding docs/ documents or experiments/*/README.mdas needed; when ./tmp/agents/ exists, also take a look at the claim status of agents/BOARD.md .
Only go deep into outputs/。

Common operations

Task	Action
First write (lazy initialization)	The first time you write something to `./tmp/` , it is triggered automatically; see "Lazy initialization" below;`.gitignore` append (first check whether there is already a `tmp` rule) → `README.md` write to disk verbatim → `STATE.md` write the minimal skeleton;create the remaining directories when needed; after creating them, inform the user,`scratch/` can be deleted freely, the other top-level ones cannot be deleted
Start a new experiment	Scan `experiments/` and `archive/` to get the next `EXP-XXXX`; create `experiments/EXP-XXXX-slug/{README.md,config.yaml,scripts/}`（do not create an artifact directory）；`README.md` first fill in "Method", leave the conclusion blank and add it after running;`STATE.md`add a line to "In progress", and record a line in that day's journal (with multiple agents, during the process only record BOARD and your own journal, and write back to STATE at the end)
Run scripts / record artifacts	Write artifacts to `outputs/`, do not overwrite; record the location inone place: if it belongs to an experiment, record it in the experiment's `README.md`"Run log"; if it has no owner, record it in that day's `journal/`
Write code explanations	See the `annotated/` section of "Structures of various files"; record the source well
Multi-agent collaboration	Use only when working in parallel: create `agents/` and `BOARD.md`(see the "Multi-agent collaboration" section); after each claims, create your own `agents/<agent-id>/`
Consolidate into documents	Determine the type → `docs/{memory,research,plans}/`; write according to the corresponding structure, fill in the complete front-matter (finalized `status: stable`, still evolving mark `draft`）；`STATE.md`link it in "key links"; write the time range of the source journal into the "Source" section; update the "Conclusion" of the related experiment `README.md` accordingly
Graduate to the project `./docs/`	Ask the user first; do not write to the project `docs/`without authorization; after approval, follow the project docs' own formatrewrite(not copying `./tmp/` 's formatting);`STATE.md` record a line "Graduated: <tmp path> → <docs path>";`./tmp/` keep the original file,`status` mark `deprecated` or move `archive/`
Wrap-up	Update `STATE.md` 's "Now / In Progress / Next", move completed items away or into `archive/`; index the conclusions scattered in the day's `journal/` (write them into `docs/` or attach links); if an experiment is completed → add the `README.md` conclusion; write remaining blockers into "Pending / Blocked"
Archive	Completed / abandoned experiments:`experiments/EXP-XXXX-slug/` → `archive/EXP-XXXX-slug/`, move or delete the corresponding artifacts along with them; for outdated documents first `status: deprecated`, and only if they truly have no reference value move them to `archive/`

Multi-agent collaboration

Multiple agents simultaneouslyonly enable this when working in the same project; with a single agent the entire agents/ directory does not exist. The root STATE.md is still the sole entry point, and the global view does not fragment into N copies. When this section conflicts with the default flow in "Common Operations", this section prevails: during work, state goes only into BOARD and one's own subdirectory; global files are written back only at wrap-up. (If each agent is in its own git worktree,./tmp/ are not shared with each other, and the conventions in this section do not apply.)

./tmp/agents/
├── BOARD.md           # 共享任务板：任务 / 认领人 / 状态 / 产物链接
└── <agent-id>/        # 每个 agent 一份（id 认法见规则 1）
    ├── STATE.md       # 该 agent 自己的现状 / 下一步
    └── journal/       # 该 agent 自己的时间线，一天一个文件（约定同全局 journal）
        └── 2026-10-12.md

BOARD.md one line per item (both tasks and file occupancy count):

Task / Occupancy	Claimant	Status	Artifacts / Notes
EXP-0003 result analysis	claude-1	In Progress	outputs/exp-0003/
Edit `docs/memory/缓存策略.md`	codex-2	Occupied	Release upon completion

Rules:

Identify the id first, then the task. For agent-id, prefer the name specified by the user or environment; when multiple sessions of an agent with the same name run concurrently, add a sequence number (claude-1、claude-2). Before creating a directory, first scan agents/, and do not collide with names.
Claiming is locking. To take on a task, or to modify docs/、experiments/ or a file in a shared area such as BOARD.md , first add/modify a registration line in done, and do not touch other people's lines.
Write only in your own territory. Each agent writes only to its own agents/<agent-id>/ and its own few lines in BOARD; the root STATE.md and global journal/ are not touched during work.
Write back to the global view at wrap-up. At the end of a session, write the one sentence "worth the global view knowing" into the root STATE.md(Now / In Progress / Next), and leave the details in your own subdirectory.
BOARD holds only status and links, not task details—put details in the task's own document or journal, and link to it from one BOARD line.

Format conventions

Timestamp: journal filename YYYY-MM-DD.md; document front-matter date YYYY-MM-DD; inline time HH:MM. Use local time.
Experiment ID: format EXP-0001，four-digit zero-padded, monotonically increasing, never reused(even if the experiment is archived). Directory name EXP-0001-<slug>, slug in lowercase kebab-case, ≤5 words, self-explanatory. When creating a new one, scan experiments/ to take the current maximum number +1, and also check archive/, to avoid reusing numbers.
File naming: documents use English kebab-case (storage-latency-model.md); titles may be in Chinese, but filenames should remain cross-platform stable.
outputs/: No internal structure is prescribed, and no built-in metadata is required; the only requirement is to record the artifact location inone place—if it belongs to an experiment, record it in the experiment's README.md"run log"; if it has no owner, record it in the day's journal/。

Structure of each type of file

The value of structure isthat one glance tells you where to look. Field names are not mandatory, but keep the section order and the sections that exist as much as possible.

STATE.md(overwrite update, <150 lines):## 现在 → ## 进行中 → ## 下一步 → ## 待决 / 阻塞 → ## 关键链接 → ## 已毕业。

Experiment README.md：状态 → 问题 → 假设 → 方法 → 结果 → 结论 → 未决 → 运行记录(table, each row points to the actual artifact location in outputs/ ). Initially fill in only up to "Method", and add conclusions after running—open it first.

docs/ document:memory = background → decision → rationale and cost → sources;research = one sentence → body → evidence → open questions;plan = goal → approach → alternatives / trade-offs → verification method.

annotated/<topic-slug>: form is unrestricted; choose the least effortful one based on the content—<slug>.md pure explanation (code embedded in the document in code blocks),<slug>.<ext> annotated source snippets (the comments themselves are the explanation),<slug>/ topic directory (one copy of the explanation and one of the code, or add a few variants / diffs).The only hard requirement: for code excerpted from project source, record the source (original file path + commit/date), at the top of the file or in a README in the same directory.

docs/ demo-type content has no independent form requirement—slides, a one-pager, demo scripts, and finished html can go directly next to the corresponding document or in the same directory assets/; whether to add README.md to explain who it is for is also up to you;docs/ only accumulates stable conclusions and finished products, and the form is free.

Document front-matter

All docs/**/*.md must include:

---
title: 标题
type: memory | research | plan      # 主类型；演示等自由形态的内容填实际形态即可
status: draft | stable | deprecated
created: 2026-09-27
updated: 2026-09-27
tags: []
related: [EXP-0001]
---

status starts from draft , change to stableonce the content is stable, and change to deprecatedwhen outdated (do not delete directly).related uses the experiment ID or relative path to link together "which experiments produced this conclusion".

journal entry

- 15:30 做了什么 / 观察到什么 / 为什么

One line per entry, no complete sentences required, no formatting required; one file corresponds to one day, and a new file is created when crossing days; append only, do not go back and organize.

`docs/` threshold for

docs/ and scratch/ is not "degree of accumulation", butwhether you want to keep it：

	Want to keep it?	Organization	Temporality
`scratch/`	No (no loss if discarded)	None	Current draft
`journal/`	Yes (as arecord）	None, by time	Strong—"which day it happened"
`docs/`	Yes (asknowledge）	Yes, by topic	Weak—decoupled from time

Entering docs/ requires satisfying two points at the same time: ① decoupled from time—it can be understood without knowing the context at the time, and is not a running log; ② someone will come look it up—some future decision / experiment will point back to it. Maturity is expressed with status: draft → stable ,there is no need to wait until it is fully settled. If unsure, keep it in journal/。

Artifact metadata (optional)

outputs/ has no internal convention, and whether an artifact carries its own source is decided by the program. If you want the artifact to be able to prove its origin, you can have the program write one itself:

{
  "experiment": "EXP-0001",
  "command": "python scripts/run.py --config config.yaml",
  "started_at": "2026-09-27T15:30:12+08:00",
  "duration_s": 123.4,
  "git": { "rev": "abc1234", "dirty": true },
  "inputs": ["config.yaml"],
  "artifacts": [{ "path": "metrics.csv", "bytes": 2048 }],
  "status": "ok"
}

status Suggested note ok | failed | interrupted—Failed / interrupted artifacts are equally worth keeping.

Links and references

Documents link to each other using relative paths, ensuring they are clickable in editors / renderers. Conclusions point to evidence:docs/ references outputs/ the actual path in , rather than copy-pasting numbers.

Lazy initialization (on first write)

There is no separate "initialization" step: read-only (cold start, looking things up) creates nothing. The trigger condition is—the first time you need towrite ./tmp/, and ./tmp/README.md does not exist. At this point, only do the following minimal set of actions:

Confirm the current directory is the project root (./tmp/ should be created here, not in a subdirectory).
Ensure .gitignore has /tmp/(see "Project .gitignore append" below; if the rule already exists, do not add it again).
./tmp/README.md Write to disk verbatim (see below).
./tmp/STATE.md Write a minimal skeleton (see below).
Only create the path to be written this time(plus the entry file above); create the remaining directories when they are needed, and do not pre-create a bunch of empty directories.

Steps 2 and 3 areirreversible protection, and cannot be skipped: without .gitignore, process memory will be committed into the version repository, and later git clean -fdx will clear it along with everything else; without README.md, no one will know later that this directory is not garbage. Everything else is just convenience, so save effort wherever possible.

The following three passages of textare written to disk verbatim(not suggestions that can be freely rewritten).

1. `./tmp/README.md`

# ./tmp — 项目过程性记忆

> **这个目录不是临时垃圾。** 顶层内容（除 `scratch/` 外）是开发与研究探索的过程记忆，**不要用 `git clean`、清理脚本或手工批量删除**。
> 只有 `scratch/` 可以随时删除。

## 这是什么

- 探索中的、失败的、临时的、还没定论的东西都在这里。
- 项目正式文档在 `./docs/`；本目录只保存"过程"。只有稳定且对项目有价值的结论才"毕业"到 `./docs/`。

## 先看哪里

1. `STATE.md` — 当前状态与下一步（唯一入口）
2. `journal/` — 最近的原始记录
3. 其余按需：`docs/`、`experiments/*/README.md`、多 agent 时的 `agents/BOARD.md`

## 目录

| 目录 | 用途 | 可删？ |
|---|---|---|
| `STATE.md` | 现状 / 进行中 / 下一步 / 待决 / 关键链接 | 否 |
| `journal/` | 追加式时间线 | 否 |
| `docs/{memory,research,plans}/` | 沉淀后的稳定内容 | 否 |
| `experiments/` | 实验的定义与结论（不含产物） | 否 |
| `outputs/` | 程序产物（内部结构自定） | 否 |
| `annotated/` | 代码讲解与带注释的源码片段 | 否 |
| `agents/` | 多 agent 协作：BOARD.md 任务板 + 各 agent 子目录 | 否 |
| `scripts/` | 跨实验复用的工具 | 否 |
| `archive/` | 完成 / 废弃的东西 | 否 |
| `scratch/` | 草稿、一次性文件 | **可以** |

> 目录按需创建：还没出现的目录只是还没用到。

## 脚本输出约定

- 程序产物统一写 `outputs/`，内部结构由程序决定，不设约定。
- 跑完把产物位置记在一处：有归属实验记实验 `README.md`「运行记录」，没归属记当天 `journal/`。

## 约定

- 结果不可变：每次运行独立目录，不覆盖历史。
- 只追加 journal，不回头整理；稳定了才写 `docs/`。
- 多 agent 并行时启用 `agents/`：任务上 `BOARD.md` 认领，进展写各自 `agents/<agent-id>/`，全局 `STATE.md` 只在收尾时更新。
- 详细规则见 project-memory skill。

2. Project `.gitignore` append

# ./tmp —— 过程性记忆，默认不进版本库（整个目录）
/tmp/

3. `./tmp/STATE.md`(minimal skeleton)

Entry file, updated by overwrite. Initially it is empty; fill it in when there is content:

# STATE

## 现在

## 进行中

## 下一步

## 待决 / 阻塞

## 关键链接

## 已毕业