okstra 0.43.1 → 0.45.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.1",
+  "version": "0.45.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.1",
-  "builtAt": "2026-06-04T05:01:10.794Z",
+  "package": "0.45.0",
+  "builtAt": "2026-06-04T06:11:59.186Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/report_views.py

@@ -300,6 +300,10 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
         rows.append(_split_pipe_row(lines[i]))
         i += 1
 
+    grouped_spec = _grouped_table_spec(header_cells, section_path)
+    if grouped_spec is not None:
+        return _emit_grouped_table(header_cells, rows, grouped_spec), i - start
+
     is_clarification_table = (
         not _section_forbids_form(section_path)
         and any("Clarification Items" in h for h in section_path)
@@ -383,6 +387,172 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
     return f"<table>{head}{body}</table>", i - start
 
 
+@dataclass(frozen=True)
+class _GroupedSpec:
+    """Plan for rendering a wide table as a compact grouped layout: the
+    short columns (``group_cols``) collapse into one stacked ``key:
+    value`` metadata cell led by ``headline_col``; the long columns
+    (``wide_cols``) each keep their own min-width column.
+
+    ``kind == "clarification"`` additionally re-attaches the §5 form
+    widget to the ``user_input_col`` cell and the ``data-*`` row attrs."""
+    headline_col: int
+    group_cols: tuple[int, ...]
+    wide_cols: tuple[int, ...]
+    kind: str  # "plain" | "clarification"
+    id_col: int = -1
+    kind_col: int = -1
+    status_col: int = -1
+    statement_col: int = -1
+    user_input_col: int = -1
+
+
+_FOLLOWUP_WIDE_PREFIXES: tuple[str, ...] = ("title", "scope", "reason")
+
+
+def _grouped_table_spec(
+    header_cells: list[str], section_path: list[str]
+) -> Optional[_GroupedSpec]:
+    """Return a ``_GroupedSpec`` for the three wide final-report tables
+    that benefit from the compact layout — Execution Status, §5
+    Clarification Items, §7 Follow-up Tasks — or ``None`` for every other
+    table (which keeps the default per-cell ``td-narrow`` rendering).
+
+    Each table is identified by stable header tokens (the i18n token/cost
+    columns are never used as anchors). ``wide_cols`` lists the long-prose
+    columns that must keep a guaranteed min-width; everything else short
+    collapses into the leading metadata cell."""
+    norm = [h.strip() for h in header_cells]
+
+    def _spec(headline: int, wide: tuple[int, ...], **kw) -> _GroupedSpec:
+        wide_set = set(wide)
+        group = tuple(c for c in range(len(norm)) if c != headline and c not in wide_set)
+        return _GroupedSpec(headline_col=headline, group_cols=group, wide_cols=wide, **kw)
+
+    # Execution Status by Agent — Agent … Summary of Key Findings.
+    if len(norm) >= 3 and norm[0] == "Agent" and norm[-1] == "Summary of Key Findings":
+        return _spec(0, (len(norm) - 1,), kind="plain")
+
+    # §5 Clarification Items — keep the interactive form, but collapse the
+    # short ID/Kind/Status/… columns and widen Statement + User input.
+    if (
+        any("Clarification Items" in h for h in section_path)
+        and not _section_forbids_form(section_path)
+        and "ID" in norm
+        and "User input" in norm
+        and any(h.startswith("Statement") for h in norm)
+    ):
+        statement_col = next(i for i, h in enumerate(norm) if h.startswith("Statement"))
+        user_input_col = norm.index("User input")
+        return _spec(
+            norm.index("ID"),
+            (statement_col, user_input_col),
+            kind="clarification",
+            id_col=norm.index("ID"),
+            kind_col=norm.index("Kind") if "Kind" in norm else -1,
+            status_col=norm.index("Status") if "Status" in norm else -1,
+            statement_col=statement_col,
+            user_input_col=user_input_col,
+        )
+
+    # §7 Follow-up Tasks — widen Title / Scope / Reason, collapse the rest.
+    if any("Follow-up Tasks" in h for h in section_path) and "ID" in norm:
+        wide = tuple(
+            i
+            for i, h in enumerate(norm)
+            if any(h.lower().startswith(p) for p in _FOLLOWUP_WIDE_PREFIXES)
+        )
+        if wide:
+            return _spec(norm.index("ID"), wide, kind="plain")
+
+    return None
+
+
+def _grouped_meta_cell(
+    header_cells: list[str], row: list[str], spec: _GroupedSpec
+) -> str:
+    """The leading metadata ``<td>``: a bold headline (``headline_col``)
+    above one ``key: value`` line per collapsed short column."""
+    headline = row[spec.headline_col] if spec.headline_col < len(row) else ""
+    fields = "".join(
+        '<div class="grp-field">'
+        f'<span class="grp-key">{_inline(header_cells[col])}</span>'
+        f'<span class="grp-val">{_inline(row[col] if col < len(row) else "")}</span>'
+        "</div>"
+        for col in spec.group_cols
+    )
+    return (
+        '<td class="grp-meta">'
+        f'<div class="grp-headline">{_inline(headline)}</div>'
+        f"{fields}</td>"
+    )
+
+
+def _grouped_clarification_row(
+    row: list[str], spec: _GroupedSpec
+) -> tuple[str, str]:
+    """Return ``(tr_attrs, wide_cells_html)`` for one §5 row, re-attaching
+    the form widget + ``data-*`` attrs to ``C-\\d+`` rows exactly as the
+    non-grouped path does."""
+    rid = row[spec.id_col] if 0 <= spec.id_col < len(row) else ""
+    is_form_row = bool(re.fullmatch(r"C-\d+", rid)) and spec.user_input_col >= 0
+    kind = row[spec.kind_col] if is_form_row and 0 <= spec.kind_col < len(row) else ""
+    status = row[spec.status_col] if is_form_row and 0 <= spec.status_col < len(row) else ""
+    statement = (
+        row[spec.statement_col]
+        if is_form_row and 0 <= spec.statement_col < len(row)
+        else ""
+    )
+    tr_attrs = (
+        f' data-response-id="{html.escape(rid)}" '
+        f'data-kind="{html.escape(kind)}" '
+        f'data-status="{html.escape(status)}"'
+        if is_form_row
+        else ""
+    )
+    cells: list[str] = []
+    for col in spec.wide_cols:
+        value = row[col] if col < len(row) else ""
+        if is_form_row and col == spec.user_input_col:
+            cells.append(
+                f'<td class="grp-wide grp-form">'
+                f"{_form_control(rid, kind, status, value, statement)}</td>"
+            )
+        else:
+            cells.append(f'<td class="grp-wide">{_inline(value)}</td>')
+    return tr_attrs, "".join(cells)
+
+
+def _emit_grouped_table(
+    header_cells: list[str], rows: list[list[str]], spec: _GroupedSpec
+) -> str:
+    """Render a wide table in the compact grouped layout described by
+    ``spec`` — one metadata cell plus the min-width long columns."""
+    head = (
+        "<thead><tr>"
+        f"<th>{_inline(header_cells[spec.headline_col])}</th>"
+        + "".join(
+            f'<th class="grp-wide">{_inline(header_cells[col])}</th>'
+            for col in spec.wide_cols
+        )
+        + "</tr></thead>"
+    )
+    body_rows: list[str] = []
+    for row in rows:
+        meta = _grouped_meta_cell(header_cells, row, spec)
+        if spec.kind == "clarification":
+            tr_attrs, wide_cells = _grouped_clarification_row(row, spec)
+        else:
+            tr_attrs = ""
+            wide_cells = "".join(
+                f'<td class="grp-wide">{_inline(row[col] if col < len(row) else "")}</td>'
+                for col in spec.wide_cols
+            )
+        body_rows.append(f"<tr{tr_attrs}>{meta}{wide_cells}</tr>")
+    body = "<tbody>" + "".join(body_rows) + "</tbody>"
+    return f'<table class="grouped-table">{head}{body}</table>'
+
+
 _ENUM_LETTERS = "abcde"
 _ENUM_CUE_WORDS: tuple[str, ...] = (
     "권장은", "권장 ", "추천은", "추천 ", "사유:", "사유 ", "근거:",

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/templates/reports/report.css

@@ -132,6 +132,38 @@ td.td-narrow, th.td-narrow {
   width: 5%;
   white-space: nowrap;
 }
+/* Compact grouped layout for the wide final-report tables (Execution
+ * Status, §5 Clarification Items, §7 Follow-up Tasks): the short
+ * columns collapse into one stacked `key: value` metadata cell, while
+ * each long-prose column keeps its own guaranteed min-width so it never
+ * gets squashed into a one-character ladder. */
+table.grouped-table td.grp-meta {
+  width: 24%;
+}
+table.grouped-table th.grp-wide,
+table.grouped-table td.grp-wide {
+  min-width: 18ch;
+}
+.grp-meta .grp-headline {
+  font-weight: 600;
+  margin-bottom: 0.4em;
+}
+.grp-meta .grp-field {
+  display: flex;
+  gap: 0.45em;
+  font-size: 0.88rem;
+  line-height: 1.55;
+}
+.grp-meta .grp-key {
+  color: GrayText;
+  white-space: nowrap;
+}
+.grp-meta .grp-key::after {
+  content: ":";
+}
+.grp-meta .grp-val {
+  overflow-wrap: anywhere;
+}
 thead th {
   position: sticky;
   top: 3rem;

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",