OpenFundus

All-in-one OpenCode plugin: cross-session memory, selective context reduction, and session protection hooks

OpenFundus combines three subsystems into a single plugin:

1. Memory — Persistent cross-session memory with full-text search, tagging, linking, and auto-recall
2. SCR (Selective Context Reduction) — Token-aware context pruning, deduplication, and compression
3. Hooks — Nine session protection and enhancement hooks that run automatically

Installation

Add to your OpenCode config:

// .opencode/opencode.jsonc
{
  "plugin": ["openfundus@latest"]
}

Using @latest ensures you always get the newest version automatically when OpenCode starts.

Restart OpenCode. The plugin will automatically start managing your sessions.

Memory

Overview

OpenFundus stores important findings, decisions, and code patterns in a local SQLite database with FTS5 full-text search. Memories persist across sessions and are automatically recalled when relevant.

• Full-text search with BM25 ranking and relevance decay (90-day half-life)
• Deduplication via Jaccard similarity to prevent storing near-duplicates
• Auto-recall injects relevant memories into the system prompt at session start
• Auto-extraction detects preferences, bug fixes, and conventions from tool outputs
• Mistake tracking stores tool errors as anti-pattern memories to avoid repeating them
• File knowledge caching remembers file contents to skip redundant reads

Memory Tools

| Tool | Description | |------|-------------| | memory_store | Store a memory with content, category, tags, scope (project/global), and optional dedup bypass | | memory_search | Full-text search with BM25 ranking, category filter, and configurable result limit | | memory_update | Update content, category, or source of an existing memory | | memory_delete | Delete a memory by ID | | memory_list | List recent memories with category and scope filters | | memory_refresh | Boost a memory's relevance score to prevent decay | | memory_tag | Add, remove, or list tags on a memory; list all tags; search by tag | | memory_link | Create relationships between memories (related, supersedes, contradicts, extends) | | memory_stats | Show total count, category breakdown, and database size | | memory_cleanup | FTS optimization, purge old memories, enforce limits, vacuum database | | memory_export | Export memories to versioned JSON with tags and links | | memory_import | Import memories from JSON with conflict handling and link restoration | | memory_file_check | Check if a file has changed since last read; returns cached content if unchanged |

Memory Categories

decision | pattern | debugging | preference | convention | discovery | anti-pattern | general

Memory Configuration

Configure under the openrecall key in opencode.json plugins config:

