Skip to content

Commit bba138a

Browse files
cdeustclaude
andauthored
docs(readme): predictions and calibration, one store for Claude Code and Codex (#603)
* docs(readme): predictions and calibration, one store for Claude Code and Codex The README described what Cortex remembers and never that it can record what it expected (#597, ADR-1076): a section under "Keep context useful" shows predict, resolve_prediction and calibration with their real return shapes and says what the Brier score means against the 0.25 of a constant 0.5 forecast. The host table gains the row, and the Codex paragraph says the plugin reads the same saved backend selection as the Claude launcher (#600). The unreleased changelog had two "### Added" headings; one now. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs(readme): one column per host in the capability table Codex was folded into "local stdio hosts" although its plugin starts the server with --profile lean (ten named tools, no hooks) while a direct codex mcp add gets the full surface. The table now has a column for each, says which tools lean lacks (predictions, wiki writes, ingestion), where the shared backend selection lives (#600), and which worktree directory doctor checks per host. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs(readme): the calibration band the code can return, and the release hedge for Codex BAND_EDGES steps by 0.2, so the illustrative reliability row shows [0.6, 0.8]. The Codex paragraph names CORTEX_BACKEND between the two variables it already named and says the shared backend selection reaches the plugin with the release after 4.22.0, since the plugin launches the published package. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs(readme): the worktree row states the convention, not a doctor check The doctor check for worktree locations is PR #602, not merged. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs(readme): the lean profile's real reason, and each worktree cell sourced to what names it ADR-0693 records why the Codex plugin starts lean: the full surface is the largest fixed token cost a session pays, not a startup-time limit. The worktree row cites docs/agent-guidance.md for the Claude Code directory only; the Codex directory is observed behaviour that #601 gitignored. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH --------- Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent 9656fc4 commit bba138a

2 files changed

Lines changed: 54 additions & 15 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,6 @@ adheres to [Semantic Versioning](https://semver.org/).
4141
(ADR-1076). The table lives on both backends. Standalone tool count 54 to
4242
57, 60 with both upstream integrations.
4343

44-
### Added
45-
4644
- **The Path B draft tools are exposed over MCP (#579).** `wiki_get_draft`
4745
and `wiki_refine_draft` had existed as handlers since ADR-0467 without ever
4846
being registered, so no client could call them and `wiki_get_draft`'s own

‎README.md‎

Lines changed: 54 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,35 @@ remember({ content: "...", supersedes_id: 4360411 })
154154
// → { action: "superseded", memory_id: 4360412, superseded_id: 4360411 }
155155
```
156156

157+
### Whether it was right
158+
159+
A memory records what happened. A prediction records what was expected before the outcome
160+
was known, so that Cortex can later find out it was wrong. `predict` writes a falsifiable
161+
claim with the confidence held at the time; `resolve_prediction` settles it against an
162+
observation the caller supplies, naming the verdict, the kind of source that decided it and
163+
a reference to that source; `calibration` scores the resolved set.
164+
165+
```js
166+
predict({ claim: "The p90 of the SQLite job is under 6 minutes",
167+
prediction: "a 20-minute budget leaves headroom", test: "21 attempts of 2026-09-16",
168+
confidence: 0.8 })
169+
// → { prediction_id: 12, status: "open" }
170+
resolve_prediction({ prediction_id: 12, verdict: "confirmed",
171+
observed: "p90 348 s over 18 successes",
172+
source_kind: "ci", source_ref: "cdeust/Cortex actions, 2026-09-16" })
173+
// → { prediction_id: 12, verdict: "confirmed", resolved: true }
174+
calibration()
175+
// → { scored: 9, brier: 0.11, uninformative_brier: 0.25, confirmed: 7, refuted: 2,
176+
// reliability: [{ band: [0.6, 0.8], resolved: 4, mean_confidence: 0.78,
177+
// observed_frequency: 0.75 }, ...] }
178+
```
179+
180+
`brier` is the mean squared distance between confidence and outcome; 0.25 is what a constant
181+
0.5 forecast earns, so a score above it means the confidences carried less information than
182+
saying nothing. Cortex never fetches the evidence itself: the verdict, the observation and
183+
the source reference come from the caller, which is what lets the same contract hold in any
184+
repository and under any review convention.
185+
157186
### What fades
158187

159188
Memories carry heat that decays unless replay reinforces them, and episodic traces can consolidate
@@ -247,18 +276,26 @@ banners, auto-recall, auto-capture, checkpoints and every memory tool work on bo
247276

248277
The server is host-agnostic. Any host that can launch a stdio process gets the full tool
249278
surface on the default SQLite store. What is not portable are the nine lifecycle hooks, which
250-
are Claude Code plugin machinery; the server never imports or requires them at startup.
251-
252-
| Capability | Claude Code plugin | Local stdio hosts (Gemini CLI, Codex CLI, ChatGPT desktop, Cursor, Windsurf, VS Code, Agents SDK) | ChatGPT web |
253-
|---|---|---|---|
254-
| All 57 memory tools (`remember`, `recall`, wiki, navigation, consolidation, triggers, rules) | ✅ | ✅ | ❌ no remote HTTPS endpoint is shipped |
255-
| SQLite default store / PostgreSQL opt-in | ✅ | ✅ | ❌ would need a remote deployment and a per-user storage and auth model |
256-
| Auto-capture of significant tool output | ✅ PostToolUse hook | ❌ store explicitly with `remember` | ❌ |
257-
| Session-start context injection | ✅ SessionStart hook | ❌ call `recall` yourself | ❌ |
258-
| Per-prompt auto-recall | ✅ | ❌ | ❌ |
259-
| Compaction checkpoints | ✅ | ❌ | ❌ |
260-
| Autonomous wiki cycle | ✅ | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
261-
| Cognitive profiling (`query_methodology`) | ✅ | ⚠️ profiles are mined from Claude Code session logs under `~/.claude/`; without them the profile is empty | ❌ |
279+
are Claude Code plugin machinery; the server never imports or requires them at startup. The
280+
Codex plugin deliberately starts the server with `--profile lean`: the full tool surface is the
281+
largest fixed token cost a session pays before the user types anything (ADR-0693, issue #177),
282+
and the plugin keeps that cost to ten tools; the direct registration below gives Codex the full
283+
surface.
284+
285+
| Capability | Claude Code plugin | Codex plugin (`hypermnesia-mcp-codex`) | Codex `codex mcp add`, Gemini CLI, Cursor, Windsurf, VS Code, Agents SDK | ChatGPT web |
286+
|---|---|---|---|---|
287+
| Tool surface | all 57 tools | the 10-tool `lean` profile: `remember`, `recall`, `unified_search`, `recall_hierarchical`, `consolidate`, `memory_stats`, `check_setup`, `wiki_read`, `wiki_list`, `query_methodology` | all 57 tools (`full` is the default profile) | ❌ no remote HTTPS endpoint is shipped |
288+
| SQLite default store / PostgreSQL opt-in | ✅ | ✅ | ✅ | ❌ would need a remote deployment and a per-user storage and auth model |
289+
| One store for Claude Code and Codex | ✅ writes the selection to `~/.claude/methodology/backend.json` | ✅ reads that selection at startup (#600, from the release after 4.22.0) | ✅ same rule for any direct startup sharing the configuration root | ❌ |
290+
| Predictions and calibration (`predict`, `resolve_prediction`, `calibration`) | ✅ | ❌ not in `lean`; use the direct registration | ✅ | ❌ |
291+
| Wiki writes, ADRs, triggers, rules, codebase ingestion | ✅ | ❌ not in `lean` | ✅ | ❌ |
292+
| Auto-capture of significant tool output | ✅ PostToolUse hook | ❌ store explicitly with `remember` | ❌ same | ❌ |
293+
| Session-start context injection | ✅ SessionStart hook | ❌ call `recall` yourself | ❌ same | ❌ |
294+
| Per-prompt auto-recall | ✅ | ❌ | ❌ | ❌ |
295+
| Compaction checkpoints | ✅ | ❌ | ❌ | ❌ |
296+
| Autonomous wiki cycle | ✅ | ❌ `consolidate` by hand; `curate_wiki` needs the full profile | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
297+
| Cognitive profiling (`query_methodology`) | ✅ | ⚠️ profiles are mined from Claude Code session logs under `~/.claude/`; without them the profile is empty | ⚠️ same | ❌ |
298+
| Worktree directory | `.claude/worktrees/<name>/`, the location `docs/agent-guidance.md` names | `.Codex/worktrees/<name>/`, where Codex puts its own; ignored at the repository root since #601 | n/a | n/a |
262299

263300
On Claude Code memory is ambient: hooks capture and inject automatically. On every other host
264301
memory is tool-driven: the agent stores and retrieves when instructed, and nothing happens
@@ -277,7 +314,11 @@ uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp
277314
gemini extensions install https://github.com/cdeust/Cortex
278315
```
279316

280-
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. Pre-install
317+
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. It reads the
318+
same saved backend selection as the Claude Code launcher (`~/.claude/methodology/backend.json`),
319+
so both hosts write to one store (from the release after 4.22.0; the plugin launches the
320+
published package); explicit `CORTEX_MEMORY_STORE_BACKEND`, `CORTEX_BACKEND` or a database URL
321+
still wins. Pre-install
281322
the package once so the plugin's first `uvx` handshake reuses the local uv cache instead of
282323
spending its startup budget downloading a Python environment:
283324

0 commit comments

Comments
 (0)