okstra 0.43.0 → 0.44.0

package/README.kr.md

@@ -43,7 +43,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
 ├── runtime/                     gitignored 설치 payload; ~/.okstra 로 복사
 ├── scripts/                     python + bash 런타임 소스
-├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 13종)
+├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 10종)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, schemas/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
@@ -66,6 +66,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
 ├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
+├── memory-book/                 전역 대화 메모리 (`okstra memory`)
 ├── projects/                    프로젝트별 메타데이터 미러
 ├── worktrees/                   task-key 당 하나의 격리 git worktree
 │                                (모든 phase가 공유; run 종료 후 자동 삭제하지 않음)
@@ -73,7 +74,7 @@ okstra/                          npm 패키지 = repo 루트
 └── .locks/                      central/task mutex 파일
 
 ~/.claude/skills/                Claude Code 가 자동 인식
-└── okstra-*/SKILL.md            스킬 13종 (§3.3 참조)
+└── okstra-*/SKILL.md            스킬 10종 (§3.3 참조)
 
 ~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
@@ -106,7 +107,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 13개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 10개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 
@@ -155,6 +156,7 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 |---|---|
 | `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
 | `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
+| `/okstra-memory` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
 | `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안) |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
@@ -206,6 +208,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.okstra/project.json`) |
 | `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | okstra 설정 읽기/쓰기. 현재 지원 키: `pr-template-path` (project.json 또는 `~/.okstra/config.json` 의 `prTemplatePath` 갱신) |
+| `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
 | `npx -y okstra@latest render-views <final-report.md>` | final-report MD 한 본을 입력으로 슬림 MD + HTML 두 view 를 (재)생성 (Phase 7 step 1.5; 멱등) |
 | `npx -y okstra@latest token-usage ...` | run token usage 수집/치환. 설치된 Python token usage CLI를 감싼 Node wrapper |
 | `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |

package/README.md

@@ -43,7 +43,7 @@ okstra/                          npm package = repo root
 ├── tools/build.mjs              runtime/ sync script (invoked by prepack)
 ├── runtime/                     gitignored install payload copied to ~/.okstra
 ├── scripts/                     python + bash runtime sources
-├── skills/                      Claude Code skill markdown sources (13 skills)
+├── skills/                      Claude Code skill markdown sources (14 skills)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, schemas/, templates/, validators/
 ├── tests/, tests-e2e/
@@ -65,6 +65,7 @@ okstra/                          npm package = repo root
 ├── installed-skills.json        manifest of installed skills (used by uninstall)
 ├── installed-agents.json        manifest of installed worker agents (used by uninstall)
 ├── recent.jsonl, active.jsonl   run index
+├── memory-book/                 global conversation memory (okstra memory)
 ├── projects/                    per-project metadata mirror
 ├── worktrees/                   one isolated git worktree per task-key
 │                                (shared by all phases; not auto-removed)
@@ -72,7 +73,7 @@ okstra/                          npm package = repo root
 └── .locks/                      central/task mutex files
 
 ~/.claude/skills/                discovered automatically by Claude Code
-└── okstra-*/SKILL.md            13 skills total (see §3.3)
+└── okstra-*/SKILL.md            14 skills total (see §3.3)
 
 ~/.claude/agents/                discovered automatically by Claude Code
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
@@ -105,7 +106,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 13 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
+Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 14 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
 
 Verify:
 
@@ -154,6 +155,7 @@ User-facing slash commands inside a Claude Code session:
 |---|---|
 | `/okstra-brief` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
 | `/okstra-run` | Start a new task (or resume the next phase of an existing one) |
+| `/okstra-memory` | Store/search/archive global conversation memory in `~/.okstra/memory-book` |
 | `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup) |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
@@ -205,6 +207,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.okstra/project.json`) |
 | `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
+| `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | Store and find global conversation memory in `~/.okstra/memory-book` |
 | `npx -y okstra@latest render-views <final-report.md>` | Regenerate the slim-MD + HTML sibling views from a final-report MD (Phase 7 step 1.5; idempotent) |
 | `npx -y okstra@latest token-usage ...` | Collect/substitute token usage for a run; wraps the installed Python token usage CLI |
 | `npx -y okstra@latest uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |

package/bin/okstra

@@ -19,6 +19,7 @@ const COMMANDS = new Map([
   ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
   ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
   ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],
+  ["memory", () => import("../src/memory.mjs").then((m) => m.run)],
 ]);
 
 const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
@@ -61,6 +62,8 @@ Introspection commands (JSON output, used by skills to avoid python heredocs):
   token-usage            Collect token usage for a run (wraps the installed
                          okstra-token-usage.py so skills avoid emitting
                          python3 "$HOME/..." invocations).
