release: publish csep 1.3.0

Author: T0UGH

AGENTS.md

@@ -2,15 +2,14 @@
 
 ## Project Structure & Module Organization
 
-This is a Python 3.11+ package using a `src/` layout. Core code lives in `src/codex_self_evolution/`: `cli.py` and `csep.py` expose command-line entry points, `hooks/` handles Codex lifecycle hooks, `review/` handles stop-review providers, `compiler/` promotes suggestions into memory/recall/skills, and `managed_skills/` publishes generated skills. Tests live in `tests/`, with fixtures under `tests/fixtures/`. Documentation and implementation notes live in `docs/` and `notes/`. README images are kept under `docs/assets/` as SVG sources plus committed PNG renderings. Plugin manifests are present in both `src/codex_self_evolution/plugin_bundle/.codex-plugin/` and `plugins/codex-self-evolution/.codex-plugin/`; keep them aligned when changing hook metadata.
+This is a Python 3.11+ package using a `src/` layout. Core code lives in `src/codex_self_evolution/`: `cli.py` and `csep.py` expose command-line entry points, `hooks/` handles Codex lifecycle hooks, `session_recall/` archives and searches historical sessions, `session_reflection/` handles background memory/skill review, and `plugin_bundle/` packages the Codex plugin. Generated plugin skills are mirrored under both `skills/` and `plugins/codex-self-evolution/skills/`. Tests live in `tests/`. Documentation and implementation notes live in `docs/`. README images are kept under `docs/assets/`. Plugin manifests are present in both `src/codex_self_evolution/plugin_bundle/.codex-plugin/` and `plugins/codex-self-evolution/.codex-plugin/`; keep them aligned when changing hook metadata.
 
 ## Build, Test, and Development Commands
 
 - `python -m pip install -e .` installs the package locally with `codex-self-evolution` and `csep` console scripts.
 - `python -m pip install -e '.[dev]'` adds contributor tooling such as `pytest`, `build`, and `twine`.
 - `python -m pytest -q` runs the full test suite; CI runs this on Python 3.11 and 3.12.
 - `make test PYTHON=python3.11` runs the same pytest command through the Makefile.
-- `make preflight PYTHON=python3.11` runs `compile-preflight` against the local `data/` state directory.
 - `python -m build` builds source and wheel distributions.
 - `scripts/install.sh` installs the local CLI with `uv` and refreshes the Codex plugin cache.
 
@@ -20,7 +19,7 @@ Use 4-space indentation, type hints where they clarify interfaces, and small std
 
 ## Testing Guidelines
 
-Use pytest. Name tests `test_*.py` and test functions `test_*`. Add focused coverage beside the behavior being changed, especially for storage state transitions, hook payload handling, CLI flags, and compiler promotion logic. Provider smoke tests require real credentials and are not part of public CI.
+Use pytest. Name tests `test_*.py` and test functions `test_*`. Add focused coverage beside the behavior being changed, especially for storage state transitions, hook payload handling, CLI flags, session recall behavior, session reflection validation, and diagnostics/status output. Provider smoke tests require real credentials and are not part of public CI.
 
 ## Commit & Pull Request Guidelines
 

README.md

@@ -39,7 +39,7 @@ Codex Self-Evolution Plugin，简称 `csep`。它在 `SessionStart` 时把稳定
 
 | 能力 | 写入时机 | 下一次如何使用 |
 | --- | --- | --- |
-| Stable Memory | 达到 trigger 条件后，由 session reflection 写入 `USER.md` / `MEMORY.md` | `SessionStart` 自动注入 Codex 上下文 |
+| Stable Memory | 达到 trigger 条件后，由 session reflection 写入 `MEMORY.md` / `memory/refs/` | `SessionStart` 自动注入 `MEMORY.md` |
 | Session Recall | `Stop` hook 把 transcript 归档到本地 SQLite/FTS；插件内置 `csep-session-recall` skill 教 Codex 如何检索 | `csep recall "needle1|needle2"` 像 `rg` 一样按当前 repo 或全局检索历史证据 |
 | Reflection Skills | reflection worker 写入 `~/.codex/skills/csep-reflect-*` | Codex 原生 skills loader 自动加载 |
 | Runtime Status | hooks、配置、日志、reflection job、recall DB 都可只读检查 | `csep status` 排查当前运行状态 |
