jeo-code 0.6.16 → 0.6.18

package/CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.6.18] - 2026-06-17
+_Memory data-flow diagram and a README "Memory flow" section documenting the actual runtime behavior._
+
+### Added
+- **Editable memory data-flow diagram (`docs/diagrams/memory-flow.drawio`).** A draw.io swimlane diagram traces the OKF memory system's actual runtime behavior end to end: the **WRITE** lane (session-exit `spawnDetachedDistill` → `distillSessionMemory` → one JSON-mode LLM call → per-concept atomic upsert into `facts/`/`commands/`/`gotchas/`/`preferences/`, with a plain-text legacy fallback, then `rebuildIndex`/`updateLog`), the **STORE** lane (the typed concept bundle, `index.md`/`log.md`, the cross-link graph, and the legacy `MEMORY.md`/`.bak`), the **READ** lane (`memoryPromptSection` → `JEO_NO_MEMORY`/`JEO_MEMORY_LEGACY` gates → `loadConcepts` → `selectWithinBudget` priority order with 1-hop graph expansion → `frameMemory` injection-hardening → `<project_memory>` injection), and the one-shot idempotent **MIGRATION** lane (`jeo memory-migrate`).
+- **README "Memory flow" section (all four languages).** A new section in `README.md` / `README.ko.md` / `README.ja.md` / `README.zh.md` explains the local-first distilled memory model and embeds a GitHub-renderable Mermaid version of the write/store/read/migration flow, links the editable `.drawio`, and documents the `JEO_NO_MEMORY` / `JEO_MEMORY_LEGACY` toggles and the migration's rollback path.
+
+## [0.6.17] - 2026-06-17
+_Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle._
+
+### Added
+- **`jeo memory-migrate` — legacy memory → OKF bundle migration (OKF Sprint 05).** A one-shot, idempotent migration converts the legacy single-doc `.jeo/memory/MEMORY.md` into the type-partitioned OKF concept bundle: `parseLegacyMemory` maps each `## heading` to a concept type (commands/gotchas/preferences/repo-facts, unknown → RepoFact) and splits top-level bullets into concepts (`**title**: description` form recognized, indented continuation lines become the body — lossless), then `migrateLegacyMemory` writes each concept atomically under `facts/`/`commands/`/`gotchas/`/`preferences/`, (re)builds `index.md`/`log.md`, and renames the legacy doc to `MEMORY.md.bak` for rollback. Re-running is a no-op once the bundle has concepts. The bundle is the default read path; `JEO_MEMORY_LEGACY=1` is a new rollback toggle that ignores the bundle and reads the legacy doc (or its `.bak` backup) through the same injection-hardening, while `JEO_NO_MEMORY=1` still wins over everything.
+
 ## [0.6.16] - 2026-06-17
 _OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional._
 

package/README.ja.md

@@ -119,6 +119,48 @@ jeo ultragoal
 
 非ゼロ終了したフックの出力はモデルが読むツール結果に付加され(バッチ内で重複排除)、フックが赤のまま `done` を呼ぶとフック名付きでプッシュバックされます。
 
