Skip to content

Commit 344afd2

Browse files
author
Tehan
committed
feat(external-memory): Hindsight backend tee and unified external recall
Vertical sync of durable knowledge to an external Hindsight memory backend, orthogonal to upstream's local workspace sharing: each project keeps its own bank and sharing stays local-only, so the two axes never diverge. - Write path: historian fact promotion and `ctx_memory` mutations tee to the backend post-commit (update/archive/merge/verify all propagate). - Read path: three-slice recall at session start (project bank, user profile via scope:user, global via recall tags), rendered as an <external-memory> block with the profile slice merged into <user-profile>. - Cache safety: the recall snapshot rides m[1] as a delta and is explicitly subtracted from pressure-refold accounting, so it can never trigger an m[0] hard fold. `externalRecallHash` appears 0x inside `mustMaterialize` -- an invariant re-verified on every upstream rebase. - `ctx_search` gains an explicit "external" source (opt-in, 5s abort). - Full OpenCode + Pi parity. Deliberately never proposed upstream: it couples the plugin to an external service, and upstream is actively simplifying the memory system (see cortexkit#335). This commit also carries the union resolutions that let both fork features coexist -- shared fork migration lane, merged status/RPC/TUI surfaces, and the combined prompt-surface budget.
1 parent 5997771 commit 344afd2

86 files changed

Lines changed: 7101 additions & 281 deletions

File tree

Some content is hidden

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

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@ Because it runs during idle time, the dreamer pairs well with local models, even
262262

263263
*The right memory at the right moment.* Every turn, active project memories and the compacted session history are injected automatically and cache-stably. On demand, the agent reaches for:
264264

265-
- **`ctx_search`**: one query across project **memories**, raw **conversation** history, indexed **git commits**, parked **notes**, and promoted **primers**. Semantic embeddings with full-text fallback.
265+
- **`ctx_search`**: one query across project **memories**, raw **conversation** history, indexed **git commits**, parked **notes**, promoted **primers**, and (opt-in) the long-term **external** memory backend. Semantic embeddings with full-text fallback.
266266