{
  "plugins": {
    "openfundus": {
      "autoRecall": true,
      "autoExtract": true,
      "searchLimit": 10,
      "maxMemories": 0,
      "globalMemories": false
    }
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | dbPath | string | ~/.local/share/opencode/openrecall.db | Database file path | | autoRecall | boolean | true | Auto-inject relevant memories on session start | | autoExtract | boolean | true | Auto-extract patterns from tool outputs | | searchLimit | number | 10 | Default max search results | | maxMemories | number | 0 | Memory limit (0 = unlimited) | | globalMemories | boolean | false | Enable cross-project global memories | | agentModel | string | "" | Model to use for agent extraction |

SCR (Selective Context Reduction)

Overview

SCR manages the LLM's context window by removing redundant or low-value content. It runs automatically alongside memory features and provides three tools plus automatic reduction strategies.

SCR Tools

| Tool | Description | |------|-------------| | prune | Remove completed tool call/result pairs from context by their numeric IDs | | distill | Replace a tool's output with a condensed summary, preserving key information | | compress | Collapse a range of messages into a summary using text boundaries |

Automatic Strategies

SCR applies these strategies transparently during the message transform phase:

• Deduplication — Detects and removes duplicate tool calls (e.g., reading the same file twice)
• Supersede Writes — When a file is written/edited multiple times, keeps only the latest version
• Purge Errors — Removes old error outputs that are no longer relevant

SCR CLI Commands

Use /scr in the OpenCode TUI:

| Command | Description | |---------|-------------| | /scr help | Show all available SCR commands | | /scr context | Display current context usage and prunable tools | | /scr stats | Show token savings statistics (session and all-time) | | /scr sweep [n] | Auto-prune the oldest N tool results | | /scr manual [on\|off] | Toggle manual mode (disables automatic nudges) | | /scr prune | Trigger prune on next assistant turn | | /scr distill | Trigger distill on next assistant turn | | /scr compress | Trigger compress on next assistant turn |

SCR Configuration

SCR supports multiple config locations (in priority order):

1. Project: <project>/.opencode/scr.jsonc (or scr.json)
2. Custom: $OPENCODE_CONFIG_DIR/scr.jsonc (or scr.json)
3. Global: ~/.config/opencode/scr.jsonc (or scr.json)

Example config with all defaults shown:

{
  "enabled": true,
  "debug": false,
  "pruneNotification": "detailed",   // "off" | "minimal" | "detailed"
  "pruneNotificationType": "chat",    // "chat" | "toast"
  "manualMode": {
    "enabled": false,
    "automaticStrategies": true       // run strategies even in manual mode
  },
  "turnProtection": {
    "enabled": false,
    "turns": 4                        // protect tool results from the last N turns
  },
  "protectedFilePatterns": [],        // glob patterns for files that should never be pruned
  "strategies": {
    "deduplication": { "enabled": true, "protectedTools": [] },
    "supersedeWrites": { "enabled": true },
    "purgeErrors": { "enabled": true, "turns": 4, "protectedTools": [] }
  },
  "tools": {
    "prune": { "permission": "allow" },
    "distill": { "permission": "allow", "showDistillation": false },
    "compress": { "permission": "deny", "showCompression": false },
    "settings": {
      "nudgeEnabled": true,
      "nudgeFrequency": 10,
      "protectedTools": ["memory_store", "memory_search"],
      "contextLimit": 100000
    }
  },
  "commands": { "enabled": true, "protectedTools": [] }
}

| Key | Description | |-----|-------------| | enabled | Enable/disable SCR entirely | | debug | Write debug logs to ~/.config/opencode/logs/scr/ | | pruneNotification | Notification verbosity: "off", "minimal", or "detailed" | | pruneNotificationType | Where notifications appear: "chat" or "toast" | | manualMode.enabled | Disable automatic nudges (tools still available manually) | | manualMode.automaticStrategies | Run automatic strategies even when manual mode is on | | turnProtection.enabled | Protect recent tool results from being pruned | | turnProtection.turns | Number of recent turns to protect | | protectedFilePatterns | Glob patterns for files that should never be pruned | | tools.*.permission | "allow" (auto), "ask" (confirm), or "deny" (disabled) | | tools.settings.nudgeEnabled | Periodically remind the model to prune | | tools.settings.nudgeFrequency | Nudge every N tool calls (default: 10) | | tools.settings.contextLimit | Token threshold for compress nudge (absolute number or "80%") | | tools.settings.protectedTools | Tools that should never be pruned | | tools.settings.modelLimits | Per-model context limits, e.g. { "anthropic/claude-sonnet-4-5-20250929": "75%" } | | strategies.deduplication.enabled | Auto-remove duplicate tool calls | | strategies.deduplication.protectedTools | Tools exempt from deduplication | | strategies.supersedeWrites.enabled | Keep only latest write to each file | | strategies.purgeErrors.enabled | Auto-remove old error outputs | | strategies.purgeErrors.turns | How many turns back to purge errors | | strategies.purgeErrors.protectedTools | Tools exempt from error purging | | commands.protectedTools | Tools that can't be pruned via CLI commands |

Session Protection Hooks

These hooks run automatically and require no configuration.

1. Preemptive Compaction

Monitors context usage and auto-triggers OpenCode's built-in compaction at 78% capacity. Prevents the model from hitting the context limit mid-task.

2. Compaction Todo Preserver

Snapshots the current todo list before compaction runs, then restores it after. Prevents todos from being lost when the context is compacted.

3. Edit Error Recovery

When an Edit tool call fails (e.g., the old_string was not found), injects a reminder to re-read the file before retrying. Prevents the model from repeatedly failing on stale file content.

4. Tool Output Truncator

Strips ANSI escape sequences from all tool outputs to save tokens. Truncates excessively large outputs to prevent context bloat:

• Grep, Glob, WebFetch: ~40,000 characters
• All other tools: ~200,000 characters

Appends a truncation notice so the model knows the output was cut.

5. Non-Interactive Environment

Prepends environment variables to shell commands that invoke git to prevent interactive prompts that would hang:

• GIT_EDITOR=: GIT_PAGER=cat GIT_TERMINAL_PROMPT=0

Also warns when interactive tools (less, vim, nano, etc.) are detected.

On Windows, sanitizes >nul / 2>nul redirections to >/dev/null to prevent Git Bash from creating undeletable nul files.

6. Context Window Monitor

At 70%+ context usage, appends a brief status line to tool outputs reminding the model how much context remains. Helps the model make informed decisions about whether to prune.

7. Write-Existing-File Guard

Blocks Write tool calls that target existing files and throws an error directing the model to use Edit instead. Prevents accidental file overwrites.

8. Session Recovery

Detects API errors (tool_result_missing, thinking_block_order, thinking_disabled_violation, unavailable_tool) and automatically recovers the session. Prevents sessions from dying due to transient API issues.

9. Edit Tool Argument Coercion

Coerces the replaceAll argument from string ("false") to boolean (false) before the Edit tool executes. Fixes schema validation errors caused by LLMs outputting string values instead of booleans.

Structured Compaction

When OpenCode compacts the session context, OpenFundus injects a structured summary template that preserves:

1. Original user requests (verbatim)
2. Final goal and expected deliverable
3. Work completed with file paths
4. Remaining tasks
5. Active working context (files, code in progress, references, state)
6. Mistakes and anti-patterns encountered
7. Key decisions and discoveries

This ensures continuity after compaction without losing critical context.

Data Storage

• Memory database: ~/.local/share/opencode/openrecall.db (configurable)
• SCR session state: ~/.local/share/opencode/storage/plugin/scr/{sessionId}.json
• SCR logs: ~/.config/opencode/logs/scr/ (when debug is enabled)
• All data is stored locally

Development

bun install
bun test
bun run typecheck

License

MIT