You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: update README/tutorial/architecture for 0.3.0 trust split (#21 P1)
User-facing surface for the session_journal split was missing — only
CHANGELOG and version bump landed in the prior P1 commits. End users
would not have learned `ccmem promote` exists; contributors would not
have found the rationale for splitting trust off the persistence gate.
- README (EN/ZH): replace v0.2.6 caveat with v0.3.0 trust split notice;
Features adds "Trust two-tier" row; new CLI Commands section covers
ccmem promote / reject; API table adds /journal/pending|promote|reject;
Project Structure adds src/cli/journal.ts; test count 475/32 → 562/37
- tutorial (EN/ZH): Hooks section explains journal trust; Verifying-fires
section now counts session_journal; Scenario 4 walks through promote
and reject with rationale link to issue #21
- architecture (EN/ZH): Engine 2 documents sweepJournal; Engine 3
documents new harvest target; new "Promote and reject paths" plus
"Trust grade vs persistence gate" sections explain the 0.3.0 redesign;
Trade-offs adds two new rows; Where to Look adds 4 file pointers
562 tests still passing; no source changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
> The harvester's knowledge-bearing scorer (introduced in v0.2.6) was corpus-validated against Mandarin Chinese sessions only. Each of the 5 signal categories ships with 1–3 anchor patterns per language as plan-time scaffolding. **English-language sessions may see a higher skip rate than expected** — the harvester will write fewer new memories until pattern coverage expands.
16
+
> The SessionEnd hook now writes to a low-trust `session_journal` table instead of `memories`. Journal entries are scored, surfaced via `/health` (`journalPendingCount`), and **do not appear in `recall_query` / `recall_context` results** until you run `ccmem promote <id>`. Manual `recall_save` is unchanged — it still writes directly to high-trust `memories`.
17
17
>
18
-
> If you observe English outcome sessions failing to harvest, please contribute a redacted excerpt at [issue #23](https://github.com/tznthou/ccRecall/issues/23) — that's the corpus we need to expand coverage deliberately rather than by guesswork.
18
+
> The rule scorer is no longer on the persistence gate; it informs trust grade and promotion priority instead. Background reasoning at [issue #21](https://github.com/tznthou/ccRecall/issues/21).
19
19
>
20
-
> Memories accumulated pre-v0.2.6 are preserved; a separate cleanup release will purge legacy noise after a 7-day observation window.
20
+
> Pre-0.3.0 memories stay queryable as-is. The v22 schema migration runs automatically on first daemon startup; existing rows are not touched. New harvest goes to journal from now on.
21
21
22
22
---
23
23
@@ -43,6 +43,7 @@ ccRecall is the "memory" counterpart to [ccRewind](https://github.com/tznthou/cc
43
43
|**Incremental indexing**| Only re-indexes sessions that changed (mtime diffing), handles resumed sessions via UUID dedup |
44
44
|**Metacognition**|`knowledge_map` aggregates topic mentions from sessions + memories. Depth derived from mention count (shallow / medium / deep). Exposed via `/metacognition/check` and MCP `recall_context`|
45
45
|**Forgetting curve**| Memories compress over time: raw → summary → one-liner → deleted. Confidence decays on unused memories. Background maintenance tick runs every 5 min |
46
+
|**Trust two-tier** (v0.3.0) | Hooks write to a low-trust `session_journal` (reviewable, never recalled directly); manual `recall_save` writes high-trust `memories`. Promote candidates with `ccmem promote <id>`; rejected entries auto-clear after 7 days |
46
47
|**Watch mode**| chokidar-based JSONL watcher picks up new sessions within 2 s; periodic 10 min full-resync covers missed filesystem events |
47
48
|**Rescue reindex**|`/session/end` retries a reindex on cache miss — no fresh-session race between the hook and the daemon |
48
49
|**Auto-start (macOS)**|`ccmem install-daemon` registers a LaunchAgent so the service stays up across reboots |
@@ -88,7 +89,7 @@ flowchart TB
88
89
| FTS5 | Full-text search | Built into SQLite, trigram tokenizer with LIKE fallback for short CJK / mixed-script queries |
89
90
| Native `http`| HTTP server | No Express — minimal surface, localhost only |
90
91
| chokidar | Filesystem watcher | Cross-platform JSONL change detection with 2 s debounce + single-flight |
|`/health`| GET | Service health + DB stats + integrity check status | Live |
136
-
|`/memory/query?q=...&limit=...&project=...`| GET | FTS5 search across memories with optional project filter | Live |
136
+
|`/health`| GET | Service health + DB stats + integrity check status + `journalPendingCount` (since v0.3.0) | Live |
137
+
|`/memory/query?q=...&limit=...&project=...`| GET | FTS5 search across memories with optional project filter (journal entries excluded by design) | Live |
137
138
|`/memory/save`| POST | Save a memory entry (origin-checked) | Live |
138
-
|`/session/end`| POST | Harvest a finished session's summary into a memory (idempotent) | Live |
139
+
|`/session/end`| POST | Harvest a finished session into `session_journal` (idempotent; was `memories` pre-0.3.0) | Live |
140
+
|`/journal/pending`| GET | List journal entries awaiting promotion review | Live (v0.3.0) |
141
+
|`/journal/promote`| POST | Atomically promote a journal entry into `memories`| Live (v0.3.0) |
142
+
|`/journal/reject`| POST | Soft-delete a journal entry (cleared after 7-day TTL by decay sweep) | Live (v0.3.0) |
139
143
|`/memory/context?session_id=...`| GET | Session context lookup | Stub |
140
144
|`/metacognition/check?projectId=...[&topic=...]`| GET | Knowledge map: summary (top/recent/stale topics + counts) or topic detail (memories + related topics) | Live |
141
145
|`/session/checkpoint`| POST | Mid-session snapshot into dedicated `session_checkpoints` table (not harvested as memory) | Live |
@@ -175,6 +179,40 @@ See [hooks/README.md](hooks/README.md) for SessionStart / SessionEnd hook instal
175
179
176
180
---
177
181
182
+
## CLI Commands
183
+
184
+
`@tznthou/ccrecall` ships two binaries:
185
+
186
+
-**`ccmem`** — daemon launcher + admin commands
187
+
-**`ccmem-mcp`** — MCP server (registered with Claude Code via `claude mcp add`)
188
+
189
+
Daemon and hook lifecycle (macOS):
190
+
191
+
| Command | Purpose |
192
+
|---------|---------|
193
+
|`ccmem`| Run the daemon in foreground |
194
+
|`ccmem install-daemon`| Register a LaunchAgent (auto-start at login) |
195
+
|`ccmem uninstall-daemon`| Stop and remove the LaunchAgent |
196
+
|`ccmem install-hooks`| Merge SessionStart / SessionEnd entries into `~/.claude/settings.json`|
ccRecall lives alongside Claude Code's built-in auto memory (`~/.claude/projects/*/memory/`). They're complementary — use them for different things.
@@ -192,6 +230,8 @@ ccRecall lives alongside Claude Code's built-in auto memory (`~/.claude/projects
192
230
193
231
ccRecall's value is the long tail that auto memory can't cover (nobody hand-curates 500 sessions of notes). If Claude defaults to both, auto memory wins because it's already loaded and curated. ccRecall earns its keep when the curated index misses.
194
232
233
+
**Within ccRecall there's now a second trust split** (since v0.3.0). The SessionEnd hook writes to a low-trust `session_journal` table that `recall_query` does **not** read. Promote a candidate to high-trust `memories` with `ccmem promote <id>` to make it queryable. Manual `recall_save` skips the journal entirely — it writes straight to memories. The point is to let the harvester record broadly while keeping recall results clean.
0 commit comments