OpenCode Plugin
Automatically saves conversation facts to your persistent memory layer and injects relevant memories as context before the agent answers.
Installation
npm install -g @audaxic/memory-opencode
Setup
Before using the plugin, configure your API key:
npx @audaxic/memory-opencode setup
This will prompt you for your Audaxic API key and save it to ~/.config/audaxic/config.json with secure file permissions (600).
Get your API key from: memory-dashboard.audaxic.com
Configuration
Server plugin
Add to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@audaxic/memory-opencode"]
}
TUI plugin (sidebar indicator + toast)
Add to your ~/.config/opencode/tui.json:
{
"$schema": "https://opencode.ai/tui.json",
"plugin": ["@audaxic/memory-opencode"]
}
The plugin will be automatically loaded by OpenCode on startup.
How It Works
-
Message Capture: The plugin uses
chat.messageandmessage.part.updatedhooks to capture both user prompts and assistant responses. -
In-Memory Buffer: Messages are buffered in memory up to 30 items. The sidebar indicator shows the current count (e.g.
15/30 messages). -
Disk Persistence: Each message is immediately written to
~/.config/audaxic/pending.jsonso no data is lost on crash or/exit. -
Batch API Flush: When the buffer reaches 30 messages, they are sent to
POST /addand cleared from disk. -
Startup Recovery: On next launch, any
pending.jsonis read and sent toPOST /add. The file is deleted only after the API confirms receipt; on any failure (HTTP error or network exception) it stays on disk untouched and is retried on the next launch — data loss is impossible. -
Silent Failure: If no API key is configured, the plugin logs a warning and disables itself without blocking OpenCode.
Sidebar Indicator
The TUI plugin adds a status block to the session sidebar:
| State | Display |
|---|---|
| Idle | ● Audaxic Memory / listening |
| Searching | ● Audaxic Memory / retrieving... |
| Retrieved | ● Audaxic Memory / retrieved 3 memories (brief) |
| Buffering | ● Audaxic Memory / 15/30 messages |
| Flushing | ● Audaxic Memory / saving... |
| Error | ● Audaxic Memory / last save failed (yellow) |
The indicator updates every 2 seconds by polling the server's status file.
Environment Variable Alternative
Instead of using the setup script, you can set the API key as an environment variable:
export AUDAXIC_API_KEY="ak_your_key_here"
The plugin checks in this order:
AUDAXIC_API_KEYenvironment variable~/.config/audaxic/config.jsonconfig file
Memory Search & Context Injection
After a user prompt is received and before the agent answers, the plugin:
- Takes the latest user message (excluding synthetic parts like file-read output)
- Searches your memory via
POST /search(up to 5 results, 8s timeout, 2 attempts) - Injects the results as a synthetic user message wrapped in
<audaxic_memory_context>...</audaxic_memory_context>into the model request
The injection is:
- In-memory only — never persists to the session, so it won't appear in conversation history or the TUI
- Once per user message — subsequent agent loop steps (tool calls, etc.) reuse the already-injected context instead of re-searching
- Silent on failure — if the search API is unreachable, the plugin logs a warning and the conversation proceeds without context
To disable auto-search/injection (saving still works):
export AUDAXIC_SEARCH=off
Architecture
┌──────────────────────────────────────────────────────────────────┐
│ OpenCode CLI │
│ │
│ ┌───────────────────── Server Plugin ───────────────────────┐ │
│ │ │ │
│ │ chat.message hook ──► user text ──┐ │ │
│ │ event hook (part) ──► assistant ──┤ │ │
│ │ ▼ │ │
│ │ messageBuffer[30] │ │
│ │ │ │ │ │
│ │ ┌─────────┴──┐ ┌──┴──────────┐ │ │
│ │ │ < 30 msgs │ │ >= 30 msgs │ │ │
│ │ └─────┬─────┘ └──────┬───────┘ │ │
│ │ │ ▼ │ │
│ │ │ POST /add (flush) │ │
│ │ │ │ │ │
│ │ ┌─────┴─────┐ │ │ │
│ │ │ pending │ │ │ │
│ │ │ .json │ │ │ │
│ │ │ (disk) │ │ │ │
│ │ └───────────┘ │ │ │
│ │ │ │ │ │
│ │ SIGINT / /exit │ │ │
│ │ ▼ │ │ │
│ │ process.on("exit") │ │ │
│ │ flushPendingSync() │ │ │
│ │ │ │ │
│ │ experimental.chat.messages.transform ────┘ │ │
│ │ (once per user message, in-memory only) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ POST /search (limit 5, 8s × 2) ──► inject context │ │
│ │ │ into model request │ │
│ │ ▼ │ │
│ │ agent answers with memory context │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────── TUI Plugin ────────────────────────┐ │
│ │ │ │
│ │ Startup ──► Toast notification │ │
│ │ Every 2s ──► Polls status.json ──► Updates sidebar │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
https://api.memory.audaxic.com/add | POST | Save conversation messages |
https://api.memory.audaxic.com/search | POST | Search memories for context injection |
Troubleshooting
Plugin not loading
- Verify
@audaxic/memory-opencodeis installed globally - Check
opencode.jsonhas the plugin configured - Restart OpenCode after adding the plugin
Messages not saving
- Verify API key is set:
npx @audaxic/memory-opencode setup - Check
~/.config/audaxic/config.jsonexists and has valid key - Check
~/.config/audaxic/pending.jsonfor unsent messages
Sidebar not showing
- Add plugin to
~/.config/opencode/tui.json - Restart OpenCode
Context not being injected
- Verify API key is set and valid at memory-dashboard.audaxic.com
- Check network connectivity to
api.memory.audaxic.com - If
AUDAXIC_SEARCH=offis set, injection is intentionally disabled — unset it to re-enable