+  memory                 Store and find user-home conversation memory under
+                         ~/.okstra/memory-book.
 
 Global options:
   --version              Print okstra version and exit

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](../../scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: 각 phase profile의 `Required workers:` 블록이 roster의 권위입니다. 일반 분석 phase는 Claude/Codex analyser + report-writer를 기본으로 하고, Gemini는 profile과 `--workers`가 허용할 때만 포함됩니다. `release-handoff`처럼 lead-only에 가까운 phase는 별도 roster를 가집니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 13종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 10종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Derived views and telemetry**: final-report data.json → Markdown → slim MD / self-contained HTML view, worker error sidecar, wrapper log sidecar, token usage / cost accounting을 제공합니다.
 
@@ -152,7 +152,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`agents/SKILL.md`](../../agents/SKILL.md) — main okstra lead contract.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- `skills/okstra-{brief,status,history,convergence,schedule,context-loader,team-contract,report-finder,report-writer,time-summary,logs}/SKILL.md` — brief 작성, phase 진행, status/history, report/time/log 보조 skill. `okstra-logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함).
+- `skills/okstra-{brief,run,memory,inspect,schedule,context-loader,team-contract,convergence,report-writer}/SKILL.md` — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log read-side, schedule 보조 skill. `okstra-inspect logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함).
 - 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md` (`okstra-install.sh` dev 설치, 또는 위 npx 채널).
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
@@ -839,7 +839,7 @@ scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --task-type fin
 프로젝트 전체 상태를 훑을 때는 `.okstra/discovery/task-catalog.json`을 사용합니다.
 특정 task의 최신 상태를 볼 때는 `.okstra/discovery/latest-task.json`, `task-manifest.json`, 최신 `run-manifest`, `history/timeline.json` 순서로 확인합니다.
 
-Claude에서는 seeded `okstra-status` skill을 사용해 아래 질문을 직접 처리할 수 있습니다.
+Claude에서는 seeded `okstra-inspect` skill의 `status` 하위 흐름을 사용해 아래 질문을 직접 처리할 수 있습니다.
 
 - 전체 okstra task status 보여줘
 - 특정 `task-key`의 current phase와 next phase 알려줘
@@ -914,7 +914,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 두 view 를 결정
 - **run-scoped 태깅으로 정리**: trace pane 의 `tail -F` 는 tmux 셸의 자식이라 Claude 가 종료돼도 살아남습니다. wrapper 는 spawn 한 pane 을 `tmux set-option -p @okstra_trace_run=<RUN_DIR>` 로 태깅하고, `okstra-trace-cleanup.sh` 는 `tmux list-panes -a` 에서 그 태그로 pane 을 server-wide 발견해 `tmux kill-pane` 합니다. tmux env 변수·pane-id registry 없이 동작하며, run-scoped 태그라 동시에 도는 다른 okstra run 의 trace pane 을 죽이지 않습니다. cleanup 은 두 진입 형태를 가집니다 — lead 가 `--run-dir <RUN_DIR>` 로 호출(해당 run 의 trace + worker-agent pane 정리)하거나, `templates/reports/settings.template.json` 의 `hooks.SessionEnd` 가 `--reap` 로 호출(`$CLAUDE_PROJECT_DIR/.okstra/` 하위 태그를 가진 trace pane 일괄 정리; 단일 run-dir 이 없는 종료 시점용). tmux 가 없거나 stale pane id 인 경우 silent degrade.
 - **phase 전환 시 자동 정리 + worker-agent pane 포함**: `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` 는 태깅된 trace pane 뿐 아니라 dispatch 된 서브에이전트가 점유하는 worker-agent pane(title `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`)도 lead 세션(`tmux list-panes -s -t <lead-pane>`) 범위에서 title allowlist 로 식별해 닫습니다(worker-agent pane 은 harness 소유라 태깅 불가). 세션 scope 와 lead 자기 pane 제외는 `<RUN_DIR>/state/lead-pane.id` 로 결정되며, lead 자신의 pane 은 title 이 걸려도 절대 죽이지 않습니다. lead 는 새 phase 의 worker 를 dispatch 하기 직전(`PROGRESS: phase-5.5-convergence` / `phase-6-synthesis` 마커 직전) 이 스크립트를 `--run-dir` 로 호출해 이전 phase 의 pane 을 prompt 없이 정리합니다.
 - **Phase 종료 시 사용자 확인**: run 최종 종료 시점(마지막 단계)에 lead 가 `okstra-trace-cleanup.sh --list --run-dir <RUN_DIR>` 로 잔여 okstra pane(worker-agent + trace) 목록을 출력한 뒤 사용자에게 "모두 닫기 / 그대로 두기" 양자택일을 묻고 응답대로 처리합니다 (`prompts/profiles/_common-contract.md` 의 *Phase wrap-up* 항목). `<RUN_DIR>/state/lead-pane.id` 가 비어 있는(=tmux 밖) 환경에서는 단계 자체가 silent-skip. `--list` 모드는 pane 을 죽이지 않고 `<pane_id>\t<pane_title>` 만 출력하므로 사용자가 무엇이 닫힐지 시각적으로 확인할 수 있습니다.
-- 디스크 누적은 `okstra-logs` skill 이 read-only 로 인벤토리 + cleanup 명령을 제안합니다 (실행은 사용자 copy-paste).
+- 디스크 누적은 `okstra-inspect logs` 흐름이 read-only 로 인벤토리 + cleanup 명령을 제안합니다 (실행은 사용자 copy-paste).
 
 ### Linked-worktree `.git/` write 권한 (codex / gemini)
 
@@ -973,7 +973,7 @@ phase 산출물의 출고 가능 여부를 강제하는 진입점:
 - 토큰 사용 및 비용 집계는 `scripts/okstra-token-usage.py`와 Node wrapper `okstra token-usage`가 담당합니다.
 - `okstra.sh`는 worker CLI 호출 anchoring을 위해 절대 projectRoot를 강제합니다.
 - `okstra wizard step` 은 `--answer <val>` 을 **필수** 로 받습니다. 응답을 줄 차례가 아니라 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek 합니다.
-- `/okstra-history`는 task manifest fallback / 페이지네이션 / 필터를 지원하고, `--base-ref`는 워크트리 registry에서 해석합니다.
+- `/okstra-inspect history`는 task manifest fallback / 페이지네이션 / 필터를 지원하고, `--base-ref`는 워크트리 registry에서 해석합니다.
 - 사용자 프로젝트에 대한 모든 쓰기는 `<PROJECT_ROOT>/.okstra/` 안에만 발생합니다 (Artifact-home rule 참조).
 
 ## Related documents

package/docs/kr/cli.md

@@ -577,6 +577,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra setup --project-id <id>` | 현재 프로젝트의 `.okstra/project.json` 생성/갱신 |
 | `okstra check-project [--json]` | 현재 프로젝트가 등록되었는지 검증 |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기 |
