Skip to content

Commit 373f4eb

Browse files
committed
Merge recall into journal: ctx recall → ctx journal source
Absorb the entire ctx recall command tree into ctx journal. recall list/show become journal source (--show flag dispatch), import/lock/unlock/sync move directly under journal. CLI surface: ctx journal source (was: ctx recall list) ctx journal source --show <id> (was: ctx recall show) ctx journal import (was: ctx recall import) ctx journal lock/unlock/sync (was: ctx recall lock/unlock/sync) Code changes: - Create journal/cmd/source/ with flag-based list/show dispatch - Move recall/cmd/* subcommands under journal/cmd/ - Merge write/recall/ → write/journal/source.go - Merge err/recall/ → err/journal/source.go - Rename all config constants: UseRecall* → UseJournal*, DescKeyRecall* → DescKeyJournal* - Rename all YAML keys: recall.* → journal.* - Rename MCP tool: ctx_recall → ctx_journal_source - Remove recall from bootstrap registration - Delete internal/cli/recall/, internal/write/recall/, internal/err/recall/ Documentation: - Update 12 skills, 2 CLAUDE.md files, AGENT_PLAYBOOK - Update docs/cli, recipes, architecture diagrams - Fix architecture-dia-build.md: 23 → 31 CLI packages, add missing directories, recall/parser → journal/parser - Rebuild site/ - Delete obsolete doccheck script Spec: specs/journal-recall-merge.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
1 parent b09642c commit 373f4eb

84 files changed

Lines changed: 521 additions & 730 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.claude/skills/_ctx-qa/SKILL.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ they hit CI.
3434

3535
```text
3636
/_ctx-qa
37-
/_ctx-qa (after refactoring the recall command)
37+
/_ctx-qa (after refactoring the journal command)
3838
```
3939

4040
## What to Run
@@ -77,7 +77,7 @@ make smoke
7777

7878
Builds the binary and exercises `ctx init`, `ctx status`,
7979
`ctx agent`, `ctx drift`, `ctx add task`, and
80-
`ctx recall list` in a temp directory.
80+
`ctx journal source` in a temporary directory.
8181

8282
## Shortcut
8383

.claude/skills/_ctx-update-docs/SKILL.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ conventions for consistency.
4747
| `internal/config/` | `docs/home/context-files.md`, `docs/home/configuration.md` |
4848
| `internal/context/` | `docs/home/context-files.md`, `docs/home/prompting-guide.md` |
4949
| `internal/drift/` | `docs/recipes/context-health.md` |
50-
| `internal/journal/` | `docs/reference/session-journal.md`, `docs/cli/recall.md` |
50+
| `internal/journal/` | `docs/reference/session-journal.md`, `docs/cli/journal.md` |
5151
| `internal/bootstrap/` | `docs/home/getting-started.md` |
5252
| `internal/claude/`, `internal/rc/` | `docs/operations/integrations.md`, `docs/home/configuration.md` |
5353
| `internal/assets/` | `docs/home/context-files.md` (templates) |

.context/AGENT_PLAYBOOK.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ a problem as "pre-existing" or "not related to my changes."
209209
Never assume. If you don't see it in files, you don't know it.
210210

211211
- Don't claim "we discussed X" without file evidence
212-
- Don't invent history — check context files and `ctx recall`
212+
- Don't invent history — check context files and `ctx journal source`
213213
- If uncertain, say "I don't see this documented"
214214
- Trust files over intuition
215215

.context/ARCHITECTURE.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ upward from them. The `rc` package mediates config resolution;
114114
| `notify` | Send fire-and-forget webhook notifications |
115115
| `pad` | Encrypted scratchpad CRUD with blob support and merge |
116116
| `permissions` | Permission snapshot/restore (golden images) for Claude Code |
117-
| `recall` | Browse, import, lock/unlock AI session history |
117+
| `recall` | *(merged into `journal`)* Browse, import, lock/unlock AI session history |
118118
| `reindex` | Regenerate indices for DECISIONS.md and LEARNINGS.md |
119119
| `remind` | Session-scoped reminders surfaced at start |
120120
| `serve` | Serve static journal site locally via zensical |
@@ -145,7 +145,7 @@ Five core flows define how data moves through the system:
145145
constitution compliance, required files, file age, entry count,
146146
missing packages) → returns report with warnings and violations.
147147

148-
4. **`ctx recall import`**: User invokes with `--all``cli/recall`
148+
4. **`ctx journal import`**: User invokes with `--all``cli/journal`
149149
calls `parser.FindSessionsForCWD()` which scans
150150
`~/.claude/projects/` → parses JSONL transcripts → loads journal
151151
state → plans each session (new/regen/skip/locked) → formats as
@@ -178,7 +178,7 @@ Five state machines govern lifecycle transitions:
178178
pending children remain) → Archived (via `ctx task archive` to
179179
`.context/archive/`).
180180

181-
3. **Journal pipeline**: Imported (JSONL→MD via `recall import`) →
181+
3. **Journal pipeline**: Imported (JSONL→MD via `journal import`) →
182182
Enriched (YAML frontmatter, tags) → Normalized (soft-wrap, clean
183183
JSON) → Fences Verified (fence balance check) → Locked (prevent
184184
overwrite). Each stage tracked in `.context/journal/.state.json`;

.context/DECISIONS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1007,7 +1007,7 @@ See: `specs/injection-oversize-nudge.md`.
10071007

10081008
**Rationale**: Dead-end write sinks waste code surface, maintenance effort, and user attention. The recall pipeline already proved that reading directly from `~/.claude/projects/` is sufficient. Context snapshots are redundant with git history. Removing the middle layer simplifies the architecture from three stores to two, eliminates an entire CLI command tree (`ctx session`), and removes a shell hook that fired on every session end.
10091009

1010-
**Consequence**: Deleted `internal/cli/session/` (15 files), removed auto-save hook, removed `--auto-save` from watch, removed pre-compact auto-save from compact, removed `/ctx-save` skill, updated ~45 documentation files. Four earlier decisions superseded (SessionEnd hook, Auto-Save Before Compact, Session Filename Format, Two-Tier Persistence Model). Users who want session history use `ctx recall list/export` instead.
1010+
**Consequence**: Deleted `internal/cli/session/` (15 files), removed auto-save hook, removed `--auto-save` from watch, removed pre-compact auto-save from compact, removed `/ctx-save` skill, updated ~45 documentation files. Four earlier decisions superseded (SessionEnd hook, Auto-Save Before Compact, Session Filename Format, Two-Tier Persistence Model). Users who want session history use `ctx journal source`/`ctx journal import` instead.
10111011

10121012
---
10131013

.context/DETAILED_DESIGN.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1018,7 +1018,7 @@ Consult specific sections when working on a module.
10181018
| `check-context-size` | UserPromptSubmit | (all) | Adaptive counter: silent 1–15, every 5th 16–30, every 3rd 30+. Per-session counter in temp file | Per-session |
10191019
| `check-persistence` | UserPromptSubmit | (all) | Track .context/ mtime; silent 1–10, nudge at #20 if no modifications, then every 15 prompts since last mod | Per-session |
10201020
| `check-ceremonies` | UserPromptSubmit | (all) | Scan last 3 journal entries for "ctx-remember" and "ctx-wrap-up" strings; nudge missing ceremonies | Daily |
1021-
| `check-journal` | UserPromptSubmit | (all) | Stage 1: count .jsonl files newer than latest journal export. Stage 2: count unenriched entries via journal/state. Suggest `ctx recall import --all` and `/ctx-journal-enrich-all` | Daily |
1021+
| `check-journal` | UserPromptSubmit | (all) | Stage 1: count .jsonl files newer than latest journal export. Stage 2: count unenriched entries via journal/state. Suggest `ctx journal import --all` and `/ctx-journal-enrich-all` | Daily |
10221022
| `check-reminders` | UserPromptSubmit | (all) | Surface due reminders (After ≤ today) from reminders.json with dismiss commands | None (until dismissed) |
10231023
| `check-version` | UserPromptSubmit | (all) | Compare binary version (ldflags) vs plugin.json major.minor; skip "dev" builds. Piggyback: check encryption key age vs `rc.KeyRotationDays()` | Daily |
10241024
| `check-resources` | UserPromptSubmit | (all) | `sysinfo.Collect()` + `Evaluate()`; output ONLY at DANGER severity (mem≥90%, swap≥75%, disk≥95%, load≥1.5x CPUs) | None |

.context/GLOSSARY.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ DO NOT UPDATE FOR:
2828
| Read order | The priority sequence in which context files are loaded and presented to agents. Defined by `config.FileReadOrder`. Higher priority files are loaded first and survive token budget cuts. |
2929
| Token budget | Maximum estimated token count for assembled context. Default 8000. Configurable via `CTX_TOKEN_BUDGET`, `.ctxrc`, or `--budget` flag. Uses 4-chars-per-token heuristic. |
3030
| Curated tier | The `.context/*.md` files: manually maintained, token-budgeted, loaded by `ctx agent`. Contrast with full-dump tier. |
31-
| Full-dump tier | The `.context/journal/` directory: imported session transcripts. Not auto-loaded; used for archaeology when curated context is insufficient. Browse with `ctx recall`. |
31+
| Full-dump tier | The `.context/journal/` directory: imported session transcripts. Not auto-loaded; used for archaeology when curated context is insufficient. Browse with `ctx journal source`. |
3232
| Compaction | The process of archiving completed tasks and cleaning up context files. Run via `ctx compact`. Moves completed tasks to archive; preserves phase structure. |
3333
| Entry header | The timestamped heading format used in DECISIONS.md and LEARNINGS.md: `## [YYYY-MM-DD-HHMMSS] Title`. Parsed by `config.RegExEntryHeader`. |
3434
| Index table | The auto-generated markdown table at the top of DECISIONS.md and LEARNINGS.md (between `<!-- INDEX:START -->` and `<!-- INDEX:END -->` markers). Updated by `ctx add` and `ctx decision/learnings reindex`. |

.context/LEARNINGS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -913,7 +913,7 @@ DO NOT UPDATE FOR:
913913
**Consolidated from**: 5 entries (2026-01-20 to 2026-01-25)
914914

915915
- `ctx agent` is optimized for task execution (filters pending tasks, surfaces constitution, token-budget aware). Manual file reading is better for exploratory/memory questions (session history, timestamps, completed tasks).
916-
- On "Do you remember?" questions, immediately read .context/ files and run `ctx recall list --limit 5`. Never ask "would you like me to check?" — that is the obvious intent.
916+
- On "Do you remember?" questions, immediately read .context/ files and run `ctx journal source --limit 5`. Never ask "would you like me to check?" — that is the obvious intent.
917917
- .context/ is NOT a Claude Code primitive. Only CLAUDE.md and .claude/settings.json are auto-loaded. The .context/ directory requires a hook or explicit CLAUDE.md instruction to be discovered.
918918
- ~~Orchestrator (IMPLEMENTATION_PLAN.md) and agent (.context/TASKS.md) task lists must be separate.~~ (Superseded 2026-03-25: IMPLEMENTATION_PLAN.md removed. TASKS.md is the single task source.)
919919
- Only CLAUDE.md is auto-loaded by Claude Code. Projects using ctx should rely on the CLAUDE.md -> AGENT_PLAYBOOK.md chain, not AGENTS.md.

.context/TASKS.md

Lines changed: 39 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1009,66 +1009,65 @@ block template.
10091009
Spec: `specs/journal-recall-merge.md`. Read the spec before starting any
10101010
JRM task.
10111011

1012-
Absorb `ctx recall` into `ctx journal`. `recall list`/`show` become
1013-
`journal source --list`/`--show`. `recall import/lock/unlock/sync` move
1014-
directly under `journal`. Delete `recall` as a top-level command.
1012+
Absorb `ctx recall` into `ctx journal`. `recall list`/`show` became
1013+
`journal source --list`/`--show`. `recall import/lock/unlock/sync` moved
1014+
directly under `journal`. `recall` deleted as a top-level command.
10151015

10161016
- [x] JRM.1: Create `journal/cmd/source/` — new subcommand combining list+show
10171017
with `--list` (default) / `--show <id>` flag dispatch. Reuse existing list and
10181018
show `run.go` logic. #added:2026-03-26 #done:2026-03-26
10191019
- [x] JRM.2: Move import/lock/unlock/sync subcommands from `recall/cmd/` to
10201020
`journal/cmd/`. Update imports in `journal.go` to wire them.
10211021
#added:2026-03-26 #done:2026-03-26
1022-
- [ ] JRM.3: Move `recall/core/*` packages into `journal/core/`. Rename
1022+
- [x] JRM.3: Move `recall/core/*` packages into `journal/core/`. Rename
10231023
colliding packages: `recall/core/format/``journal/core/sourceformat/`,
1024-
`recall/core/frontmatter/``journal/core/sourcefm/`. #added:2026-03-26
1025-
- [ ] JRM.4: Merge `internal/write/recall/` functions into
1024+
`recall/core/frontmatter/``journal/core/sourcefm/`. #added:2026-03-26 #done:2026-03-26
1025+
- [x] JRM.4: Merge `internal/write/recall/` functions into
10261026
`internal/write/journal/` (new file `source.go`). Delete
1027-
`write/recall/`. #added:2026-03-26
1028-
- [ ] JRM.5: Merge `internal/err/recall/` functions into `internal/err/journal/`
1029-
(new file `source.go`). Delete `err/recall/`. #added:2026-03-26
1030-
- [ ] JRM.6: Update config constants — rename `UseRecall*` / `DescKeyRecall*` to
1027+
`write/recall/`. #added:2026-03-26 #done:2026-03-26
1028+
- [x] JRM.5: Merge `internal/err/recall/` functions into `internal/err/journal/`
1029+
(new file `source.go`). Delete `err/recall/`. #added:2026-03-26 #done:2026-03-26
1030+
- [x] JRM.6: Update config constants — rename `UseRecall*` / `DescKeyRecall*` to
10311031
`UseJournalSource*` / `DescKeyJournalSource*` in `config/embed/cmd/`. Remove
1032-
`UseRecall` from `base.go`. Update `journal.go` constants. #added:2026-03-26
1033-
- [ ] JRM.7: Update flag constants — rename `recall.*` keys in
1032+
`UseRecall` from `base.go`. Update `journal.go` constants. #added:2026-03-26 #done:2026-03-26
1033+
- [x] JRM.7: Update flag constants — rename `recall.*` keys in
10341034
`config/embed/flag/recall.go` to `journal.source.*` /
1035-
`journal.import.*`. #added:2026-03-26
1036-
- [ ] JRM.8: Update text constants — rename all `recall.*`, `write.recall-*`,
1035+
`journal.import.*`. #added:2026-03-26 #done:2026-03-26
1036+
- [x] JRM.8: Update text constants — rename all `recall.*`, `write.recall-*`,
10371037
`err.recall.*`, `mcp.recall-*` keys in `config/embed/text/`. Rename source
1038-
files (`recall.go``journal_source.go`, etc.). #added:2026-03-26
1039-
- [ ] JRM.9: Update YAML files — rename keys in `commands.yaml`, `flags.yaml`,
1040-
`text/write.yaml`, `text/ui.yaml`. #added:2026-03-26
1041-
- [ ] JRM.10: Update MCP tool — rename `ctx_recall` to `ctx_journal_source` in
1038+
files (`recall.go``journal_source.go`, etc.). #added:2026-03-26 #done:2026-03-26
1039+
- [x] JRM.9: Update YAML files — rename keys in `commands.yaml`, `flags.yaml`,
1040+
`text/write.yaml`, `text/ui.yaml`. #added:2026-03-26 #done:2026-03-26
1041+
- [x] JRM.10: Update MCP tool — rename `ctx_recall` to `ctx_journal_source` in
10421042
`mcp/server/route/tool/`, `mcp/handler/tool.go`, `mcp/server/server_test.go`,
1043-
and `config/embed/text/mcp_tool.go`. #added:2026-03-26
1043+
and `config/embed/text/mcp_tool.go`. #added:2026-03-26 #done:2026-03-26
10441044
- [x] JRM.11: Remove `recall` from bootstrap — delete `recall.Cmd` registration
10451045
in `bootstrap.go`, remove import. #added:2026-03-26 #done:2026-03-26
1046-
- [ ] JRM.12: Delete `internal/cli/recall/` entirely after all code is
1047-
moved. #added:2026-03-26
1048-
- [ ] JRM.13: Update skills — rename `ctx-recall/` skill dir to
1049-
`ctx-journal-browse/`, update all `ctx recall` commands to `ctx journal`
1046+
- [x] JRM.12: Delete `internal/cli/recall/` entirely after all code is
1047+
moved. #added:2026-03-26 #done:2026-03-26
1048+
- [x] JRM.13: Update skills — rename `ctx-recall/` skill dir to
1049+
`ctx-history/`, update all `ctx recall` commands to `ctx journal`
10501050
equivalents. Update `ctx-remember` skill to use `ctx journal source` instead
10511051
of `ctx recall list`. Check journal-enrich, journal-enrich-all,
10521052
journal-normalize for stale recall refs. Delete
1053-
`.claude/skills/generated/recall/`. #added:2026-03-26
1054-
- [ ] JRM.14: Update CLAUDE.md files — `ctx recall list``ctx journal source`
1055-
in both `CLAUDE.md` and `internal/assets/claude/CLAUDE.md`. #added:2026-03-26
1056-
- [ ] JRM.15: Update docs — rewrite `docs/cli/recall.md` as unified journal
1053+
`.claude/skills/generated/recall/`. #added:2026-03-26 #done:2026-03-26
1054+
- [x] JRM.14: Update CLAUDE.md files — `ctx recall list``ctx journal source`
1055+
in both `CLAUDE.md` and `internal/assets/claude/CLAUDE.md`. Already done in
1056+
a prior pass. #added:2026-03-26 #done:2026-03-26
1057+
- [x] JRM.15: Update docs — rewrite `docs/cli/recall.md` as unified journal
10571058
reference (rename to `docs/cli/journal.md`). Update `docs/cli/index.md`
1058-
nav. #added:2026-03-26
1059-
- [ ] JRM.16: Update recipes — find/replace `ctx recall``ctx journal`
1060-
equivalents across all 12 recipe files that reference
1061-
recall. #added:2026-03-26
1062-
- [ ] JRM.17: Update context files — `.context/ARCHITECTURE.md`,
1059+
nav. #added:2026-03-26 #done:2026-03-26
1060+
- [x] JRM.16: Update recipes — find/replace `ctx recall``ctx journal`
1061+
equivalents across recipe files that reference recall. #added:2026-03-26 #done:2026-03-26
1062+
- [x] JRM.17: Update context files — `.context/ARCHITECTURE.md`,
10631063
`.context/AGENT_PLAYBOOK.md`, `.context/architecture-dia-*.md`,
10641064
`specs/future-complete/recall-sync.md`,
1065-
`specs/future-complete/recall-export-safety.md`. #added:2026-03-26
1066-
- [ ] JRM.18: Update other TASKS.md references — grep TASKS.md for `recall` and
1067-
update task descriptions that reference the old command names (e.g., P0.9.2
1068-
cli-recall, PM.7 recall architecture, F.2 recall import). #added:2026-03-26
1069-
- [ ] JRM.19: Run `make lint && make test` — full green. #added:2026-03-26
1070-
- [ ] JRM.20: Rebuild site — `make docs` or equivalent to regenerate
1071-
`site/`. #added:2026-03-26
1065+
`specs/future-complete/recall-export-safety.md`. #added:2026-03-26 #done:2026-03-26
1066+
- [-] JRM.18: Update other TASKS.md references — historical task descriptions
1067+
stay as-is (they document what the command was called at the time). #added:2026-03-26
1068+
- [x] JRM.19: Run `make lint && make test` — full green. #added:2026-03-26 #done:2026-03-26
1069+
- [x] JRM.20: Rebuild site — `make docs` or equivalent to regenerate
1070+
`site/`. #added:2026-03-26 #done:2026-03-26
10721071

10731072
## MCP-related
10741073

@@ -1135,7 +1134,7 @@ age-based — prune files older than N days (default 7).
11351134
ctx-wrapped-up all have the same cross-session suppression bug as
11361135
memory-drift-nudged #added:2026-03-05-205425
11371136

1138-
- [ ] F.2: ctx recall import — import Claude Code session JSONLs from local or
1137+
- [ ] F.2: ctx journal import (remote) — import Claude Code session JSONLs from local or
11391138
remote (~/.claude/projects/) into local ~/.claude/projects/. Pure Go: local
11401139
copy with os.CopyFS-style walk, remote via os/exec ssh+scp (no rsync
11411140
dependency). --source flag accepts local path or user@host. --dry-run shows

0 commit comments

Comments
 (0)