@@ -162,11 +162,12 @@ csep recall --recent
 └── projects/
     └── -Users-you-code-repo/
         └── memory/
-            ├── USER.md
-            └── MEMORY.md
+            ├── MEMORY.md
+            └── refs/
+                └── ...
 ```
 
-每个 repo 会按绝对路径分配独立 bucket。业务仓库保持干净，运行时状态留在用户 home 目录。
+每个 repo 会按绝对路径分配独立 bucket。`MEMORY.md` 是唯一默认注入的热上下文；`refs/` 保存按需读取的长资料，不会在 `SessionStart` 自动展开。旧 `USER.md` 如果存在会保留在磁盘上，但新版本只在 `status` 中提示 ignored。
 
 ## 安全边界
 
@@ -175,6 +176,7 @@ csep recall --recent
 - provider secret 不进仓库，密钥放在 `~/.codex-self-evolution/.env.provider`。
 - runtime state 不写进业务仓库。
 - `csep-reflect-*` 之外的 skill 不会被当作有效产物。
+- memory 写入只接受当前 repo bucket 下的 `MEMORY.md` 和 `memory/refs/**/*.md`。
 - child thread 的口头声明不算数，父进程只认 `receipt.json` 和校验结果。
 - hook 前台不做长耗时工作，避免影响 Codex 正常退出。
 

README_en.md

@@ -39,7 +39,7 @@ After a few days with Codex, the real drag is usually not the big task. It is th
 
 | Capability | When it writes | How the next session uses it |
 | --- | --- | --- |
-| Stable Memory | After the trigger policy fires, session reflection writes `USER.md` / `MEMORY.md` | `SessionStart` injects it into Codex context |
+| Stable Memory | After the trigger policy fires, session reflection writes `MEMORY.md` / `memory/refs/` | `SessionStart` injects `MEMORY.md` into Codex context |
 | Session Recall | The `Stop` hook archives transcripts into local SQLite/FTS, and the bundled `csep-session-recall` skill teaches Codex how to search | `csep recall "needle1|needle2"` searches historical evidence like `rg`, scoped to the current repo unless `--global` is explicit |
 | Reflection Skills | The reflection worker writes `~/.codex/skills/csep-reflect-*` | Codex loads them through the native skills loader |
 | Runtime Status | Hooks, config, logs, reflection jobs, and recall DB are read-only inspectable | `csep status` shows the current runtime state |
@@ -162,11 +162,12 @@ Default runtime root:
 └── projects/
     └── -Users-you-code-repo/
         └── memory/
-            ├── USER.md
-            └── MEMORY.md
+            ├── MEMORY.md
+            └── refs/
+                └── ...
 ```
 
-Each repo gets a bucket based on its absolute path. Application repos stay clean; runtime state stays in the user's home directory.
+Each repo gets a bucket based on its absolute path. `MEMORY.md` is the only hot context injected by default; `refs/` stores long-form material that agents can open on demand. A legacy `USER.md`, if present, is kept on disk but ignored by the current runtime.
 
 ## Safety Boundaries
 
@@ -175,6 +176,7 @@ Each repo gets a bucket based on its absolute path. Application repos stay clean
 - Provider secrets do not go into the repo. Put them in `~/.codex-self-evolution/.env.provider`.
 - Runtime state does not get written into application repos.
 - Skills outside the `csep-reflect-*` namespace are not accepted as generated artifacts.
+- Memory writes are accepted only for the current repo bucket's `MEMORY.md` and `memory/refs/**/*.md`.
 - The child thread's natural-language claim is not trusted; the parent process validates `receipt.json`.
 - Foreground hooks do not run long model work, so Codex can exit normally.
 

docs/architecture.md

@@ -10,7 +10,7 @@ CSEP 只做一件事：让本机 Codex session 的经验能在后续 session 中
 
 | 线 | 写入 | 使用 |
 | --- | --- | --- |
