Skip to content

Commit a9aa9e7

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 c4c42bf commit a9aa9e7

84 files changed

Lines changed: 7084 additions & 275 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 & 11 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
@@ -1534,22 +1534,6 @@
15341534
}
15351535
},
15361536
"memory": {
1537-
"default": {
1538-
"enabled": true,
1539-
"injection_budget_tokens": 4000,
1540-
"auto_promote": true,
1541-
"retrieval_count_promotion_threshold": 3,
1542-
"auto_search": {
1543-
"enabled": true,
1544-
"score_threshold": 0.6,
1545-
"min_prompt_chars": 20
1546-
},
1547-
"git_commit_indexing": {
1548-
"enabled": false,
1549-
"since_days": 365,
1550-
"max_commits": 2000
1551-
}
1552-
},
15531537
"description": "Cross-session memory configuration",
15541538
"type": "object",
15551539
"properties": {
@@ -1635,6 +1619,141 @@
16351619
"maximum": 20000
16361620
}
16371621
}
1622+
},
1623+
"external": {
1624+
"description": "External long-term memory backend (tee). USER config only.",
1625+
"type": "object",
1626+
"properties": {
1627+
"provider": {
1628+
"default": "off",
1629+
"description": "External memory backend. 'hindsight' tees memory creations to a Hindsight service; 'off' disables (default). SECURITY: this whole block only honors USER-level config.",
1630+
"type": "string",
1631+
"enum": [
1632+
"hindsight",
1633+
"off"
1634+
]
1635+
},
1636+
"endpoint": {
1637+
"description": "Backend base URL (e.g. http://10.0.0.1:8889). Required when provider is hindsight.",
1638+
"type": "string"
1639+
},
1640+
"api_key": {
1641+
"description": "Bearer token for the backend (optional).",
1642+
"type": "string"
1643+
},
1644+
"project_bank": {
1645+
"default": "mc-{name}-{id8}",
1646+
"description": "Bank name template for project-scoped items. Placeholders: {name}=project basename, {id8}=first 8 chars of the project identity hash.",
1647+
"type": "string"
1648+
},
1649+
"main_bank": {
1650+
"description": "Bank for user- and global-scoped items. Required when provider is hindsight. Assumed to pre-exist; never created or modified.",
1651+
"type": "string"
1652+
},
1653+
"retain_sources": {
1654+
"default": [
1655+
"historian",
1656+
"agent",
1657+
"dreamer"
1658+
],
1659+
"description": "Which creation points tee: historian promotion, agent ctx_memory writes, dreamer user-memory promotion.",
1660+
"type": "array",
1661+
"items": {
1662+
"type": "string",
1663+
"enum": [
1664+
"historian",
1665+
"agent",
1666+
"dreamer"
1667+
]
1668+
}
1669+
},
1670+
"tags": {
1671+
"default": [],
1672+
"description": "Static tags attached to every retained item.",
1673+
"type": "array",
1674+
"items": {
1675+
"type": "string"
1676+
}
1677+
},
1678+
"recall": {
1679+
"default": {
1680+
"enabled": true,
1681+
"timeout_ms": 3000,
1682+
"max_tokens": 2048,
1683+
"dedup_threshold": 0.85,
1684+
"global_tags": [],
1685+
"global_from_prompt": false,
1686+
"search": true,
1687+
"mental_models": true,
1688+
"profile_mental_models": [
1689+
"user-preferences"
1690+
]
1691+
},
1692+
"description": "Unified read path: session-start recall + ctx_search external source.",
1693+
"type": "object",
1694+
"properties": {
1695+
"enabled": {
1696+
"default": true,
1697+
"description": "Session-start recall from the external backend, merged into the context injection (default: true).",
1698+
"type": "boolean"
1699+
},
1700+
"timeout_ms": {
1701+
"default": 3000,
1702+
"description": "Max wait for recall at the first render of a session (already cache-cold). Late results ride the m[1] delta. (default: 3000)",
1703+
"type": "number",
1704+
"minimum": 500,
1705+
"maximum": 15000
1706+
},
1707+
"max_tokens": {
1708+
"default": 2048,
1709+
"description": "Token budget per recall slice (project / profile / global each). (default: 2048)",
1710+
"type": "number",
1711+
"minimum": 256,
1712+
"maximum": 8192
1713+
},
1714+
"dedup_threshold": {
1715+
"default": 0.85,
1716+
"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)",
1717+
"type": "number",
1718+
"minimum": 0.5,
1719+
"maximum": 0.99
1720+
},
1721+
"global_tags": {
1722+
"default": [],
1723+
"description": "Tag filter for the global (main-bank) recall slice, matched with tags_match 'any' (untagged content INCLUDED). Empty = no filter (full autoRecall replacement).",
1724+
"type": "array",
1725+
"items": {
1726+
"type": "string"
1727+
}
1728+
},
1729+
"global_from_prompt": {
1730+
"default": false,
1731+
"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.",
1732+
"type": "boolean"
1733+
},
1734+
"search": {
1735+
"default": true,
1736+
"description": "Expose the ctx_search 'external' source (project + main bank). (default: true)",
1737+
"type": "boolean"
1738+
},
1739+
"mental_models": {
1740+
"default": true,
1741+
"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)",
1742+
"type": "boolean"
1743+
},
1744+
"profile_mental_models": {
1745+
"default": [
1746+
"user-preferences"
1747+
],
1748+
"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.",
1749+
"type": "array",
1750+
"items": {
1751+
"type": "string"
1752+
}
1753+
}
1754+
}
1755+
}
1756+
}
16381757
}
16391758
}
16401759
},

‎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/docs/src/content/docs/reference/configuration.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,24 @@ Durable project memory, semantic search, and recall features.
128128
| `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. |
129129
| `memory.git_commit_indexing.since_days` | number (7–3650) | `365` | Days of HEAD history to index (min: 7, max: 3650, default: 365) |
130130
| `memory.git_commit_indexing.max_commits` | number (100–20000) | `2000` | Max commits kept per project; oldest evicted (min: 100, max: 20000, default: 2000) |
131+
| `memory.external` | object | — | External long-term memory backend (tee). USER config only. |
132+
| `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. |
133+
| `memory.external.endpoint` | string | — | Backend base URL (e.g. http://10.0.0.1:8889). Required when provider is hindsight. |
134+
| `memory.external.api_key` | string | — | Bearer token for the backend (optional). |
135+
| `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. |
136+
| `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. |
137+
| `memory.external.retain_sources` | `"historian"` \\| `"agent"` \\| `"dreamer"`[] | `["historian","agent","dreamer"]` | Which creation points tee: historian promotion, agent ctx_memory writes, dreamer user-memory promotion. |
138+
| `memory.external.tags` | string[] | `[]` | Static tags attached to every retained item. |
139+
| `memory.external.recall` | object | — | Unified read path: session-start recall + ctx_search external source. |
140+
| `memory.external.recall.enabled` | boolean | `true` | Session-start recall from the external backend, merged into the context injection (default: true). |
141+
| `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) |
142+
| `memory.external.recall.max_tokens` | number (256–8192) | `2048` | Token budget per recall slice (project / profile / global each). (default: 2048) |
143+
| `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) |
144+
| `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). |
145+
| `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. |
146+
| `memory.external.recall.search` | boolean | `true` | Expose the ctx_search 'external' source (project + main bank). (default: true) |
147+
| `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) |
148+
| `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. |
131149
| `embedding` | object | — | Embedding provider configuration |
132150
| `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. |
133151
| `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)