Skip to content

feat/context-management - #52

Open
jwitmann wants to merge 19 commits into
aerovato:mainfrom
jwitmann:feat/context-management
Open

jwitmann wants to merge 19 commits into
aerovato:mainfrom
jwitmann:feat/context-management

Conversation

@jwitmann

@jwitmann jwitmann commented Oct 5, 2026 •

Copy link
Copy Markdown

Intent

Implements the Context Management roadmap item of Operator Memory: deterministic, local-only context reduction for the OpenCode V2 adapter. Magic Compact's README names Operator Memory its successor ; so this is the context-management feature arriving there, built by porting Magic Compact's trim machinery onto Operator's Brain-backed design.

Design summary

Three deterministic triggers, all off by default:

  • end-of-run compaction (session.execution.succeeded, gated by compactFloorTokens).
  • trim past a window ratio.
  • trim past an absolute hard cap.

Each deduplicated per session with cross-process state hydrated from the receipt log.

Trim replaces bulky completed tool I/O with omission notices (stored per-payload under ~/.operator/state/omitted/, recoverable through theoperator:read_omitted tool) and re-applies identically on every over-threshold request.

Compaction is requested throughctx.session.compact and shaped prompt-only (Brain partition paths
referenced, never inlined); the hook never rewrites messages and never sets result, per the live findings below. The
Brain is a hard prerequisite: without an initialized partition the feature stays off and logs one refusal receipt per session.

Every trim and compaction appends one JSON line to ~/.operator/state/context-log/<sessionID>.log. No network, no quota, no metering, no model-driven pruning decisions.

Configuration

Single opt-in switch, off by default (vanilla behavior unchanged). A full user reference follows in the docs follow-up. The block lives in the plugins entry's options — global (~/.config/opencode/opencode.json) for every project, or a project
root opencode.json / opencode.jsonc for one project (configs merge; a local directory plugin entry resolves <dir>/index.js, so point it at the built dist directory):

{
  "operator": {
    "contextManagement": {
      "enabled": false,
      "ratio": 0.8,
      "hardCapTokens": 250000,
      "keepRecentTurns": 3,
      "compactOnComplete": true,
      "compactFloorTokens": 32000
    }
  }
}

Requires an initialized Brain (/operator:user-init or /operator:project-init); without one the feature stays off with a
refusal receipt.

Verification evidence

  • Rebased onto origin/main at 734bb11 (helper@v1.9.0). Branch holds 15 feat(core|opencode-v2) commits only, no merges. Diff scope: packages/core/, packages/opencode-v2/, bun.lock (32 files).
  • bun run check packages/core — green (format, lint, typecheck, 9 files / 73 tests pass).
  • bun run check packages/opencode-v2 — green (format, lint, typecheck, 10 files / 63 tests pass).
  • bun run check (root) — green, 42 files / 296 tests pass.
  • Live runs on OpenCode v2.0.22 (@opencode/plugin 2.0.14, model opencode-go/qwen3.8-flash): inert when disabled; refusal with no Brain; trim with receipts and byte-identical re-trim; read_omitted round-trip; single task-complete compaction across its own follow-up run; continued sessions open on compacted history with recall verified. Detailed run log (sessions, receipts, host rows) held with the design notes.

Notes for reviewers

  • Runtime writes in core (~/.operator/state/) are a new precedent: core previously only read. They are operational state, deliberately outside the Brain partitions (never cataloged, safe to delete).
  • Two mechanisms were built, verified live, then removed: the result short-circuit and the keep-tail budget — both destroy
    view history on v2.0.22. The removal commits are in the branch history; the spec no longer contains them.
  • Known limitation: compactions requested at the very end of a opencode run can lose a race with standalone server teardown (mid-run compactions complete reliably).
  • Known limitation: per-request store round-trips scale with stored omissions (see Follow-ups); harmless at small scale, follow-up planned.

@jwitmann jwitmann changed the title Context management feat/context-management Oct 9, 2026
@jwitmann
jwitmann force-pushed the feat/context-management branch from 4e34c08 to eaf36dc Compare October 28, 2026 07:13
@jwitmann

Copy link
Copy Markdown
Author

Status + roadmap check-in. #52 itself is ready for review (16 commits, green gates, shared-doc binding note now included per the contributing guide).

Behind it I have a sequenced stack, each as its own PR after this one merges — nothing will be opened until you weigh in:

  1. docs — user guide for context management (docs/harnesses/opencode-v2.md, comparison, troubleshooting).
  2. perf — batching (single-walk trim, batched store), event-stream resubscribe, unexecuted-cause expiry, receipt-failure surfacing, plus omission retention (operator:prune, 200 payloads / 32 MiB / 30 days).
  3. preamble-refresh — opt-in mid-session preamble re-render on Brain fingerprint moves, gated on cold provider cache (post-compaction bypasses).
  4. brain-updates — opt-in nudge counting distinct completed tool calls since the last fingerprint move (threshold 25, one reminder per era, never writes the Brain).

Two questions before I open anything else:

  • (a) does this sequence look right to you, or would you rather see something consolidated?
  • (b) is the opt-in-per-feature direction (operator.contextManagement / preambleRefresh / brainUpdates, all off by default) the shape you'd accept upstream?

Happy to rework #52 itself first if the direction needs adjusting — cheaper now than after four more PRs.

A host-reported failed compaction arms a per-session backoff (ten
minutes, then growth-gated re-arm); both request paths check it before
admitting. Requests are single-flight while one is outstanding, the
hook clears the backoff when an attempt runs, and the shared runtime
is pinned to globalThis so reloads keep the state.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant