Mnemosyne

Context-aware token optimization for OpenCode

Mnemosyne is an OpenCode plugin that reduces token consumption at every layer through integrated systems: command output filtering, dynamic context pruning, persistent memory offloading, and automatic codebase indexing.

Installation

{
  "plugin": ["@enowdev/mnemosyne@latest"]
}

Add the line above to your opencode.json and restart OpenCode. That's it — everything works automatically.

What It Does

🔧 RTK — Command Output Filtering

Automatically filters verbose CLI output before it enters the LLM context. No configuration needed.

| Command | What It Does | Token Savings | |---------|-------------|---------------| | git status/diff/log/branch | Compact, grouped output | 40-90% | | git add/commit/push/pull | Ultra-compact confirmations | 80-95% | | vitest/playwright/pytest/cargo test/go test | Failures only | 70-90% | | tsc/eslint/biome | Errors grouped by file/rule | 60-80% | | docker ps/images/logs | Compact tables | 60-80% | | grep/find/ls | Grouped and deduplicated | 30-70% | | pnpm/pip list/outdated | Compact package info | 60-80% | | gh pr/issue/run list | Compact GitHub info | 60-80% | | next build/prettier | Metrics/files only | 70-95% |

✂️ DCP — Dynamic Context Pruning

Manages conversation context automatically through pruning strategies and AI-driven compression.

Automatic Strategies:

• Deduplication — Removes duplicate tool calls, keeps most recent
• Supersede Writes — Prunes write inputs when file is subsequently read
• Purge Errors — Removes errored tool inputs after N turns

Compress Tool — AI can compress conversation ranges into technical summaries. Supports nested compression.

Nudge System — Automatically prompts compression when context gets large.

Slash Commands:

| Command | Description | |---------|-------------| | /mn context | Token usage breakdown | | /mn stats | Cumulative pruning statistics | | /mn sweep [N] | Prune tool outputs manually | | /mn manual [on\|off] | Toggle manual mode |

🧠 Memory — Automatic Persistent Storage

Completed work is automatically captured to .memory/ on disk via hooks. No manual intervention needed.

Auto-triggers:

• Task marked completed via todowrite → auto-saved to .memory/tasks/
• Context exceeds 75% → heavy tool outputs auto-offloaded to .memory/
• Old memory entries → auto-replaced with compact pointers in context

Structure:

.memory/
├── index.json
├── codebase/
│   └── index.json          # Auto-indexed code structure
├── tasks/
│   ├── 001-auth-middleware.md
│   └── 002-api-routes.md
├── decisions/
│   └── 001-database-choice.md
└── errors/
    └── 001-cors-issue.md

Manual tools (for decisions/errors not captured by auto-hooks):

| Tool | Description | |------|-------------| | memory_write | Save a decision or error to .memory/ | | memory_read | Read a memory entry by ID | | memory_search | Search memories by keyword | | code_search | Search auto-indexed codebase structure |

📂 Code Index — Automatic Codebase Mapping

Every file the AI reads is automatically indexed — exports, imports, and language are captured to .memory/codebase/index.json. Structure exploration commands (find, ls, tree, glob, grep) also feed the index.

The AI can use code_search to locate features/functions without re-reading files.

🚫 No-Comment Rule

Automatically instructs the AI to write code without comments (to save tokens). Comments are only added when the user explicitly requests them. Configurable via memory.noCommentRule.

Configuration

Optional. Create mnemosyne.jsonc in one of these locations (priority: project > custom > global):

• Project: .opencode/mnemosyne.jsonc
• Custom: $OPENCODE_CONFIG_DIR/mnemosyne.jsonc
• Global: ~/.config/opencode/mnemosyne.jsonc

{
  "enabled": true,
  "debug": false,
  "rtk": {
    "enabled": true,
    "excludeCommands": [],
    "tracking": true
  },
  "dcp": {
    "enabled": true,
    "manualMode": false,
    "pruneNotification": "minimal",
    "compress": {
      "maxContextLimit": 100000,
      "minContextLimit": 30000,
      "nudgeFrequency": 5,
      "nudgeForce": "soft",
      "permission": "allow"
    },
    "strategies": {
      "deduplication": { "enabled": true },
      "supersedeWrites": { "enabled": true },
      "purgeErrors": { "enabled": true, "turns": 4 }
    },
    "turnProtection": 2,
    "protectedTools": ["task", "skill", "todowrite", "todoread", "write", "edit", "memory_write", "memory_read", "memory_search"],
    "protectedFilePatterns": []
  },
  "memory": {
    "enabled": true,
    "offloadThreshold": 0.75,
    "maxDetailSize": 8192,
    "searchResultLimit": 10,
    "pointerReplacementTurns": 3,
    "codeIndex": {
      "enabled": true,
      "indexFileReads": true,
      "indexStructureExploration": true,
      "maxFileSizeForIndex": 50000
    },
    "noCommentRule": true
  }
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    OpenCode Core                         │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                  Mnemosyne Plugin                        │
│                                                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐│
│  │    RTK     │  │    DCP     │  │      Memory        ││
│  │ • Filters  │  │ • Prune   │  │ • Auto-capture     ││
│  │ • Tracking │  │ • Compress │  │ • Auto-offload     ││
│  │            │  │ • Nudges   │  │ • Code index       ││
│  │            │  │ • Commands │  │ • Search            ││
│  └────────────┘  └────────────┘  └────────────────────┘│
│                                                          │
│  Hooks:                                                  │
│  1. tool.execute.before  → RTK stores command            │
│  2. tool.execute.after   → RTK filters + Memory indexes  │
│  3. chat.system.transform → DCP + Memory prompts         │
│  4. chat.messages.transform → Auto-offload → DCP → Memory│
│  5. chat.message → DCP variant cache                     │
│  6. command.execute.before → /mn slash commands           │
└──────────────────────────────────────────────────────────┘

Credits

Mnemosyne is built upon the ideas and work of:

• RTK (Rust Token Killer) by rtk-ai — The original command output filtering system written in Rust. Mnemosyne's RTK module is a TypeScript rewrite inspired by RTK's filtering patterns and command modules.

• OpenCode Dynamic Context Pruning by Opencode-DCP — The original context pruning plugin for OpenCode. Mnemosyne's DCP module is a rewrite adapting DCP's pruning strategies, compression system, and nudge architecture.

The Memory system, automatic code indexing, and no-comment rule are original additions.

License

MIT