267267
```
268268
ctx_search(query="why did we pick event sourcing for orders")
@@ -274,6 +274,8 @@ Because it runs during idle time, the dreamer pairs well with local models, even
274274

275275
Recall works **across sessions** (a new session inherits everything) and **across harnesses** (write a memory in OpenCode, retrieve it in Pi or OMP).
276276

277+
> **Long-term memory** *(opt-in, off by default)* tees curated writes (historian promotions, `ctx_memory` writes, dreamer user-memory promotions) to a Hindsight backend and recalls them BACK once per session as a `<external-memory>` block — across sessions, across harnesses, and across projects for the global slice. Same `ctx_search` "external" source (explicit-only, never on the auto-search hot path). User-config-only; a repo cannot redirect the endpoint. Configure under `memory.external`; see [CONFIGURATION.md](./CONFIGURATION.md#memoryexternal).
278+
>
277279
> **Auto search hints** *(on by default)* run a background `ctx_search` each turn and whisper a "vague recall" when something relevant exists — like almost remembering a note you took. It appends only compact fragments, never full content; set `memory.auto_search.enabled: false` to turn it off. **Git commit indexing** *(opt-in)* makes your project history semantically searchable as an additional `ctx_search` source — enable with `memory.git_commit_indexing.enabled: true`.
278280
279281
### Agent tools at a glance
@@ -282,7 +284,7 @@ Recall works **across sessions** (a new session inherits everything) and **acros
282284
|------|-------|-------------|
283285
| `ctx_reduce` | Context | Queue stale tagged content for removal, cache-aware |
284286
| `ctx_memory` | Capture | Write or delete durable cross-session memories |
285-
| `ctx_search` | Recall | Search memories, conversation history, git commits, notes, and primers |
287+
| `ctx_search` | Recall | Search memories, conversation history, git commits, notes, primers, and external long-term memory |
286288
| `ctx_expand` | Recall | Decompress a history range back to the transcript |
287289
| `ctx_note` | Recall | Deferred intentions and dreamer-evaluated smart notes |
288290
| `ctx_skill_note` | Recall | Write back a per-skill note (gotcha/discovery/fix/workflow) for future loads |

‎STRUCTURE.md‎

Lines changed: 12 additions & 13 deletions
Large diffs are not rendered by default.

‎assets/magic-context.schema.json‎

Lines changed: 135 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1917,22 +1917,6 @@
19171917
}
19181918
},
19191919
"memory": {
1920-
"default": {
1921-
"enabled": true,
1922-
"injection_budget_tokens": 4000,
1923-
"auto_promote": true,
1924-
"retrieval_count_promotion_threshold": 3,
1925-
"auto_search": {
1926-
"enabled": true,
1927-
"score_threshold": 0.6,
1928-
"min_prompt_chars": 20
1929-
},
1930-
"git_commit_indexing": {
1931-
"enabled": false,
1932-
"since_days": 365,
1933-
"max_commits": 2000
1934-
}
1935-
},
19361920
"description": "Cross-session memory configuration",
19371921
"type": "object",
19381922
"properties": {
@@ -2018,6 +2002,141 @@
20182002
"maximum": 20000
20192003
}
20202004
}
2005+
},
2006+
"external": {
2007+
"description": "External long-term memory backend (tee). USER config only.",
2008+
"type": "object",
2009+
"properties": {
2010+
"provider": {
2011+
"default": "off",
2012+
"description": "External memory backend. 'hindsight' tees memory creations to a Hindsight service; 'off' disables (default). SECURITY: this whole block only honors USER-level config.",
2013+
"type": "string",
2014+
"enum": [
2015+
"hindsight",
2016+
"off"
2017+
]
2018+
},
2019+
"endpoint": {
2020+
"description": "Backend base URL (e.g. http://10.0.0.1:8889). Required when provider is hindsight.",
2021+
"type": "string"
2022+
},
2023+
"api_key": {
2024+
"description": "Bearer token for the backend (optional).",
2025+
"type": "string"
2026+
},
2027+
"project_bank": {
2028+
"default": "mc-{name}-{id8}",
2029+
"description": "Bank name template for project-scoped items. Placeholders: {name}=project basename, {id8}=first 8 chars of the project identity hash.",
2030+
"type": "string"
2031+
},
2032+
"main_bank": {
2033+
"description": "Bank for user- and global-scoped items. Required when provider is hindsight. Assumed to pre-exist; never created or modified.",
2034+
"type": "string"
2035+
},
2036+
"retain_sources": {
2037+
"default": [
2038+
"historian",
2039+
"agent",
2040+
"dreamer"
2041+
],
2042+
"description": "Which creation points tee: historian promotion, agent ctx_memory writes, dreamer user-memory promotion.",
2043+
"type": "array",
2044+
"items": {
2045+
"type": "string",
2046+
"enum": [
2047+
"historian",
2048+
"agent",
2049+
"dreamer"
2050+
]
2051+
}
2052+
},
2053+
"tags": {
2054+
"default": [],
2055+
"description": "Static tags attached to every retained item.",
2056+
"type": "array",
2057+
"items": {
2058+
"type": "string"
2059+
}
2060+
},
2061+
"recall": {
2062+
"default": {
2063+
"enabled": true,
2064+
"timeout_ms": 3000,
2065+
"max_tokens": 2048,
2066+
"dedup_threshold": 0.85,
2067+
"global_tags": [],
2068+
"global_from_prompt": false,
2069+
"search": true,
2070+
"mental_models": true,
2071+
"profile_mental_models": [
2072+
"user-preferences"
2073+
]
2074+
},
2075+
"description": "Unified read path: session-start recall + ctx_search external source.",
2076+
"type": "object",
2077+
"properties": {
2078+
"enabled": {
2079+
"default": true,
2080+
"description": "Session-start recall from the external backend, merged into the context injection (default: true).",
2081+
"type": "boolean"
2082+
},
2083+
"timeout_ms": {
2084+
"default": 3000,
2085+
"description": "Max wait for recall at the first render of a session (already cache-cold). Late results ride the m[1] delta. (default: 3000)",
2086+
"type": "number",
2087+
"minimum": 500,
2088+
"maximum": 15000
2089+
},
2090+
"max_tokens": {
2091+
"default": 2048,
2092+
"description": "Token budget per recall slice (project / profile / global each). (default: 2048)",
2093+
"type": "number",
2094+
"minimum": 256,
2095+
"maximum": 8192
2096+
},
2097+
"dedup_threshold": {
2098+
"default": 0.85,
2099+
"description": "Cosine similarity above which a recalled item is dropped as a duplicate of a local memory. Hash-only fallback when embeddings are unavailable. (default: 0.85)",
2100+
"type": "number",
2101+
"minimum": 0.5,
2102+
"maximum": 0.99
2103+
},
2104+
"global_tags": {
2105+
"default": [],
2106+
"description": "Tag filter for the global (main-bank) recall slice, matched with tags_match 'any' (untagged content INCLUDED). Empty = no filter (full autoRecall replacement).",
2107+
"type": "array",
2108+
"items": {
2109+
"type": "string"
2110+
}
2111+
},
2112+
"global_from_prompt": {
2113+
"default": false,
2114+
"description": "Include an excerpt of the session's FIRST user prompt in the global-slice recall query (the project name is always included). The first prompt is fixed for the session, so the query — and the frozen recall snapshot — stays deterministic. Default false: pure template query.",
2115+
"type": "boolean"
2116+
},
2117+
"search": {
2118+
"default": true,
2119+
"description": "Expose the ctx_search 'external' source (project + main bank). (default: true)",
2120+
"type": "boolean"
2121+
},
2122+
"mental_models": {
2123+
"default": true,
2124+
"description": "Use Hindsight mental models as the fast path for the project/profile recall slices (single GET, server-refreshed), falling back to recall when absent/empty. (default: true)",
2125+
"type": "boolean"
2126+
},
2127+
"profile_mental_models": {
2128+
"default": [
2129+
"user-preferences"
2130+
],
2131+
"description": "Main-bank mental-model names (case-insensitive) used for the profile slice. The main bank is never modified by the plugin — create these manually.",
2132+
"type": "array",
2133+
"items": {
2134+
"type": "string"
2135+
}
2136+
}
2137+
}
2138+
}
2139+
}
20212140
}
20222141
}
20232142
},

‎docs/specs/prompt-surface/budget-fixture.json‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -90,12 +90,12 @@
9090
"tokens": 391
9191
},
9292
"ctx_memory": {
93-
"chars": 980,
94-
"tokens": 234
93+
"chars": 1171,
94+
"tokens": 278
9595
},
9696
"ctx_search": {
97-
"chars": 1253,
98-
"tokens": 309
97+
"chars": 1546,
98+
"tokens": 371
9999
},
100100
"ctx_skill_note": {
101101
"chars": 300,
@@ -120,12 +120,12 @@
120120
"tokens": 317
121121
},
122122
"ctx_memory": {
123-
"chars": 840,
124-
"tokens": 201
123+
"chars": 1247,
124+
"tokens": 291
125125
},
126126
"ctx_search": {
127-
"chars": 777,
128-
"tokens": 184
127+
"chars": 847,
128+
"tokens": 200
129129
},
130130
"ctx_skill_note": {
131131
"chars": 690,
@@ -135,12 +135,12 @@
135135
"chars": 396,
136136
"tokens": 95
137137
},
138-
"totalTokens": 1173
138+
"totalTokens": 1279
139139
},
140-
"builtInProviderVisibleTotal": 5260
140+
"builtInProviderVisibleTotal": 5472
141141
},
142-
"mutableProseBaseline": 4087,
143-
"integerLightCeiling": 2043,
142+
"mutableProseBaseline": 4193,
143+
"integerLightCeiling": 2096,
144144
"includedSurfaces": [
145145
"The primary built-in full guidance section for the exact feature variant above.",
146146
"One built-in full top-level description for every active ctx_* tool above.",
@@ -167,5 +167,5 @@
167167
"packages/plugin/src/tools/ctx-search/constants.ts#CTX_SEARCH_DESCRIPTION"
168168
]
169169
},
170-
"downstreamNote": "DOWNSTREAM MEASUREMENT, NOT A RATIFICATION. This fork adds ctx_skill_note and ctx_skill_recall (skill-memory), so the measured surface is larger than the upstream s2-r1 numbers. Values here are re-measured from source with the same tokenizer identity and the same floor(0.50 * mutableProseBaseline) policy; only the measurements moved, never the policy, the tokenizer, the primary variant, or the inclusion/exclusion lists. Upstream baseline for reference: mutableProseBaseline 3650, integerLightCeiling 1825, builtInProviderVisibleTotal 4560, 5 active tools. The ceiling is a derived consequence of the larger surface, not a request to relax the budget -- ratifying the increase is upstream's call."
170+
"downstreamNote": "DOWNSTREAM MEASUREMENT, NOT A RATIFICATION. This is the union tree: it carries BOTH downstream features, so its surface is larger than either feature branch alone. skill-memory adds two tools (ctx_skill_note, ctx_skill_recall) plus their guidance prose; external-memory widens two existing tools (ctx_memory gains scope:\"global\", ctx_search gains the \"external\" source) without adding any. Re-measured from source on this tree -- neither parent branch's fixture is correct here. Same tokenizer identity and the same floor(0.50 * mutableProseBaseline) policy; only measurements moved, never the policy, tokenizer, primary variant, or inclusion/exclusion lists. Upstream baseline for reference: mutableProseBaseline 3650, integerLightCeiling 1825, builtInProviderVisibleTotal 4560, 5 active tools. Per-feature numbers live on the respective PR branches; ratifying any increase is upstream's call."
171171
}

‎packages/dashboard/src/components/ConfigEditor/config-field-coverage.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,9 @@ export const OMITTED_BY_DESIGN: Readonly<Record<string, string>> = {
8080
...agentOverrideTailOmissions(),
8181
profile:
8282
"per-repository model-profile selector; deferred until the Alfonso Desktop profile editor is available",
83+
// Fork-only surface. The object prefix covers every child leaf.
84+
"memory.external":
85+
"fork-only external memory backend (Hindsight); user-tier only by design \u2014 project configs are stripped of it in project-security.ts, and the endpoint/api_key pair is deliberately not editable from the dashboard",
8386
profiles:
8487
"user-owned model-profile definitions; deferred until the Alfonso Desktop profile editor is available",
8588
"sidekick.system_prompt": "free-form prompt override; raw JSONC",

‎packages/docs/src/content/docs/reference/configuration.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,24 @@ Durable project memory, semantic search, and recall features.
137137
| `memory.git_commit_indexing.enabled` | boolean | `false` | Index HEAD git commits for ctx_search (git_commit source). Graduated from experimental.git_commit_indexing; opt-in, default off. Independent of memory.enabled. |
138138
| `memory.git_commit_indexing.since_days` | number (7–3650) | `365` | Days of HEAD history to index (min: 7, max: 3650, default: 365) |
139139
| `memory.git_commit_indexing.max_commits` | number (100–20000) | `2000` | Max commits kept per project; oldest evicted (min: 100, max: 20000, default: 2000) |
140+
| `memory.external` | object | — | External long-term memory backend (tee). USER config only. |
141+
| `memory.external.provider` | `"hindsight"` \\| `"off"` | `"off"` | External memory backend. 'hindsight' tees memory creations to a Hindsight service; 'off' disables (default). SECURITY: this whole block only honors USER-level config. |
142+
| `memory.external.endpoint` | string | — | Backend base URL (e.g. http://10.0.0.1:8889). Required when provider is hindsight. |
143+
| `memory.external.api_key` | string | — | Bearer token for the backend (optional). |
144+
| `memory.external.project_bank` | string | `"mc-{name}-{id8}"` | Bank name template for project-scoped items. Placeholders: {name}=project basename, {id8}=first 8 chars of the project identity hash. |
145+
| `memory.external.main_bank` | string | — | Bank for user- and global-scoped items. Required when provider is hindsight. Assumed to pre-exist; never created or modified. |
146+
| `memory.external.retain_sources` | `"historian"` \\| `"agent"` \\| `"dreamer"`[] | `["historian","agent","dreamer"]` | Which creation points tee: historian promotion, agent ctx_memory writes, dreamer user-memory promotion. |
147+
| `memory.external.tags` | string[] | `[]` | Static tags attached to every retained item. |
148+
| `memory.external.recall` | object | — | Unified read path: session-start recall + ctx_search external source. |
149+
| `memory.external.recall.enabled` | boolean | `true` | Session-start recall from the external backend, merged into the context injection (default: true). |
150+
| `memory.external.recall.timeout_ms` | number (500–15000) | `3000` | Max wait for recall at the first render of a session (already cache-cold). Late results ride the m[1] delta. (default: 3000) |
151+
| `memory.external.recall.max_tokens` | number (256–8192) | `2048` | Token budget per recall slice (project / profile / global each). (default: 2048) |
152+
| `memory.external.recall.dedup_threshold` | number (0.5–0.99) | `0.85` | Cosine similarity above which a recalled item is dropped as a duplicate of a local memory. Hash-only fallback when embeddings are unavailable. (default: 0.85) |
153+
| `memory.external.recall.global_tags` | string[] | `[]` | Tag filter for the global (main-bank) recall slice, matched with tags_match 'any' (untagged content INCLUDED). Empty = no filter (full autoRecall replacement). |
154+
| `memory.external.recall.global_from_prompt` | boolean | `false` | Include an excerpt of the session's FIRST user prompt in the global-slice recall query (the project name is always included). The first prompt is fixed for the session, so the query — and the frozen recall snapshot — stays deterministic. Default false: pure template query. |
155+
| `memory.external.recall.search` | boolean | `true` | Expose the ctx_search 'external' source (project + main bank). (default: true) |
156+
| `memory.external.recall.mental_models` | boolean | `true` | Use Hindsight mental models as the fast path for the project/profile recall slices (single GET, server-refreshed), falling back to recall when absent/empty. (default: true) |
157+
| `memory.external.recall.profile_mental_models` | string[] | `["user-preferences"]` | Main-bank mental-model names (case-insensitive) used for the profile slice. The main bank is never modified by the plugin — create these manually. |
140158
| `embedding` | object | — | Embedding provider configuration |
141159
| `embedding.provider` | `"local"` \\| `"openai-compatible"` \\| `"off"` \\| `"synapse"` | `"local"` | Embedding provider. 'local' uses Xenova/all-MiniLM-L6-v2, 'openai-compatible' requires endpoint and model, 'synapse' uses the certified local Synapse lane with an explicit fallback provider, and 'off' disables embeddings. |
142160
| `embedding.fallback_provider` | `"local"` \\| `"openai-compatible"` \\| `"off"` | — | Fallback provider for the Synapse lane. Required when provider is 'synapse'; local, openai-compatible, and off are valid. |

0 commit comments

Comments
 (0)