Skip to content

Commit 40263d6

Browse files
cdeustclaude
andcommitted
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
1 parent 9656fc4 commit 40263d6

2 files changed

Lines changed: 34 additions & 3 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: 34 additions & 1 deletion
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.7, 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
@@ -258,6 +287,7 @@ are Claude Code plugin machinery; the server never imports or requires them at s
258287
| Per-prompt auto-recall | ✅ | ❌ | ❌ |
259288
| Compaction checkpoints | ✅ | ❌ | ❌ |
260289
| Autonomous wiki cycle | ✅ | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
290+
| Predictions and calibration (`predict`, `resolve_prediction`, `calibration`) | ✅ | ✅ | ❌ |
261291
| Cognitive profiling (`query_methodology`) | ✅ | ⚠️ profiles are mined from Claude Code session logs under `~/.claude/`; without them the profile is empty | ❌ |
262292

263293
On Claude Code memory is ambient: hooks capture and inject automatically. On every other host
@@ -277,7 +307,10 @@ uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp
277307
gemini extensions install https://github.com/cdeust/Cortex
278308
```
279309

280-
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. Pre-install
310+
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. It reads the
311+
same saved backend selection as the Claude Code launcher (`~/.claude/methodology/backend.json`),
312+
so both hosts write to one store; explicit `CORTEX_MEMORY_STORE_BACKEND` or a database URL
313+
still wins. Pre-install
281314
the package once so the plugin's first `uvx` handshake reuses the local uv cache instead of
282315
spending its startup budget downloading a Python environment:
283316

0 commit comments

Comments
 (0)