-| Stable Memory | session reflection 写 `USER.md` / `MEMORY.md` | `SessionStart` 注入当前 Codex session |
+| Stable Memory | session reflection 写 `MEMORY.md` / `memory/refs/` | `SessionStart` 注入 `MEMORY.md` |
 | Reflection Skills | session reflection 写 `~/.codex/skills/csep-reflect-*` | Codex 原生 skills loader 加载 |
 | Session Recall | `Stop` hook 或 backfill 归档 transcript 到 SQLite/FTS | `csep recall` 按 repo 或全局召回历史片段 |
 
@@ -19,7 +19,7 @@ CSEP 只做一件事：让本机 Codex session 的经验能在后续 session 中
 ```text
 Codex SessionStart
   -> csep session-start --from-stdin
-  -> 读取当前 repo bucket 的 USER.md / MEMORY.md
+  -> 读取当前 repo bucket 的 MEMORY.md
   -> 注入 stable background 和极短 recall skill pointer
 
 Codex 正常工作
@@ -34,7 +34,7 @@ Codex Stop
 Session Reflection Worker
   -> 通过 Codex app-server fork 当前 thread
   -> child Codex review memory 和 skill
-  -> child 原子写 memory / csep-reflect-* skill / receipt.json
+  -> child 原子写 MEMORY.md / refs / csep-reflect-* skill / receipt.json
   -> parent 校验 receipt、路径、hash、skill 前缀
   -> 更新 job 状态和 trigger counters
 
@@ -66,11 +66,12 @@ csep recall
 └── projects/
     └── <repo-bucket>/
         └── memory/
-            ├── USER.md
-            └── MEMORY.md
+            ├── MEMORY.md
+            └── refs/
+                └── ...
 ```
 
-业务仓库不保存运行时状态。每个 repo 按绝对路径分配 bucket；worktree 场景会尽量解析到稳定的 repo scope。
+业务仓库不保存运行时状态。每个 repo 按绝对路径分配 bucket；worktree 场景会尽量解析到稳定的 repo scope。`MEMORY.md` 是默认注入文件；`refs/` 只作为按需引用区，旧 `USER.md` 如存在会被忽略。
 
 ## 命令面
 

docs/getting-started.md

@@ -120,9 +120,10 @@ Stop         -> csep session-stop --from-stdin
 ```bash
 REPO=$(pwd)
 BUCKET=~/.codex-self-evolution/projects/$(python3 -c "import os; print(os.getcwd().replace('/', '-'))")
-mkdir -p "$BUCKET/memory"
-cat > "$BUCKET/memory/USER.md" <<'EOF'
-# User stable background
+mkdir -p "$BUCKET/memory/refs"
+cat > "$BUCKET/memory/MEMORY.md" <<'EOF'
+# Project Memory
+
 My favorite test passphrase is XANADU_RIVER_442.
 EOF
 ```
@@ -136,7 +137,7 @@ codex exec --json 'What is my favorite test passphrase?' 2>/dev/null | grep -i X
 看到 passphrase 即表示 `SessionStart` 已把 stable background 注入当前会话。测试后清理：
 
 ```bash
-rm "$BUCKET/memory/USER.md"
+rm "$BUCKET/memory/MEMORY.md"
 ```
 
 ## 5. 验证 Stop Hook 与 Reflection

docs/session-reflection.md

@@ -79,8 +79,8 @@ csep session-reflect --job <job_id>
 Child Codex 只能写两类产物：
 
 1. 当前 repo bucket 的 memory：
-   - `USER.md`
    - `MEMORY.md`
+   - `refs/**/*.md`
 2. 用户 Codex skills 目录下的 `csep-reflect-*` skill。
 
 Child 必须写 `receipt.json`，声明：
@@ -97,7 +97,7 @@ Parent 校验：
 
 - receipt 必须是合法 JSON object。
 - job / parent / child id 必须匹配。
-- memory path 必须落在允许的 memory root 下。
+- memory path 只接受当前 repo bucket 下的 `MEMORY.md` 和 `memory/refs/**/*.md`；旧 `USER.md` 不再是合法写入目标。
 - skill path 必须落在 skills root 下，且名称必须以 `csep-reflect-` 开头。
 - 文件 hash 必须和 receipt 声明一致。