Context Anchor Anchors

Why Context Anchor?

When long coding or research sessions hit token limits, automatic context compression summarizes raw history—often discarding exact file paths, subtle constraints, rejected approaches, and active task state.

Antigravity does not currently expose a PreCompact lifecycle hook or allow plugins to rewrite its internal compaction prompt. Context Anchor solves this within Antigravity's native plugin architecture by pairing:

1. Agent-Selected Context Anchoring (MCP Tools) — Gives the running agent first-class tools (pin_context, unpin_context, list_pinned_context, get_pinned_context, replace_session_anchors) so the agent itself decides what must survive compression.

2. Proactive Token & Compaction Watcher (Lifecycle Hooks) — Tails transcript.jsonl on PreInvocation to warn the agent before auto-compaction hits, and automatically re-injects pinned anchors when a context drop is detected.

3. Always-On Curation Rule & /context-anchor Skill — Guides the agent to pin concise conclusions and exact pointers (never bloated raw logs), and lets you trigger manual curation at any time via /context-anchor.

4. Zero Dependencies — Pure Node.js (>= 18) standard library; works across Windows, macOS, and Linux without npm install.

Related MCP server: mnemex

How It Works

flowchart LR
    A[SessionStart / PreInvocation Hook] -->|Register session_id & tail transcript.jsonl| B{Token Check}
    B -->|Tokens >= 80k| C[Inject Pre-Compression Nudge]
    C -->|Agent curates important context| D[MCP: pin_context / replace_session_anchors]
    D -->|Atomic JSON write| E[(Session & Workspace Anchors)]
    B -->|Token drop >= 35% or step reset| F[Compaction Detected]
    E -->|Priority sort: critical > high > normal| F
    F -->|Inject systemMessage| G[Agent Continues Without Amnesia]

Features & Components

1. MCP Server (anchors -> context-anchor_anchors)

Supported categories: decision, constraint, state, file_map, pitfall, task.
Supported scopes:

• session (default): Isolated to the current conversationId.

• workspace: Persists across conversations in the same workspace directory.

2. Lifecycle Hooks (hooks.json)

• SessionStart: Registers the active conversationId, injects session_id, and restores any workspace-scoped anchors.

• PreInvocation: Reads only the last 128 KB of transcript.jsonl:

  • Sends a non-spammy reminder when prompt tokens cross 80k (and every +40k thereafter).

  • Detects compaction when a compaction/checkpoint step appears, step count resets, or prompt tokens drop by >= 35% (and >= 10k tokens)—ignoring stale pre-compaction PLANNER_RESPONSE token telemetry so a CHECKPOINT never double-triggers recovery—and injects preserved anchors ordered by priority along with a post-compaction core context recap instruction.

• Stop: Updates session metadata cleanly without blocking turn completion.

3. CLI Fallback (scripts/cli.mjs)

For manual inspection or pre-existing sessions where MCP tools have not yet attached:

node ./scripts/cli.mjs pin --title "API Contract" --content "Keep v1 response shape." --priority critical --category constraint
node ./scripts/cli.mjs list
node ./scripts/cli.mjs get
node ./scripts/cli.mjs unpin --title "API Contract"

Installation

Option 1: Install via Antigravity CLI (agy)

# Install directly from a local clone or GitHub repository URL
agy plugin install https://github.com/Over9rowth/context-anchor

Option 2: Manual Local Installation (Antigravity App / IDE / CLI)

Copy or clone this repository into your global Antigravity plugins folder:

• macOS / Linux:

  git clone https://github.com/Over9rowth/context-anchor.git ~/.gemini/config/plugins/context-anchor

• Windows (PowerShell):

  git clone https://github.com/Over9rowth/context-anchor.git "$env:USERPROFILE\.gemini\config\plugins\context-anchor"

Note: After installing, open a new conversation (or reload) so the MCP server context-anchor_anchors attaches its tool declarations to the session.

Usage

• Automatic mode: Just work normally. The always-on rule (rules/AGENTS.md) and PreInvocation hook nudge the agent to curate critical context as sessions grow, restore it once after compression, and automatically recap the restored core context at the start of the post-compaction reply.

• Recommended /context-anchor -> /compact flow:

  1. Type /context-anchor to have the agent audit, deduplicate, and save key context anchors, then prompt you with a /compact handoff.

  2. Type /compact in chat to compact the conversation window (Antigravity restricts slash commands to direct user input, so plugins/agents cannot run /compact automatically).

  3. Send any short follow-up (e.g., 继续 / continue)—context-anchor injects your curated anchors and instructs the agent to briefly recap the restored core context before resuming work.

• Natural language: Ask the agent directly, e.g., "Pin our current architecture decisions and modified files with pin_context."

Configuration (Optional Environment Variables)

Development & Testing

Requires Node.js >= 18.0.0. No dependencies to install:

npm test
# or
node --test ./scripts/test.mjs

License

MIT