@konuamah/context-bank

A persistent context bank plugin for OpenCode with semantic search. Automatically retrieves, stores, and compresses your coding session memory using in-process AI embeddings.

🚀 What it does

This plugin solves the "goldfish memory" problem in LLM-based coding. It maintains a per-project memory bank that intelligently injects relevant past context into your current conversation.

• ✅ Semantic Retrieval: Finds conceptually related context using 384-dimensional embeddings.
• ✅ No External Servers: Powered by @xenova/transformers running entirely in-process.
• ✅ Privacy First: Your data stays local in ~/.config/opencode/context-bank/.
• ✅ Cross-Platform: Fully compatible with macOS, Linux, and Windows.
• ✅ Automatic Compaction: Compresses old memory entries to save tokens while retaining core insights.
• ✅ Preemptive Compaction: Proactively triggers compaction before context limits are hit, using session summarization to preserve memory context.
• ✅ Memory Keywords: Detects phrases like "remember that" or "save this" and prompts AI to save important info.
• ✅ Context Bank Tool: Built-in tool (context-bank) for managing memories directly — add, list, search, and forget.

| Hook | Action | |---|---|---| | tool.execute.before | Retrieves relevant past context and injects it before each tool call | | tool.execute.after | Stores tool results with semantic embeddings | | experimental.session.compacting | Injects memory summary during session compaction | | event: session.idle | Compresses old entries when the session ends | | event: message.updated | Triggers preemptive compaction when context usage exceeds threshold | | client | Provides SDK client for session.summarize() and tui.showToast() |

🔧 Context Bank Tool

The plugin includes a built-in context-bank tool for managing your memories directly:

| Command | Description | Example | |---|---|---| | add | Save a memory | context-bank mode:add content:"Use bun test" scope:project | | list | List recent memories | context-bank mode:list scope:project limit:20 | | search | Search memories | context-bank mode:search query:"testing" | | forget | Delete a memory | context-bank mode:forget memoryId:<id> |

Scopes

• project (default): Project-specific memories
• user: Cross-project memories that apply everywhere

💾 Memory Keyword Detection

When you use phrases like "remember that", "save this", "don't forget", or "keep in mind", the plugin automatically prompts the AI to save that information as a memory. No manual tool calls needed.

Detected keywords:

• remember that / remind me
• save this / write this down
• don't forget / keep in mind
• note that / make a note
• take note / note to self

📦 Installation

1. Install via npm

npm install @konuamah/context-bank

2. Add to OpenCode Config

Add the plugin to your global (~/.config/opencode/opencode.json) or project-level opencode.json. Note: This step must be done manually after installation.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@konuamah/context-bank"]
}

3. Restart OpenCode

Important: After adding the plugin to your config:

1. Exit OpenCode completely (close all sessions)
2. Start a new OpenCode session

If the plugin doesn't load after restarting OpenCode, restart your machine. This is especially important on macOS where cached processes may prevent the plugin from initializing.

To verify the plugin is working, check if the context bank directory exists:

ls ~/.config/opencode/context-bank/

4. (Optional) Pre-download AI Model

The model (~23 MB) downloads automatically on first use. To pre-download it manually:

npx @konuamah/context-bank-setup

🧠 Semantic Search

Unlike keyword-based search, this plugin understands the meaning of your actions:

| Your Query | Finds Related Context | |------------|----------------------| | "file operations" | read, write, delete, fs module, path manipulation | | "error handling" | try/catch, validation, exceptions, failure cases | | "authentication" | login, sessions, user management, auth tokens | | "database query" | SQL, ORM, data fetching, db operations |

Technical Details

• Model: Xenova/all-MiniLM-L6-v2
• Embeddings: 384-dimensional vectors
• Storage: JSON files per project at ~/.config/opencode/context-bank/<project>.json
• Performance: <1ms retrieval for 300 entries.

⚙️ Configuration

The plugin uses sensible defaults but can be tuned by editing the constants in the source (or fork):

| Constant | Default | What it controls | |---|---|---| | MAX_ENTRIES | 300 | Max entries stored per project | | TOP_K | 8 | Number of relevant entries retrieved per query | | TOKEN_CAP | 1200 | Maximum tokens dedicated to injected context | | SUMMARIZE_AFTER_HOURS | 24 | Age before an entry's result is compressed | | COMPACTION_THRESHOLD | 0.80 | Context usage ratio (80%) that triggers preemptive compaction | | MIN_TOKENS_FOR_COMPACTION | 50000 | Minimum tokens before compaction can trigger | | COMPACTION_COOLDOWN_MS | 30000 | Cooldown period (30s) between compaction attempts | | DEFAULT_CONTEXT_LIMIT | 200000 | Fallback context limit if model limit cannot be determined |

🛠️ Development

Build from source

git clone https://github.com/konuamah/context-bank.git
cd context-bank
npm install
npm run build

Run tests

npm run typecheck

📄 License

MIT © Kelvin Owusu Nuamah