+| `okstra memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 관리. 프로젝트 `.okstra/` 와 분리된 user-home 저장소이며, `okstra 에 정리해서 보관해` 자연어 스킬의 CLI 기반 |
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | 한 번만 실행: 프로젝트 산출물 루트를 `.project-docs/okstra/` → `.okstra/` 로 이동. 기본 dry-run, `--apply` 로 실제 실행. `git mv` (git worktree) + 빈 `.project-docs/` 제거 + `<PROJECT>/CLAUDE.md` import 라인 + `.gitignore` + `~/.okstra/{recent,active}.jsonl` + `~/.okstra/worktrees/registry.json` 의 해당 프로젝트 row 동기화. 이미 `.okstra/` 가 존재하거나 레거시 디렉토리가 없으면 exit 1 로 거부. v0.x 말까지 유지 후 제거 예정 |
 | `okstra task-list [--project-root <path>]` | `list_project_tasks` + `read_latest_task` 결과를 합쳐 task 카탈로그 + 최근 task 를 JSON 으로 반환 |
 | `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |

package/docs/project-structure-overview.md

@@ -28,7 +28,7 @@
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
-- installed skills: 13개
+- installed skills: 10개
 - worker agents: `claude`, `codex`, `gemini`, `report-writer`
 - final report SSOT: `schemas/final-report-v1.0.schema.json` + `*.data.json`
 
@@ -54,7 +54,7 @@ okstra/
 │   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
-├── skills/                          Claude Code skills (13)
+├── skills/                          Claude Code skills (10)
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
@@ -244,12 +244,13 @@ Token/cost accounting:
 
 ### 4.10 `skills/`
 
-13 installed skills:
+10 installed skills:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
 | `okstra-brief` | yes | Produce task brief from ticket/doc/link/conversation |
 | `okstra-run` | yes | Start/resume okstra task in current Claude Code session |