+## メモリフロー
+
+`jeo` は `.jeo/memory/` 配下に **ローカルファースト・蒸留されたプロジェクトメモリ** を保持します(リモートバックエンドなし、ネイティブ依存ゼロ)。過去のセッションは [OKF](docs/okf_mem/) コンセプトバンドルへ蒸留され、次のセッションは関連性の高い予算内のスライスだけをシステムプロンプトへ再注入します — 指示ではなく DATA として堅牢化されます。`JEO_NO_MEMORY=1` ですべて無効化。
+
+📐 **編集可能な図:** [`docs/diagrams/memory-flow.drawio`](docs/diagrams/memory-flow.drawio)([draw.io](https://app.diagrams.net) / デスクトップアプリで開く) — 書き込み/保存/読み込み/移行の全スイムレーン。概要:
+
+```mermaid
+flowchart LR
+  subgraph WRITE["WRITE — session-end distill (detached, best-effort)"]
+    direction TB
+    W1["session exit / ^C^C"] --> W2["spawnDetachedDistill()<br/>payload + detached child, returns instantly"]
+    W2 --> W3["distillSessionMemory()<br/>load bundle · transcriptTail · ONE LLM call (JSON)"]
+    W3 --> WD{"concepts JSON<br/>parsed?"}
+    WD -->|yes| WY["per concept: upsert by title,<br/>atomic write into facts/ commands/<br/>gotchas/ preferences/"]
+    WD -->|no| WN["plain text →<br/>legacy MEMORY.md"]
+    WY --> WR["rebuildIndex() index.md<br/>updateLog() log.md"]
+  end
+
+  subgraph STORE[".jeo/memory/ — OKF concept bundle"]
+    direction TB
+    S1["facts/ · commands/ · gotchas/ · preferences/<br/>(YAML frontmatter + body)"]
+    S2["index.md · log.md · cross-link graph (Sprint 04)"]
+    S3["MEMORY.md (legacy fallback)<br/>MEMORY.md.bak (rollback)"]
+  end
+
+  subgraph READ["READ — memoryPromptSection(cwd, query)"]
+    direction TB
+    R1["session start (query = task text)"] --> R2{"bundle has<br/>concepts?"}
+    R2 -->|yes| R3["selectWithinBudget()<br/>core → query relevance → 1-hop graph<br/>≤ MEMORY_INJECT_MAX_CHARS (3000)"]
+    R2 -->|no| R3B["legacy loadMemory()"]
+    R3 --> R4["frameMemory()<br/>hard cap · fence-neutralize · DATA framing"]
+    R3B --> R4
+    R4 --> R5["&lt;project_memory&gt; … injected into system prompt"]
+  end
+
+  WR -->|atomic| STORE
+  WN -->|fallback| S3
+  STORE -.->|loadConcepts / loadMemory| READ
+```
+
+**移行(`jeo memory-migrate`、ワンショット・冪等).** レガシーの単一ドキュメント `MEMORY.md` をロスレスでバンドルへ変換します: `## 見出し → タイプ`、各箇条書き → タイプ別コンセプト、インデント行 → 本文; `index.md`/`log.md` を再構築し、元ファイルを `MEMORY.md.bak` にリネームします。バンドルにコンセプトができた後の再実行は no-op です。**ロールバック:** `JEO_MEMORY_LEGACY=1` はバンドルを無視し、同じ注入堅牢化を通して `MEMORY.md`/`.bak` を読みます(`JEO_NO_MEMORY=1` がすべてに優先)。
+
 ## ローカルモデル
 
 ```bash
@@ -158,11 +200,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.18]** (2026-06-17) — Memory data-flow diagram and a README "Memory flow" section documenting the actual runtime behavior.
+- **[0.6.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
 - **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
-- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -119,6 +119,48 @@ jeo ultragoal
 
 비정상 종료한 훅의 출력은 모델이 읽는 도구 결과에 첨부되고(배치 내 중복 제거), 훅이 빨간 채로 `done`을 부르면 훅 이름과 함께 푸시백됩니다.
 
+## 메모리 흐름
+
+`jeo`는 `.jeo/memory/` 아래에 **로컬 우선·증류된 프로젝트 메모리**를 둡니다(원격 백엔드 없음, 네이티브 의존성 0). 지난 세션은 [OKF](docs/okf_mem/) 개념 번들로 증류되고, 다음 세션은 관련성 높은 예산 한도 내 일부만 시스템 프롬프트로 다시 주입합니다 — 지시가 아닌 DATA로 강화 처리됩니다. `JEO_NO_MEMORY=1`로 전체 비활성화.
+
+📐 **편집 가능한 다이어그램:** [`docs/diagrams/memory-flow.drawio`](docs/diagrams/memory-flow.drawio) ([draw.io](https://app.diagrams.net) / 데스크톱 앱에서 열기) — 쓰기/저장/읽기/마이그레이션 전체 스윔레인. 요약 보기:
+
+```mermaid
+flowchart LR
+  subgraph WRITE["WRITE — session-end distill (detached, best-effort)"]
+    direction TB
+    W1["session exit / ^C^C"] --> W2["spawnDetachedDistill()<br/>payload + detached child, returns instantly"]
+    W2 --> W3["distillSessionMemory()<br/>load bundle · transcriptTail · ONE LLM call (JSON)"]
+    W3 --> WD{"concepts JSON<br/>parsed?"}
+    WD -->|yes| WY["per concept: upsert by title,<br/>atomic write into facts/ commands/<br/>gotchas/ preferences/"]
+    WD -->|no| WN["plain text →<br/>legacy MEMORY.md"]
+    WY --> WR["rebuildIndex() index.md<br/>updateLog() log.md"]
+  end
+
+  subgraph STORE[".jeo/memory/ — OKF concept bundle"]
+    direction TB
+    S1["facts/ · commands/ · gotchas/ · preferences/<br/>(YAML frontmatter + body)"]
+    S2["index.md · log.md · cross-link graph (Sprint 04)"]
+    S3["MEMORY.md (legacy fallback)<br/>MEMORY.md.bak (rollback)"]
+  end
+
+  subgraph READ["READ — memoryPromptSection(cwd, query)"]
+    direction TB
+    R1["session start (query = task text)"] --> R2{"bundle has<br/>concepts?"}
+    R2 -->|yes| R3["selectWithinBudget()<br/>core → query relevance → 1-hop graph<br/>≤ MEMORY_INJECT_MAX_CHARS (3000)"]
+    R2 -->|no| R3B["legacy loadMemory()"]
+    R3 --> R4["frameMemory()<br/>hard cap · fence-neutralize · DATA framing"]
+    R3B --> R4
+    R4 --> R5["&lt;project_memory&gt; … injected into system prompt"]
+  end
+
+  WR -->|atomic| STORE
+  WN -->|fallback| S3
+  STORE -.->|loadConcepts / loadMemory| READ
+```
+
+**마이그레이션 (`jeo memory-migrate`, 1회성 · 멱등).** 레거시 단일 문서 `MEMORY.md`를 무손실로 번들로 변환합니다: `## 헤딩 → 타입`, 각 불릿 → 타입별 개념, 들여쓴 줄 → 본문; `index.md`/`log.md`를 재생성하고 원본은 `MEMORY.md.bak`으로 이름을 바꿉니다. 번들에 개념이 생긴 뒤 재실행은 no-op입니다. **롤백:** `JEO_MEMORY_LEGACY=1`은 번들을 무시하고 동일한 주입 강화 처리로 `MEMORY.md`/`.bak`를 읽습니다(`JEO_NO_MEMORY=1`이 모든 것에 우선).
+
 ## 로컬 모델
 
 ```bash
@@ -158,11 +200,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.18]** (2026-06-17) — Memory data-flow diagram and a README "Memory flow" section documenting the actual runtime behavior.
+- **[0.6.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
 - **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
-- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -119,6 +119,48 @@ Enable hooks once globally (`"hooks": { "enabled": true }` in `~/.jeo/config.jso
 
 Non-zero hook output is appended to the tool result the model reads (deduped per batch); a still-red hook triggers a `done` pushback naming the hook.
 
+## Memory flow
+
+`jeo` keeps a **local-first, distilled project memory** under `.jeo/memory/` (no remote backend, zero native deps). Past sessions are distilled into an [OKF](docs/okf_mem/) concept bundle, and the next session injects only the relevant, budget-bounded slice back into the system prompt — hardened as DATA, never as instructions. Disable everything with `JEO_NO_MEMORY=1`.
+
+📐 **Editable diagram:** [`docs/diagrams/memory-flow.drawio`](docs/diagrams/memory-flow.drawio) (open in [draw.io](https://app.diagrams.net) / the desktop app) — full write/store/read/migration swimlanes. Quick view:
+
+```mermaid
+flowchart LR
+  subgraph WRITE["WRITE — session-end distill (detached, best-effort)"]
+    direction TB
+    W1["session exit / ^C^C"] --> W2["spawnDetachedDistill()<br/>payload + detached child, returns instantly"]
+    W2 --> W3["distillSessionMemory()<br/>load bundle · transcriptTail · ONE LLM call (JSON)"]
+    W3 --> WD{"concepts JSON<br/>parsed?"}
+    WD -->|yes| WY["per concept: upsert by title,<br/>atomic write into facts/ commands/<br/>gotchas/ preferences/"]
+    WD -->|no| WN["plain text →<br/>legacy MEMORY.md"]
+    WY --> WR["rebuildIndex() index.md<br/>updateLog() log.md"]
+  end
+
+  subgraph STORE[".jeo/memory/ — OKF concept bundle"]
+    direction TB
+    S1["facts/ · commands/ · gotchas/ · preferences/<br/>(YAML frontmatter + body)"]
+    S2["index.md · log.md · cross-link graph (Sprint 04)"]
+    S3["MEMORY.md (legacy fallback)<br/>MEMORY.md.bak (rollback)"]
+  end
+
+  subgraph READ["READ — memoryPromptSection(cwd, query)"]
+    direction TB
+    R1["session start (query = task text)"] --> R2{"bundle has<br/>concepts?"}
+    R2 -->|yes| R3["selectWithinBudget()<br/>core → query relevance → 1-hop graph<br/>≤ MEMORY_INJECT_MAX_CHARS (3000)"]
+    R2 -->|no| R3B["legacy loadMemory()"]
+    R3 --> R4["frameMemory()<br/>hard cap · fence-neutralize · DATA framing"]
+    R3B --> R4
+    R4 --> R5["&lt;project_memory&gt; … injected into system prompt"]
+  end
+
+  WR -->|atomic| STORE
+  WN -->|fallback| S3
+  STORE -.->|loadConcepts / loadMemory| READ
+```
+
+**Migration (`jeo memory-migrate`, one-shot · idempotent).** A legacy single-doc `MEMORY.md` is converted losslessly into the bundle: `## heading → type`, each bullet → a typed concept, indented lines → body; `index.md`/`log.md` are rebuilt and the original is renamed to `MEMORY.md.bak`. Re-running is a no-op once the bundle has concepts. **Rollback:** `JEO_MEMORY_LEGACY=1` ignores the bundle and reads `MEMORY.md`/`.bak` through the same injection-hardening (`JEO_NO_MEMORY=1` still wins over everything).
+
 ## Local models
 
 ```bash
@@ -158,11 +200,11 @@ Required npm token permissions (repository secret `NPM_TOKEN`):
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.18]** (2026-06-17) — Memory data-flow diagram and a README "Memory flow" section documenting the actual runtime behavior.
+- **[0.6.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
 - **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
-- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -119,6 +119,48 @@ jeo ultragoal
 
 非零退出钩子的输出会附加到模型读取的工具结果中(批内去重)；钩子未通过就调用 `done` 会收到带钩子名称的回推。
 
+## 内存流程
+
+`jeo` 在 `.jeo/memory/` 下保存 **本地优先、蒸馏后的项目内存**(无远程后端,零原生依赖)。过往会话被蒸馏为 [OKF](docs/okf_mem/) 概念包,下一次会话仅把相关的、受预算约束的切片重新注入系统提示 —— 作为 DATA 而非指令加固。用 `JEO_NO_MEMORY=1` 完全禁用。
+
+📐 **可编辑图示:** [`docs/diagrams/memory-flow.drawio`](docs/diagrams/memory-flow.drawio)(在 [draw.io](https://app.diagrams.net) / 桌面应用中打开)—— 写入/存储/读取/迁移完整泳道。概览:
+
+```mermaid
+flowchart LR
+  subgraph WRITE["WRITE — session-end distill (detached, best-effort)"]
+    direction TB
+    W1["session exit / ^C^C"] --> W2["spawnDetachedDistill()<br/>payload + detached child, returns instantly"]
+    W2 --> W3["distillSessionMemory()<br/>load bundle · transcriptTail · ONE LLM call (JSON)"]
+    W3 --> WD{"concepts JSON<br/>parsed?"}
+    WD -->|yes| WY["per concept: upsert by title,<br/>atomic write into facts/ commands/<br/>gotchas/ preferences/"]
+    WD -->|no| WN["plain text →<br/>legacy MEMORY.md"]
+    WY --> WR["rebuildIndex() index.md<br/>updateLog() log.md"]
+  end
+
+  subgraph STORE[".jeo/memory/ — OKF concept bundle"]
+    direction TB
+    S1["facts/ · commands/ · gotchas/ · preferences/<br/>(YAML frontmatter + body)"]
+    S2["index.md · log.md · cross-link graph (Sprint 04)"]
+    S3["MEMORY.md (legacy fallback)<br/>MEMORY.md.bak (rollback)"]
+  end
+
+  subgraph READ["READ — memoryPromptSection(cwd, query)"]
+    direction TB
+    R1["session start (query = task text)"] --> R2{"bundle has<br/>concepts?"}
+    R2 -->|yes| R3["selectWithinBudget()<br/>core → query relevance → 1-hop graph<br/>≤ MEMORY_INJECT_MAX_CHARS (3000)"]
+    R2 -->|no| R3B["legacy loadMemory()"]
+    R3 --> R4["frameMemory()<br/>hard cap · fence-neutralize · DATA framing"]
+    R3B --> R4
+    R4 --> R5["&lt;project_memory&gt; … injected into system prompt"]
+  end
+
+  WR -->|atomic| STORE
+  WN -->|fallback| S3
+  STORE -.->|loadConcepts / loadMemory| READ
+```
+
+**迁移(`jeo memory-migrate`,一次性 · 幂等).** 把旧版单文档 `MEMORY.md` 无损转换为概念包: `## 标题 → 类型`,每个项目符号 → 一个类型化概念,缩进行 → 正文; 重建 `index.md`/`log.md`,并把原文件重命名为 `MEMORY.md.bak`。一旦概念包中已有概念,再次运行即为 no-op。**回滚:** `JEO_MEMORY_LEGACY=1` 忽略概念包,通过相同的注入加固读取 `MEMORY.md`/`.bak`(`JEO_NO_MEMORY=1` 仍优先于一切)。
+
 ## 本地模型
 
 ```bash
@@ -158,11 +200,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.18]** (2026-06-17) — Memory data-flow diagram and a README "Memory flow" section documenting the actual runtime behavior.
+- **[0.6.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
 - **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
-- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.6.16",
+  "version": "0.6.18",
 
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",

package/src/agent/AGENTS.md

@@ -17,7 +17,9 @@ The core runtime loop, tool registry, session management, and state persistence
 | `hooks.ts` | Brief description of purpose |
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
-| `memory.ts` | Brief description of purpose |
+| `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
+| `memory-okf.ts` | OKF v0.1 format layer: frontmatter parse/serialize, concept IDs, conformance validation |
+| `memory-graph.ts` | Concept cross-link graph: build/expand (1-hop search), broken-link-tolerant lint, optional graphify detection |
 | `model-recency.ts` | Brief description of purpose |
 | `output-minimizer.ts` | Brief description of purpose |
 | `output-util.ts` | Brief description of purpose |

package/src/agent/memory.ts

@@ -50,6 +50,129 @@ export async function loadMemory(cwd: string): Promise<string> {
   }
 }
 
+/** A concept extracted from a legacy single-doc MEMORY.md during migration. */
+export interface MigratedConcept {
+  type: string;
+  title: string;
+  description: string;
+  body: string;
+}
+
+/** Map a legacy `## heading` to a jeo concept type. Lenient keyword match —
+ *  unknown headings default to RepoFact so nothing is dropped. */
+function headingToType(heading: string): string {
+  const h = heading.toLowerCase();
+  if (/\bcommand/.test(h)) return "Command";
+  if (/gotcha|pitfall|caveat/.test(h)) return "Gotcha";
+  if (/pref/.test(h)) return "UserPreference";
+  if (/repo|fact/.test(h)) return "RepoFact";
+  return "RepoFact";
+}
+
+/** Parse a legacy 4-heading MEMORY.md into concepts: each `## heading` sets the
+ *  type, each top-level bullet becomes a concept (`**title**: description` form
+ *  recognized, indented continuation lines become the body). Lossless: a plain
+ *  bullet keeps its whole text as the title. */
+export function parseLegacyMemory(doc: string): MigratedConcept[] {
+  const concepts: MigratedConcept[] = [];
+  let currentType = "RepoFact";
+  let cur: MigratedConcept | null = null;
+  const flush = () => {
+    if (cur) {
+      cur.body = cur.body.replace(/\n+$/, "");
+      concepts.push(cur);
+      cur = null;
+    }
+  };
+  for (const line of doc.split("\n")) {
+    const heading = line.match(/^#{1,6}\s+(.*)$/);
+    if (heading) {
+      flush();
+      currentType = headingToType(heading[1]!.trim());
+      continue;
+    }
+    const bullet = line.match(/^\s*[-*]\s+(.*)$/);
+    if (bullet) {
+      flush();
+      const text = bullet[1]!.trim();
+      const bold = text.match(/^\*\*(.+?)\*\*\s*:?\s*(.*)$/);
+      cur = bold
+        ? { type: currentType, title: bold[1]!.trim(), description: bold[2]!.trim(), body: "" }
+        : { type: currentType, title: text, description: "", body: "" };
+      continue;
+    }
+    // Continuation line (typically 2-space indented) belongs to the open concept.
+    if (cur && line.trim() !== "") {
+      cur.body += (cur.body ? "\n" : "") + line.replace(/^ {2}/, "");
+    }
+  }
+  flush();
+  return concepts.filter(c => c.title);
+}
+
+/** Outcome of a one-shot legacy → OKF bundle migration. */
+export interface MigrationResult {
+  migrated: boolean;
+  conceptCount: number;
+  /** Why nothing was migrated (already a bundle / no legacy doc / nothing parsed). */
+  skipped?: string;
+  /** Where the legacy MEMORY.md was preserved for rollback, if migrated. */
+  backupPath?: string;
+}
+
+/**
+ * Migrate a legacy single-doc `.jeo/memory/MEMORY.md` into the OKF concept bundle.
+ * One-shot and IDEMPOTENT: a bundle that already holds concept docs is left
+ * untouched. On success each legacy bullet becomes a type-partitioned concept,
+ * index.md/log.md are (re)built, and the legacy doc is renamed to `MEMORY.md.bak`
+ * so the active path is the bundle while a rollback copy survives.
+ */
+export async function migrateLegacyMemory(cwd: string): Promise<MigrationResult> {
+  const bundleDir = path.join(cwd, ".jeo", "memory");
+  // Idempotent: an existing concept bundle wins — never double-migrate.
+  if ((await loadConcepts(cwd)).length > 0) {
+    return { migrated: false, conceptCount: 0, skipped: "bundle already has concepts" };
+  }
+  const doc = await loadMemory(cwd);
+  if (!doc) return { migrated: false, conceptCount: 0, skipped: "no legacy MEMORY.md to migrate" };
+  const parsed = parseLegacyMemory(doc);
+  if (parsed.length === 0) return { migrated: false, conceptCount: 0, skipped: "no concepts parsed from MEMORY.md" };
+
+  await fs.mkdir(bundleDir, { recursive: true });
+  const written: { title: string; type: string }[] = [];
+  const usedSlugs = new Set<string>();
+  for (const c of parsed) {
+    const dir = DIR_BY_TYPE[c.type] ?? "facts";
+    await fs.mkdir(path.join(bundleDir, dir), { recursive: true });
+    let slug = slugify(c.title);
+    let suffix = 1;
+    while (usedSlugs.has(`${dir}/${slug}`)) slug = `${slugify(c.title)}-${suffix++}`;
+    usedSlugs.add(`${dir}/${slug}`);
+    const frontmatter = {
+      type: c.type,
+      title: c.title,
+      description: c.description,
+      tags: [] as string[],
+      timestamp: new Date().toISOString(),
+      confidence: "high",
+      last_verified: new Date().toISOString().split("T")[0]!,
+      links: [] as string[],
+    };
+    const serialized = serializeConcept(frontmatter, c.body);
+    const fullPath = path.join(bundleDir, dir, `${slug}.md`);
+    const tmpPath = `${fullPath}.tmp-${process.pid}`;
+    await fs.writeFile(tmpPath, serialized, "utf-8");
+    await fs.rename(tmpPath, fullPath);
+    written.push({ title: c.title, type: c.type });
+  }
+  await rebuildIndex(bundleDir);
+  await updateLog(bundleDir, written);
+  // Preserve the legacy doc as a rollback backup, off the active read path.
+  const backupPath = `${memoryFilePath(cwd)}.bak`;
+  await fs.rename(memoryFilePath(cwd), backupPath).catch(() => {});
+  return { migrated: true, conceptCount: written.length, backupPath };
+}
+
 /** Render a single index.md-style section: a `## header` followed by one bullet
  *  per concept (`**title**: description`), with the concept body indented beneath. */
 function renderConceptSection(header: string, list: { title: string; description: string; body: string }[]): string {
@@ -240,12 +363,26 @@ function selectWithinBudget(concepts: Concept[], query: string | undefined, budg
  *  reports: tag-breakout sequences are neutralized and the block is framed as DATA. */
 export async function memoryPromptSection(cwd: string, query?: string): Promise<string> {
   if (jeoEnv("NO_MEMORY") === "1") return "";
+  // Rollback toggle (Sprint 05): JEO_MEMORY_LEGACY=1 forces the legacy single-doc
+  // path, ignoring any concept bundle — reads MEMORY.md, or its migration backup.
+  if (jeoEnv("MEMORY_LEGACY") === "1") {
+    let memory = await loadMemory(cwd);
+    if (!memory) memory = (await fs.readFile(`${memoryFilePath(cwd)}.bak`, "utf-8").catch(() => "")).trim();
+    return memory ? frameMemory(memory) : "";
+  }
   // Prefer the OKF concept bundle (budget-selected); fall back to legacy MEMORY.md.
   const concepts = await loadConcepts(cwd);
   let memory = concepts.length > 0
     ? renderConcepts(selectWithinBudget(concepts, query, MEMORY_INJECT_MAX_CHARS))
     : await loadMemory(cwd);
   if (!memory) return "";
+  return frameMemory(memory);
+}
+
+/** Wrap distilled memory text in the hardened `<project_memory>` block: hard char
+ *  cap, fence-tag neutralization, and DATA framing. Shared by the bundle path and
+ *  the legacy/rollback path so neither can bypass the injection-hardening. */
+function frameMemory(memory: string): string {
   // Backstop: legacy MEMORY.md is a single blob (not concept-selectable), and a
   // pathological single concept can exceed the budget — hard-cap either way.
   if (memory.length > MEMORY_INJECT_MAX_CHARS) {

package/src/cli/runner.ts

@@ -146,6 +146,15 @@ export const COMMANDS: readonly CommandSpec[] = [
       return args => m.runMemoryDistillCommand(args);
     },
   },
+  {
+    name: "memory-migrate",
+    summary: "Migrate a legacy MEMORY.md into the OKF concept bundle (one-shot, idempotent).",
+    usage: "memory-migrate",
+    loader: async () => {
+      const m = await import("../commands/memory-migrate");
+      return args => m.runMemoryMigrateCommand(args);
+    },
+  },
   {
     name: "state",
     summary: "Read or update workflow state receipts under .jeo/state (gjc-state parity).",

package/src/commands/memory-migrate.ts

@@ -0,0 +1,19 @@
+/**
+ * `jeo memory-migrate` — one-shot, idempotent migration of a legacy single-doc
+ * `.jeo/memory/MEMORY.md` into the OKF concept bundle (Sprint 05).
+ *
+ * Safe to re-run: if the bundle already holds concepts it is left untouched.
+ * The legacy doc is preserved as `MEMORY.md.bak` for rollback; set
+ * `JEO_MEMORY_LEGACY=1` to read that backup again if a rollback is needed.
+ */
+import { migrateLegacyMemory } from "../agent/memory";
+
+export async function runMemoryMigrateCommand(_args: string[]): Promise<void> {
+  const result = await migrateLegacyMemory(process.cwd());
+  if (result.migrated) {
+    console.log(`migrated ${result.conceptCount} concept(s) from MEMORY.md → OKF bundle (.jeo/memory/).`);
+    if (result.backupPath) console.log(`legacy doc preserved at ${result.backupPath} (rollback: JEO_MEMORY_LEGACY=1).`);
+  } else {
+    console.log(`nothing to migrate — ${result.skipped}.`);
+  }
+}