| 1 | # Context Engine v2: Instructions, Memory, and Retrieval |
| 2 | |
| 3 | Context Engine v2 gives Reasonix two durable context layers with different |
| 4 | authority: |
| 5 | |
| 6 | - **Standing instructions** define how the agent must work. |
| 7 | - **Background memory** stores facts that may help later but can become stale. |
| 8 | |
| 9 | Keeping those layers separate is the central design rule. A fact should not |
| 10 | silently become a command, and a long-lived rule should not depend on retrieval |
| 11 | finding it at the right moment. |
| 12 | |
| 13 | ## Choose the right layer |
| 14 | |
| 15 | | Put this in | Use it for | Examples | |
| 16 | | --- | --- | --- | |
| 17 | | `AGENTS.md`, `REASONIX.md`, or `CLAUDE.md` | Rules that must be present on every relevant turn | required test commands, repository boundaries, review conventions | |
| 18 | | Project memory | Durable facts that apply only to this workspace | release branch, non-obvious service constraint, project ticket URL | |
| 19 | | Global memory | A fact that should be available in every workspace | a user preference explicitly chosen as global | |
| 20 | | Session history | Original wording, tool output, or a decision that is not yet a stable fact | an error from yesterday, an abandoned approach | |
| 21 | |
| 22 | Keep instruction files short. They are part of the cache-stable prompt prefix, |
| 23 | so every extra paragraph is carried by every turn. Store discoverable facts as |
| 24 | memory instead. |
| 25 | |
| 26 | A minimal project file is usually enough: |
| 27 | |
| 28 | ```markdown |
| 29 | # Build and verify |
| 30 | |
| 31 | - Run `go test ./...` before reporting completion. |
| 32 | - Do not edit generated files under `desktop/frontend/wailsjs/`. |
| 33 | - Keep public API changes backward compatible. |
| 34 | ``` |
| 35 | |
| 36 | In the CLI, `/remember <note>` and `# <note>` directly append a note to the |
| 37 | project instruction document. They are shortcuts for standing guidance, not the |
| 38 | agent's background-fact `remember` tool. |
| 39 | |
| 40 | ## Instruction resolution |
| 41 | |
| 42 | Reasonix recognizes `REASONIX.md`, `AGENTS.md`, and `CLAUDE.md`, plus matching |
| 43 | `.local.md` variants. It first loads user-global instruction files from the |
| 44 | Reasonix home directory. It then walks from the workspace root to the target |
| 45 | path; at each directory it loads the normal files followed by that directory's |
| 46 | `.local.md` files. |
| 47 | |
| 48 | Deeper directories beat broader directories, and a local variant beats normal |
| 49 | files in the same directory. Later entries therefore win when rules conflict. |
| 50 | The current user request remains the highest-authority user instruction. Files |
| 51 | with identical expanded content are deduplicated, preferring the more specific |
| 52 | source. |
| 53 | |
| 54 | An instruction file can import another file with a standalone relative line: |
| 55 | |
| 56 | ```markdown |
| 57 | @docs/agent-testing.md |
| 58 | ``` |
| 59 | |
| 60 | Imports are expanded deterministically, deduplicated, limited to five levels, |
| 61 | and confined to the directory owned by the source instruction file. Absolute |
| 62 | paths, parent escapes, symlink escapes, unreadable imports, and cycles are |
| 63 | rejected and surfaced as diagnostics rather than silently trusted. |
| 64 | |
| 65 | Use the following command to see the actual result: |
| 66 | |
| 67 | ```text |
| 68 | /memory instructions |
| 69 | ``` |
| 70 | |
| 71 | It reports load precedence, scope, target directory, imports, and diagnostics. |
| 72 | The desktop Context Center exposes the same provenance. |
| 73 | |
| 74 | ## Background fact model |
| 75 | |
| 76 | Each fact is a Markdown file with: |
| 77 | |
| 78 | - an immutable `id`; |
| 79 | - a monotonic `revision`; |
| 80 | - `created_at` and `updated_at` timestamps; |
| 81 | - a human-readable name, title, and description; |
| 82 | - an independent `type` and `scope`; |
| 83 | - the Markdown body. |
| 84 | |
| 85 | `type` classifies the content: |
| 86 | |
| 87 | - `user`: user identity or preferences; |
| 88 | - `feedback`: guidance about how to work and why; |
| 89 | - `project`: project goals or constraints not already evident in the repository; |
| 90 | - `reference`: external resources such as URLs or ticket IDs. |
| 91 | |
| 92 | `scope` controls reach: |
| 93 | |
| 94 | - `project` is the safe default; |
| 95 | - `global` must be chosen explicitly. |
| 96 | |
| 97 | Type does not imply scope. Project feedback remains project-local, and a global |
| 98 | reference remains a reference. |
| 99 | |
| 100 | When equivalent project and global facts exist, automatic recall uses the |
| 101 | project fact. Both remain visible in Context Center and `/memory`, with the |
| 102 | override explained instead of deleting or hiding either source. |
| 103 | |
| 104 | For compatibility and first-turn usability, globally scoped `user` and |
| 105 | `feedback` bodies are snapshotted into a lower-priority stable-guidance section |
| 106 | at session start. When an equivalent project fact exists, it suppresses that |
| 107 | global guidance before the stable prefix is built, so project-over-global |
| 108 | precedence does not depend on a later recall match. Other fact bodies remain |
| 109 | retrieval-only until relevant. |
| 110 | |
| 111 | ## Automatic recall |
| 112 | |
| 113 | Before each real user turn, Reasonix searches active facts using the raw user |
| 114 | message. Host-added provider context is not fed back into the query. The selected |
| 115 | facts are appended to that user turn as a bounded, low-authority suffix; they do |
| 116 | not mutate the system prompt or tool schema. |
| 117 | |
| 118 | Recall is conservative: |
| 119 | |
| 120 | - generic turns such as "continue" do not trigger recall; |
| 121 | - distinctive lexical matches are ranked with BM25; |
| 122 | - project facts receive a small relevance preference; |
| 123 | - stale facts are down-ranked, not silently deleted; |
| 124 | - equivalent project facts suppress global fallbacks for that recall; |
| 125 | - global `user` / `feedback` facts already present as stable guidance are not |
| 126 | duplicated by automatic recall; |
| 127 | - at most four facts and 2,400 characters are included by default; |
| 128 | - fact storage paths are omitted, and home-directory prefixes in snippets are |
| 129 | replaced with `<local-home>`. |
| 130 | |
| 131 | Freshness depends on fact type: |
| 132 | |
| 133 | | Type | Fresh | Current | Stale after | |
| 134 | | --- | ---: | ---: | ---: | |
| 135 | | `reference` | 14 days | 45 days | 45 days | |
| 136 | | `project` | 30 days | 180 days | 180 days | |
| 137 | | `user`, `feedback` | 90 days | 365 days | 365 days | |
| 138 | |
| 139 | Freshness is a warning and ranking signal, not a truth claim. Recalled text |
| 140 | explicitly tells the model that it may be wrong and cannot override the current |
| 141 | request or standing instructions. |
| 142 | |
| 143 | Inspect the last decision with: |
| 144 | |
| 145 | ```text |
| 146 | /memory recall |
| 147 | ``` |
| 148 | |
| 149 | The trace includes the query, selected IDs and revisions, scores, match reasons, |
| 150 | freshness, budget use, omitted count, and suppression reason. |
| 151 | |
| 152 | The explicit read-only `memory` tool remains available for deeper `search`, |
| 153 | `read`, and `list` operations. Use `history` instead when exact wording or tool |
| 154 | output matters. |
| 155 | |
| 156 | ## Safe writes and confirmation |
| 157 | |
| 158 | The ordinary path is zero-configuration. Reasonix may automatically create a |
| 159 | new memory only when all of these conditions hold: |
| 160 | |
| 161 | - the owning controller has the current project store (interactive or top-level |
| 162 | headless, never a sub-agent); |
| 163 | - the type is explicitly `project` or `reference`; |
| 164 | - the scope is project or omitted; |
| 165 | - the operation is create-only, not an update; |
| 166 | - the body is within the automatic-write budget; |
| 167 | - no credential, secret, private key, or email address is detected; |
| 168 | - no fact with the same name, title, or description already exists. |
| 169 | |
| 170 | The grant is one-shot and the storage layer enforces create-only semantics, so a |
| 171 | concurrent fact cannot be overwritten after assessment. |
| 172 | |
| 173 | Everything else still requires explicit confirmation: |
| 174 | |
| 175 | - global facts; |
| 176 | - `user` preferences and `feedback`; |
| 177 | - updates to an existing ID or revision; |
| 178 | - possible duplicates; |
| 179 | - sensitive or oversized content; |
| 180 | - every `forget` operation. |
| 181 | |
| 182 | Auto and Yolo do not bypass those confirmations. Guardian and permission hooks |
| 183 | cannot approve them for the user. A top-level headless controller may use only |
| 184 | the same one-shot low-risk create path above. Sub-agents and headless surfaces |
| 185 | without the owning scoped controller fail closed; all other memory mutations |
| 186 | still require an interactive confirmation surface. |
| 187 | |
| 188 | Direct edits made by the user in Context Center, `/remember`, restore, and |
| 189 | recovery commands are already explicit user actions and do not add another |
| 190 | approval prompt. |
| 191 | |
| 192 | ## Revisions, archive, and recovery |
| 193 | |
| 194 | Updating a fact creates an immutable snapshot of the previous revision. A stale |
| 195 | `expected_revision` is rejected instead of overwriting a newer edit. |
| 196 | |
| 197 | Restoring an old revision does not rewind storage in place. Reasonix copies the |
| 198 | chosen content into a new, higher revision, preserving a monotonic audit trail: |
| 199 | |
| 200 | ```text |
| 201 | /memory revisions <id-or-name> |
| 202 | /memory restore <id-or-name> <revision> |
| 203 | ``` |
| 204 | |
| 205 | `forget` removes a fact from active recall and moves it to `.archive/`. Recovery |
| 206 | accepts only an archive entry owned by the current store, rejects symlink and |
| 207 | path escapes, refuses ID/name collisions, and never overwrites an active file: |
| 208 | |
| 209 | ```text |
| 210 | /memory archived |
| 211 | /memory recover <archive-path> |
| 212 | ``` |
| 213 | |
| 214 | Recovered content also becomes a new monotonic revision. Restore and recovery |
| 215 | apply to the current session through a one-turn tail note, then join the stable |
| 216 | prefix naturally on the next session. |
| 217 | |
| 218 | ## Zero-configuration suggestions |
| 219 | |
| 220 | Opening the desktop Suggestions tab automatically scans recent local user turns. |
| 221 | There is no setup toggle. It proposes: |
| 222 | |
| 223 | - durable memory candidates from explicit preferences, constraints, and project |
| 224 | conventions; |
| 225 | - Skill candidates from repeated workflow patterns. |
| 226 | |
| 227 | Scanning uses original user content, deduplicates against facts from both scopes |
| 228 | and loaded instruction bodies, and never writes by itself. Every candidate shows |
| 229 | evidence and must be explicitly accepted. Remote workspaces fail closed: |
| 230 | Reasonix does not fall back to local sessions or local memory when the remote |
| 231 | surface cannot provide the feature. |
| 232 | |
| 233 | ## Management surfaces |
| 234 | |
| 235 | Bare `/memory` shows every active fact from both scopes, including ID, revision, |
| 236 | type, scope, freshness, and storage provenance. Structured completion is |
| 237 | available in CLI, desktop, and remote workspaces. |
| 238 | |
| 239 | | Command | Result | |
| 240 | | --- | --- | |
| 241 | | `/memory` | Combined instruction, fact, and archive summary | |
| 242 | | `/memory instructions` | Precedence, directories, imports, diagnostics | |
| 243 | | `/memory recall` | Last automatic-recall trace | |
| 244 | | `/memory revisions <ref>` | Active fact and immutable history | |
| 245 | | `/memory restore <ref> <revision>` | Restore as a new revision | |
| 246 | | `/memory archived` | Archived facts and paths | |
| 247 | | `/memory recover <path>` | Recover an owned archive as a new revision | |
| 248 | |
| 249 | Context Center provides the same model visually, including conflicts and |
| 250 | project-over-global explanations. |
| 251 | |
| 252 | ## Upgrade compatibility |
| 253 | |
| 254 | Context Engine v2 upgrades existing stores without requiring setup: |
| 255 | |
| 256 | - legacy facts without IDs receive deterministic `legacy-*` identities; |
| 257 | - missing revisions start at revision 1; |
| 258 | - missing scope is inferred from the containing project/global directory; |
| 259 | - migration is idempotent and writes the new metadata only once; |
| 260 | - compatibility routing fields keep older clients from moving facts to the |
| 261 | wrong directory when versions share a state root; |
| 262 | - old `MEMORY.md` indexes are treated as derived data and rebuilt from fact |
| 263 | files; |
| 264 | - legacy Memory v5 `<memory-compiler-execution>` transcript blocks remain |
| 265 | readable, while the retired `[agent].memory_compiler` setting is removed. |
| 266 | |
| 267 | No vector database, embedding service, setup wizard, or re-index command is |
| 268 | required. |
| 269 | |
| 270 | ## Cache and privacy contract |
| 271 | |
| 272 | - Standing instructions and the derived memory index join the stable prefix at |
| 273 | session start. |
| 274 | - Provider-visible instruction provenance uses stable `workspace/...` and |
| 275 | `user/...` labels; absolute source and store paths stay in local diagnostics. |
| 276 | - Provider-visible memory tool results use stable `project/<name>.md` and |
| 277 | `global/<name>.md` references. Those references round-trip directly through |
| 278 | read, update, revision, and archive operations, including when both scopes |
| 279 | contain the same name; Context Center and local recovery diagnostics retain |
| 280 | the real storage paths. |
| 281 | - Dynamic recall and mid-session changes are appended only to the current user |
| 282 | turn. |
| 283 | - Diagnostics never enter provider requests. |
| 284 | - Automatic recall omits fact storage paths and redacts home-directory prefixes |
| 285 | in snippets. |
| 286 | - External approval notifications receive the tool name, not memory contents. |
| 287 | - Remote management uses the remote controller's memory catalog and never reads |
| 288 | the desktop machine's local store as a fallback. |
| 289 | |
| 290 | This keeps the provider-visible prefix stable while making dynamic context |
| 291 | observable and recoverable. |
| 292 |