+| `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup) |
 | `okstra-schedule` | yes | Generate task-group schedule |
 | `okstra-setup` | yes | Install/check runtime and register project |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.43.0",
-  "builtAt": "2026-06-04T04:59:06.499Z",
+  "package": "0.44.0",
+  "builtAt": "2026-06-04T05:25:22.876Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -216,6 +216,8 @@ Use agent and subagent names that map cleanly to the selected worker roles. Do n
 
 Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5 with `run_in_background: true` and no `team_name` when Teams unavailable). Preserve exact roster, role labels, assigned models from the task bundle.
 
+**Agent `name` on dispatch (BLOCKING — token-usage attribution depends on it).** Every analysis-worker `Agent(...)` call MUST set `name: "<workerId>-worker"` — `name: "claude-worker"` / `name: "codex-worker"` / `name: "gemini-worker"` — exactly as the report-writer dispatch sets `name: "report-writer"` ([okstra-report-writer](./skills/okstra-report-writer/SKILL.md)). The Agent harness records this `name` as `agentName` in the subagent session jsonl, and the Phase 7 token collector matches each worker's session by that `agentName` (`okstra_token_usage/collect.py`). A worker dispatched **without** `name` produces a session with no `agentName`; the collector cannot attribute it and records the worker as `source: "unavailable"` even though the session exists and is team-tagged (observed in `dev-9692` error-analysis: `claude`/`codex` workers dispatched without `name` → both `unavailable`, while the named `report-writer` collected normally). Convergence reverify dispatches keep the prefix (`<workerId>-worker-reverify-r<N>`); implementation executor/verifier variants keep `<workerId>-worker` / `<workerId>-executor`.
+
 The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
 ### Errors log path wiring (BLOCKING)

package/runtime/bin/okstra-spawn-followups.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""OKSTRA follow-up task spawner.
+
+Reads the ``followUpTasks[]`` array from a final-report ``data.json``
+(the JSON SSOT for the final-report markdown) and creates stub task
+directories for rows whose ``autoSpawn`` is ``yes`` AND whose ``origin``
+is not the same-task-key ``phase-continuation`` marker.
+
+Idempotent: rows whose target directory already exists are reported as
+``existing`` and skipped. Existing directories are NEVER mutated.
+
+Output: writes new directories under
+``<project_root>/.okstra/tasks/<task-group>/<new-task-id>/`` with:
+- ``task-manifest.json`` — minimal manifest (schemaVersion 1.0,
+  currentStatus ``todo``, workflow.currentPhase = suggestedTaskType,
+  workflow.currentPhaseState ``not-started``, parentTaskKey /
+  spawnedFromReport recorded under ``relatedTasks``).
+- ``instruction-set/task-brief.md`` — stub brief naming the parent and
+  copying the Reason / Scope cells from the data.json row.
+- ``task-index.md`` — short human-readable summary.
+
+The script DOES NOT call the okstra runtime; it produces just enough
+on-disk state for the next user-driven entry — ``/okstra-run
+task-key=<new-key> task-type=<suggested>`` inside a Claude Code session,
+or ``scripts/okstra.sh --task-key <new-key> --task-type <suggested>``
+in a separate terminal — to pick the follow-up up and re-render a fully
+canonical manifest on first execution.
+
+Usage:
+    python3 scripts/okstra-spawn-followups.py \\
+        <final-report-data.json> \\
+        --project-root <abs-path> \\
+        --task-group <group-slug> \\
+        --parent-task-key <parent-task-key> \\
+        [--dry-run]
+
+Exit codes:
+    0  — at least one follow-up evaluated (including ``skipped`` /
+         ``existing`` only)
+    1  — invocation / parsing failure, or any row failed validation
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from okstra_project.dirs import tasks_root  # noqa: E402
+
+
+SLUG_RE = re.compile(r"[^a-zA-Z0-9-]+")
+
+ALLOWED_TASK_TYPES = {
+    "requirements-discovery",
+    "error-analysis",
+    "implementation-planning",
+    "implementation",
+    "final-verification",
+    "release-handoff",
+}
+ALLOWED_ORIGINS = {
+    "phase-continuation",
+    "out-of-plan",
+    "verifier-concern",
+    "scope-boundary",
+    "open-question",
+    "manual",
+}
+# Origins that point at the SAME task-key (next phase) and therefore
+# must never spawn a new task directory — the user advances via
+# /okstra-run.
+NON_SPAWNING_ORIGINS = {"phase-continuation"}
+
+
+def _slugify(value: str) -> str:
+    value = value.strip()
+    value = SLUG_RE.sub("-", value)
+    value = re.sub(r"-+", "-", value)
+    return value.strip("-").lower()
+
+
+def _validate_row(row: dict) -> tuple[bool, str]:
+    origin = (row.get("origin") or "").strip()
+    if origin not in ALLOWED_ORIGINS:
+        return False, f"invalid origin: {origin!r}"
+    task_type = (row.get("suggestedTaskType") or "").strip()
+    if task_type not in ALLOWED_TASK_TYPES:
+        return False, f"invalid suggestedTaskType: {task_type!r}"
+    if not (row.get("title") or "").strip():
+        return False, "title is empty"
+    if not (row.get("reason") or "").strip():
+        return False, "reason is empty"
+    if not (row.get("newTaskId") or "").strip():
+        return False, "newTaskId is empty"
+    return True, ""
+
+
+def _write_manifest(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _data_to_report_path(data_path: Path) -> Path:
+    """Derive the markdown sibling path used in spawned manifests for
+    the `parentReportPath` field. Falls back to the data.json itself if
+    the suffix is not recognised.
+    """
+    name = data_path.name
+    if name.endswith(".data.json"):
+        return data_path.with_name(name[: -len(".data.json")] + ".md")
+    return data_path.with_suffix(".md")
+
+
+def _spawn_one(
+    *,
+    project_root: Path,
+    task_group: str,
+    parent_task_key: str,
+    parent_report_relative: str,
+    row: dict,
+    dry_run: bool,
+) -> tuple[str, str]:
+    """Returns (status, target_relative_path).
+
+    status ∈ {created, existing, skipped, invalid}
+    """
+    ok, why = _validate_row(row)
+    if not ok:
+        return ("invalid", why)
+
+    new_task_id = _slugify(row["newTaskId"])
+    if not new_task_id:
+        return ("invalid", "newTaskId slug is empty after normalisation")
+
+    task_root = (
+        tasks_root(project_root)
+        / _slugify(task_group)
+        / new_task_id
+    )
+    rel = task_root.relative_to(project_root).as_posix()
+    if task_root.exists():
+        return ("existing", rel)
+    if dry_run:
+        return ("created", rel)
+
+    suggested = row["suggestedTaskType"].strip()
+    title = row["title"].strip()
+    scope = (row.get("scope") or "").strip()
+    reason = row["reason"].strip()
+    origin = row["origin"].strip()
+    priority = (row.get("priority") or "P1").strip()
+    ticket_id = (row.get("ticketId") or "").strip()
+    new_task_key = f"{task_group}/{new_task_id}"
+    now = dt.datetime.now(dt.timezone.utc).isoformat()
+
+    spawned_meta: dict = {
+        "parentTaskKey": parent_task_key,
+        "parentReportPath": parent_report_relative,
+        "origin": origin,
+        "rowId": row.get("id", ""),
+        "priority": priority,
+        "spawnedAt": now,
+    }
+    if ticket_id:
+        spawned_meta["ticketId"] = ticket_id
+
+    manifest_payload = {
+        "schemaVersion": "1.0",
+        "taskGroup": task_group,
+        "taskId": new_task_id,
+        "taskKey": new_task_key,
+        "taskGroupPathSegment": _slugify(task_group),
+        "taskIdPathSegment": new_task_id,
+        "taskType": suggested,
+        "workCategory": "unknown",
+        "currentStatus": "todo",
+        "spawnedFromFollowUp": spawned_meta,
+        "relatedTasks": [
+            {"taskKey": parent_task_key, "relation": "parent-followup-source"},
+        ],
+        "workflow": {
+            "currentPhase": suggested,
+            "currentPhaseState": "not-started",
+            "nextRecommendedPhase": suggested,
+            "phaseStates": {},
+            "awaitingApproval": False,
+            "routingStatus": "follow-up-spawned",
+        },
+    }
+    _write_manifest(task_root / "task-manifest.json", manifest_payload)
+
+    brief_path = task_root / "instruction-set" / "task-brief.md"
+    brief_path.parent.mkdir(parents=True, exist_ok=True)
+    ticket_line = f"- Ticket ID: `{ticket_id}`\n" if ticket_id else ""
+    brief_body = (
+        f"# Follow-up Task Brief — {new_task_key}\n\n"
+        f"- Spawned from: `{parent_task_key}`\n"
+        f"{ticket_line}"
+        f"- Origin: `{origin}`\n"
+        f"- Source report row: `{row.get('id', '')}` in `{parent_report_relative}`\n"
+        f"- Suggested task-type: `{suggested}`\n"
+        f"- Priority: `{priority}`\n"
+        f"- Spawned at: `{now}`\n\n"
+        f"## Title\n\n{title}\n\n"
+        f"## Scope (files / areas)\n\n{scope or '_(미지정)_'}\n\n"
+        f"## Reason / Why deferred from parent run\n\n{reason}\n\n"
+        f"## Next step\n\n"
+        f"이 stub은 사용자가 정식 진입할 때 자동 갱신됩니다. 다음 명령 중 하나로 시작하세요:\n\n"
+        f"- Claude Code 세션 안: `/okstra-run task-key={new_task_key} task-type={suggested}`\n"
+        f"- 별도 터미널: `scripts/okstra.sh --task-key {new_task_key} --task-type {suggested}`\n"
+    )
+    brief_path.write_text(brief_body, encoding="utf-8")
+
+    index_path = task_root / "task-index.md"
+    index_body = (
+        f"# {new_task_key} — Follow-up Task (todo)\n\n"
+        f"- Parent: `{parent_task_key}`\n"
+        f"{ticket_line}"
+        f"- Suggested task-type: `{suggested}`\n"
+        f"- Origin: `{origin}`\n"
+        f"- Priority: `{priority}`\n"
+        f"- Spawned from report: `{parent_report_relative}`\n"
+        f"- Stub brief: `instruction-set/task-brief.md`\n"
+        f"- Status: `todo`\n\n"
+        f"이 task는 자동 생성된 follow-up stub입니다. 정식 진입 시 manifest가 재렌더링됩니다.\n"
+    )
+    index_path.write_text(index_body, encoding="utf-8")
+
+    return ("created", rel)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Spawn follow-up task stubs from a final-report data.json.",
+    )
+    parser.add_argument(
+        "data_file",
+        type=Path,
+        help="Path to the final-report data.json (the JSON SSOT).",
+    )
+    parser.add_argument("--project-root", type=Path, required=True)
+    parser.add_argument(
+        "--task-group",
+        required=True,
+        help="Task-group slug of the parent task.",
+    )
+    parser.add_argument("--parent-task-key", required=True)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Parse and validate only; do not write files.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.data_file.exists():
+        print(f"data.json not found: {args.data_file}", file=sys.stderr)
+        return 1
+
+    try:
+        data = json.loads(args.data_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"invalid JSON in {args.data_file}: {exc}", file=sys.stderr)
+        return 1
+
+    rows = data.get("followUpTasks") or []
+    if not rows:
+        print("followUpTasks is empty — nothing to do.")
+        return 0
+
+    # Manifests record the markdown sibling rather than data.json so the
+    # user-facing report (and not the SSOT) is the cite-able artifact.
+    parent_report = _data_to_report_path(args.data_file)
+    try:
+        parent_report_relative = (
+            parent_report.resolve().relative_to(args.project_root.resolve()).as_posix()
+        )
+    except ValueError:
+        parent_report_relative = str(parent_report)
+
+    results = []
+    for row in rows:
+        origin = (row.get("origin") or "").strip().lower()
+        if origin in NON_SPAWNING_ORIGINS:
+            results.append((
+                "skipped",
+                row.get("newTaskId", ""),
+                f"{origin} (advance via /okstra-run, no new task dir)",
+            ))
+            continue
+        if (row.get("autoSpawn") or "").strip().lower() != "yes":
+            results.append((
+                "skipped",
+                row.get("newTaskId", ""),
+                "autoSpawn != yes",
+            ))
+            continue
+        status, info = _spawn_one(
+            project_root=args.project_root,
+            task_group=args.task_group,
+            parent_task_key=args.parent_task_key,
+            parent_report_relative=parent_report_relative,
+            row=row,
+            dry_run=args.dry_run,
+        )
+        results.append((status, row.get("newTaskId", ""), info))
+
+    print(f"Follow-up spawn summary ({'dry-run' if args.dry_run else 'live'}):")
+    for status, task_id, info in results:
+        print(f"  - [{status}] {task_id}: {info}")
+
+    if any(status == "invalid" for status, *_ in results):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_token_usage/collect.py

@@ -118,6 +118,14 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
     by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
+    # Team-tagged non-lead sessions that carry no agentName. These are almost
+    # always a worker dispatched without the Agent `name` arg (so the harness
+    # recorded no agentName) — the session exists and is team-tagged, but there
+    # is nothing to match it to a workerId by. Surfacing them in usageSummary
+    # gives the "unavailable" worker a visible cause instead of vanishing
+    # silently (observed in dev-9692 error-analysis: claude/codex workers
+    # dispatched without `name` → both unavailable, report-writer named → fine).
+    unattributed_sessions: list[str] = []
     for sid, path in claude_sessions.items():
         if sid == lead_sid:
             lead_path = path
@@ -126,6 +134,8 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         agent = totals.get("agentName")
         if agent:
             by_agent.setdefault(agent, []).append((sid, path, totals))
+        else:
+            unattributed_sessions.append(sid)
 
     # Lead.
     if lead_path is not None:
@@ -242,6 +252,7 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         "teamName": team_name,
         "sessionsFound": len(claude_sessions),
         "unmatchedModels": sorted(set(unmatched_models)),
+        "unattributedTeamSessions": unattributed_sessions,
         "definitions": {
             "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
             "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",

package/runtime/skills/okstra-memory/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: okstra-memory
+description: Use when the user wants to preserve, remember, store, recall, search, or archive AI/human conversation notes in okstra's global Memory Book. Trigger words include "okstra 에 정리해서 보관해", "memory-book", "기억해둬", "대화 저장", "정리해서 저장", "remember this", "store this conversation", "save this decision".
+---
+
+# okstra-memory
+
+Manage the user-home Memory Book at `~/.okstra/memory-book/`.
+
+Memory Book is **global user memory**, not a project-local task artifact.
+It does not require `<PROJECT_ROOT>/.okstra/project.json`, and it must not
+write into any project `.okstra/` directory unless a separate okstra task
+explicitly cites a memory entry later.
+
+## When to use
+
+- The user says "okstra 에 정리해서 보관해", "기억해둬", "대화 저장",
+  "remember this", or similar.
+- The user asks to search, list, show, or archive stored conversation memory.
+- The user wants decisions, preferences, requirements, people/context notes,
+  or follow-ups from the current conversation saved for future retrieval.
+
+## Safety rule
+
+Only save when the user explicitly asks to save/remember/store. If the user is
+only brainstorming, ask one concise confirmation question before writing.
+Never store credentials, API keys, tokens, private personal data, or secrets.
+If the conversation includes sensitive material, omit it and note the omission
+in the stored summary. As a backstop, `okstra memory add` itself refuses content
+matching high-confidence secret shapes (private-key blocks, AWS/GitHub/Slack/Google
+tokens, JWTs) and exits non-zero — redact and retry if you hit it.
+
+## Step 0: Check CLI availability
+
+Run as a separate Bash tool call with literal leading token:
+
+```bash
+okstra memory --help
+```
+
+If `okstra` is not on PATH, tell the user:
+
+`okstra not installed — run npx okstra@latest install once, then retry this skill.`
+
+Do not use `npx` from this skill.
+
+## Store current conversation
+
+1. Extract only durable memory from the conversation:
+   - decision
+   - preference
+   - requirement
+   - person
+   - project-hint
+   - follow-up
+   - context
+2. Write a concise Markdown summary, not a full transcript.
+3. Include provenance:
+   - why it is being stored
+   - source: `conversation`
+   - related project ids if clearly stated
+   - tags useful for search
+4. Store with `--yes` because the user's save request is already explicit.
+
+Command shape:
+
+```bash
+okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --tag <tag> --project <id> --source conversation --yes
+```
+
+Use repeated `--tag` / `--project` flags when needed. Omit `--project` when no
+project is clearly related.
+
+## Search / read / archive
+
+Use:
+
+```bash
+okstra memory search "<query>"
+okstra memory list --tag "<tag>"
+okstra memory show "<memory-id>"
+okstra memory archive "<memory-id>"
+```
+
+Prefer `--json` when you need to parse IDs, then present a short human summary
+to the user.

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -366,7 +366,7 @@ okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --wr
 `okstra token-usage` is a thin Node-side wrapper around the python helper installed at `~/.okstra/bin/okstra-token-usage.py`. Calling the python script directly with `python3 "$HOME/..."` is forbidden — the `$HOME` expansion breaks the literal-token permission match and forces a confirmation prompt every call.
 
 The script reads:
-- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`).
+- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`). **For this `agentName` match to work, Lead MUST set the Agent `name` arg to `<workerId>-worker` on every dispatch** (see [agents SKILL.md Phase 4 — "Agent `name` on dispatch"](../../agents/SKILL.md)); a worker dispatched without `name` carries no `agentName`, so the collector cannot attribute its session and records it `unavailable` (now surfaced as a `usageSummary.unattributedTeamSessions` entry rather than dropped silently).
 - `~/.codex/sessions/Y/M/D/rollout-*.jsonl` for the underlying Codex CLI session (matched by `cwd` and timestamp window of the wrapper subagent). Last `event_msg.token_count.total_token_usage.total_tokens` is the session total.
 - `~/.gemini/tmp/<project>/chats/session-*.json` for the underlying Gemini CLI session. Sum of per-message `tokens.total`.
 

package/src/install.mjs

@@ -28,6 +28,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-render-report-views.py",
   "okstra-render-final-report.py",
   "okstra-wrapper-status.py",
+  "okstra-spawn-followups.py",
 ];
 
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra

package/src/memory.mjs

@@ -0,0 +1,461 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+const MEMORY_TYPES = new Set([
+  "context",
+  "decision",
+  "preference",
+  "requirement",
+  "person",
+  "project-hint",
+  "follow-up",
+]);
+
+// High-confidence secret shapes. The skill instructs the agent to omit secrets,
+// but this is the CLI-side enforcement (declaration → enforcement) so a stray
+// credential cannot be persisted. Patterns are intentionally narrow (known token
+// prefixes / key blocks) to avoid false-positives on prose that merely mentions
+// "password" or "token".
+const SECRET_PATTERNS = [
+  [/-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/, "private key block"],
+  [/\bAKIA[0-9A-Z]{16}\b/, "AWS access key id"],
+  [/\bASIA[0-9A-Z]{16}\b/, "AWS temporary access key id"],
+  [/\bgh[posru]_[A-Za-z0-9]{36,}\b/, "GitHub token"],
+  [/\bgithub_pat_[A-Za-z0-9_]{60,}\b/, "GitHub fine-grained token"],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, "Slack token"],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/, "Google API key"],
+  [/\bsk-[A-Za-z0-9]{20,}\b/, "OpenAI-style secret key"],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/, "JWT"],
+];
+
+function detectSecrets(content) {
+  const hits = [];
+  for (const [pattern, label] of SECRET_PATTERNS) {
+    if (pattern.test(content)) hits.push(label);
+  }
+  return [...new Set(hits)];
+}
+
+const USAGE = `okstra memory — store and find conversation memory
+
+Memory Book stores global, user-home notes under ~/.okstra/memory-book.
+It is separate from project-local .okstra task artifacts.
+
+Usage:
+  okstra memory add [--content <text> | --file <path>] [options]
+  okstra memory list [--limit <n>] [--tag <tag>] [--type <type>] [--json]
+  okstra memory search <query> [--limit <n>] [--include-archived] [--json]
+  okstra memory show <id> [--json]
+  okstra memory archive <id> [--json]
+
+Add options:
+  --title <title>       Entry title. Defaults to the first non-empty line.
+  --type <type>         context|decision|preference|requirement|person|
+                        project-hint|follow-up. Default: context.
+  --scope <scope>       Free-form scope label. Default: global.
+  --project <id>        Related project id. Repeatable.
+  --tag <tag>           Tag. Repeatable or comma-separated.
+  --source <source>     Source label. Default: conversation.
+  --yes                 Skip interactive confirmation.
+  --json                Emit JSON.
+`;
+
+function okstraHome() {
+  const override = (process.env.OKSTRA_HOME || "").trim();
+  return override !== "" ? override : join(homedir(), ".okstra");
+}
+
+function memoryRoot() {
+  return join(okstraHome(), "memory-book");
+}
+
+function indexPath() {
+  return join(memoryRoot(), "index.jsonl");
+}
+
+function parseGlobalFlags(args) {
+  return {
+    json: args.includes("--json"),
+    includeArchived: args.includes("--include-archived"),
+  };
+}
+
+function takeValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function parseAddArgs(args) {
+  const opts = {
+    content: null,
+    file: null,
+    title: null,
+    type: "context",
+    scope: "global",
+    source: "conversation",
+    tags: [],
+    projects: [],
+    yes: false,
+    json: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === "--content") opts.content = takeValue(args, i++, flag);
+    else if (flag === "--file") opts.file = takeValue(args, i++, flag);
+    else if (flag === "--title") opts.title = takeValue(args, i++, flag);
+    else if (flag === "--type") opts.type = takeValue(args, i++, flag);
+    else if (flag === "--scope") opts.scope = takeValue(args, i++, flag);
+    else if (flag === "--source") opts.source = takeValue(args, i++, flag);
+    else if (flag === "--project") opts.projects.push(takeValue(args, i++, flag));
+    else if (flag === "--tag") opts.tags.push(...splitCsv(takeValue(args, i++, flag)));
+    else if (flag === "--yes") opts.yes = true;
+    else if (flag === "--json") opts.json = true;
+    else throw new Error(`unknown flag ${flag}`);
+  }
+  if (!MEMORY_TYPES.has(opts.type)) {
+    throw new Error(`invalid --type: ${opts.type}`);
+  }
+  if (opts.content !== null && opts.file !== null) {
+    throw new Error("pass only one of --content or --file");
+  }
+  return opts;
+}
+
+function parseListArgs(args) {
+  const opts = { ...parseGlobalFlags(args), limit: 20, tag: null, type: null };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === "--json" || flag === "--include-archived") continue;
+    if (flag === "--limit") opts.limit = parseLimit(takeValue(args, i++, flag));
+    else if (flag === "--tag") opts.tag = takeValue(args, i++, flag);
+    else if (flag === "--type") opts.type = takeValue(args, i++, flag);
+    else throw new Error(`unknown flag ${flag}`);
+  }
+  return opts;
+}
+
+function parseQueryArgs(args) {
+  const opts = { ...parseGlobalFlags(args), limit: 20, query: [] };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === "--json" || flag === "--include-archived") continue;
+    if (flag === "--limit") opts.limit = parseLimit(takeValue(args, i++, flag));
+    else if (flag.startsWith("--")) throw new Error(`unknown flag ${flag}`);
+    else opts.query.push(flag);
+  }
+  if (opts.query.length === 0) throw new Error("search requires a query");
+  return { ...opts, query: opts.query.join(" ").trim() };
+}
+
+function parseLimit(raw) {
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("--limit must be a positive integer");
+  }
+  return value;
+}
+
+function splitCsv(value) {
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+async function readInputContent(opts) {
+  if (opts.content !== null) return opts.content;
+  if (opts.file !== null) return fs.readFile(resolve(opts.file), "utf8");
+  if (!process.stdin.isTTY) return readStdin();
+  throw new Error("memory add requires --content, --file, or stdin");
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function inferTitle(content, explicitTitle, filePath) {
+  if (explicitTitle?.trim()) return explicitTitle.trim();
+  const firstLine = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  if (firstLine) return truncate(firstLine.replace(/^#+\s*/, ""), 80);
+  if (filePath) return basename(filePath);
+  return "Untitled memory";
+}
+
+function truncate(value, maxLength) {
+  return value.length > maxLength ? `${value.slice(0, maxLength - 3)}...` : value;
+}
+
+function slugify(value) {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9가-힣]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return slug || "memory";
+}
+
+function buildEntry(opts, content, now) {
+  const title = inferTitle(content, opts.title, opts.file);
+  const compact = now.toISOString().replace(/\D/g, "").slice(0, 17);
+  const slug = slugify(title);
+  const id = `mem_${compact}_${slug}`;
+  const relativePath = join(
+    "entries",
+    String(now.getUTCFullYear()),
+    String(now.getUTCMonth() + 1).padStart(2, "0"),
+    `${now.toISOString().replace(/[:.]/g, "")}-${slug}.md`,
+  );
+  return {
+    id,
+    title,
+    type: opts.type,
+    scope: opts.scope,
+    source: opts.source,
+    tags: [...new Set(opts.tags)],
+    relatedProjects: [...new Set(opts.projects)],
+    status: "active",
+    createdAt: now.toISOString(),
+    archivedAt: null,
+    path: relativePath,
+  };
+}
+
+function renderMarkdown(entry, content) {
+  return [
+    "---",
+    `id: ${entry.id}`,
+    `createdAt: ${entry.createdAt}`,
+    `source: ${entry.source}`,
+    `scope: ${entry.scope}`,
+    `type: ${entry.type}`,
+    `status: ${entry.status}`,
+    `relatedProjects: [${entry.relatedProjects.join(", ")}]`,
+    `tags: [${entry.tags.join(", ")}]`,
+    "---",
+    "",
+    `# ${entry.title}`,
+    "",
+    "## Summary",
+    "",
+    content.trim() || "(empty)",
+    "",
+  ].join("\n");
+}
+
+async function confirmSave(entry, content, opts) {
+  if (opts.yes || opts.json || !process.stdin.isTTY) return true;
+  process.stdout.write(`Memory Book entry:\n`);
+  process.stdout.write(`  title: ${entry.title}\n`);
+  process.stdout.write(`  type:  ${entry.type}\n`);
+  process.stdout.write(`  tags:  ${entry.tags.join(", ") || "(none)"}\n`);
+  process.stdout.write(`  text:  ${truncate(content.trim().replace(/\s+/g, " "), 140)}\n`);
+  const rl = createInterface({ input, output });
+  const answer = await rl.question("Save to ~/.okstra/memory-book? [y/N] ");
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+async function appendIndex(entry) {
+  await fs.mkdir(dirname(indexPath()), { recursive: true });
+  await fs.appendFile(indexPath(), JSON.stringify(entry) + "\n", "utf8");
+}
+
+async function readIndex() {
+  let text;
+  try {
+    text = await fs.readFile(indexPath(), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return text
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+async function writeIndex(entries) {
+  await fs.mkdir(dirname(indexPath()), { recursive: true });
+  const data = entries.map((entry) => JSON.stringify(entry)).join("\n");
+  await fs.writeFile(indexPath(), data ? `${data}\n` : "", "utf8");
+}
+
+function visibleEntries(entries, opts) {
+  return entries.filter((entry) => opts.includeArchived || entry.status !== "archived");
+}
+
+function formatEntryLine(entry) {
+  const tags = entry.tags.length > 0 ? ` #${entry.tags.join(" #")}` : "";
+  return `${entry.id}  ${entry.createdAt.slice(0, 10)}  ${entry.type}  ${entry.title}${tags}`;
+}
+
+function emitJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function opAdd(args) {
+  const opts = parseAddArgs(args);
+  const content = await readInputContent(opts);
+  const secrets = detectSecrets(content);
+  if (secrets.length > 0) {
+    throw new Error(
+      `refusing to store likely secret(s): ${secrets.join(", ")}. ` +
+        "Memory Book must not hold credentials — redact the secret and store a note instead.",
+    );
+  }
+  const entry = buildEntry(opts, content, new Date());
+  if (!(await confirmSave(entry, content, opts))) {
+    process.stdout.write("cancelled\n");
+    return 0;
+  }
+  const absolutePath = join(memoryRoot(), entry.path);
+  await fs.mkdir(dirname(absolutePath), { recursive: true });
+  await fs.writeFile(absolutePath, renderMarkdown(entry, content), "utf8");
+  try {
+    await appendIndex(entry);
+  } catch (err) {
+    // Index append failed after the file was written — remove the orphan so
+    // `add` stays all-or-nothing (an entry with no index row is invisible to
+    // list/search anyway).
+    await fs.rm(absolutePath, { force: true });
+    throw err;
+  }
+  if (opts.json) emitJson({ ok: true, entry, path: absolutePath });
+  else process.stdout.write(`saved ${entry.id}\n${absolutePath}\n`);
+  return 0;
+}
+
+async function opList(args) {
+  const opts = parseListArgs(args);
+  const entries = visibleEntries(await readIndex(), opts)
+    .filter((entry) => !opts.tag || entry.tags.includes(opts.tag))
+    .filter((entry) => !opts.type || entry.type === opts.type)
+    .slice(0, opts.limit);
+  if (opts.json) emitJson(entries);
+  else process.stdout.write(entries.map(formatEntryLine).join("\n") + (entries.length ? "\n" : ""));
+  return 0;
+}
+
+async function opSearch(args) {
+  const opts = parseQueryArgs(args);
+  const needle = opts.query.toLowerCase();
+  const entries = visibleEntries(await readIndex(), opts);
+  const matches = [];
+  for (const entry of entries) {
+    if (await entryMatches(entry, needle)) matches.push(entry);
+    if (matches.length >= opts.limit) break;
+  }
+  if (opts.json) emitJson(matches);
+  else process.stdout.write(matches.map(formatEntryLine).join("\n") + (matches.length ? "\n" : ""));
+  return 0;
+}
+
+async function entryMatches(entry, needle) {
+  const haystack = [
+    entry.id,
+    entry.title,
+    entry.type,
+    entry.scope,
+    entry.source,
+    ...entry.tags,
+    ...entry.relatedProjects,
+  ]
+    .join(" ")
+    .toLowerCase();
+  if (haystack.includes(needle)) return true;
+  try {
+    const body = await fs.readFile(join(memoryRoot(), entry.path), "utf8");
+    return body.toLowerCase().includes(needle);
+  } catch {
+    return false;
+  }
+}
+
+async function findEntry(id) {
+  const entries = await readIndex();
+  const entry = entries.find((candidate) => candidate.id === id);
+  if (!entry) throw new Error(`memory entry not found: ${id}`);
+  return { entry, entries };
+}
+
+async function opShow(args) {
+  const json = args.includes("--json");
+  const ids = args.filter((arg) => arg !== "--json");
+  if (ids.length !== 1) throw new Error("show requires exactly one id");
+  const { entry } = await findEntry(ids[0]);
+  const absolutePath = join(memoryRoot(), entry.path);
+  const body = await fs.readFile(absolutePath, "utf8");
+  if (json) emitJson({ entry, path: absolutePath, body });
+  else process.stdout.write(body);
+  return 0;
+}
+
+async function opArchive(args) {
+  const json = args.includes("--json");
+  const ids = args.filter((arg) => arg !== "--json");
+  if (ids.length !== 1) throw new Error("archive requires exactly one id");
+  const { entry, entries } = await findEntry(ids[0]);
+  const archivedEntry = await moveToArchive(entry);
+  const updated = entries.map((candidate) =>
+    candidate.id === entry.id ? archivedEntry : candidate,
+  );
+  await writeIndex(updated);
+  if (json) emitJson({ ok: true, entry: archivedEntry });
+  else process.stdout.write(`archived ${entry.id}\n`);
+  return 0;
+}
+
+async function moveToArchive(entry) {
+  if (entry.status === "archived") return entry;
+  const sourcePath = join(memoryRoot(), entry.path);
+  const archiveDir = join("archive", entry.createdAt.slice(0, 4));
+  const nextPath = join(archiveDir, basename(entry.path));
+  const targetPath = join(memoryRoot(), nextPath);
+  await fs.mkdir(dirname(targetPath), { recursive: true });
+  await fs.rename(sourcePath, targetPath);
+  return {
+    ...entry,
+    status: "archived",
+    archivedAt: new Date().toISOString(),
+    path: relative(memoryRoot(), targetPath),
+  };
+}
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  const [op, ...rest] = args;
+  try {
+    switch (op) {
+      case "add":
+        return await opAdd(rest);
+      case "list":
+        return await opList(rest);
+      case "search":
+        return await opSearch(rest);
+      case "show":
+        return await opShow(rest);
+      case "archive":
+        return await opArchive(rest);
+      default:
+        process.stderr.write(`unknown memory subcommand: ${op}\n\n${USAGE}`);
+        return 2;
+    }
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 1;
+  }
+}

package/src/uninstall.mjs

@@ -20,6 +20,7 @@ const FALLBACK_SKILL_NAMES = [
   "okstra-setup",
   "okstra-brief",
   "okstra-run",
+  "okstra-memory",
   "okstra-inspect",
   "okstra-schedule",
   "okstra-context-loader",