@audaxic/memory-opencode

OpenCode plugin for Audaxic Memory — 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: https://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

1. Message Capture: The plugin uses chat.message and message.part.updated hooks to capture both user prompts and assistant responses.

2. In-Memory Buffer: Messages are buffered in memory up to 30 items. The sidebar indicator shows the current count (e.g. 15/30 messages).

3. Disk Persistence: Each message is immediately written to ~/.config/audaxic/pending.json so no data is lost on crash or /exit.

4. Batch API Flush: When the buffer reaches 30 messages, they are sent to POST /add and cleared from disk.

5. Startup Recovery: On next launch, any pending.json is read and sent to POST /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.

6. 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:

1. AUDAXIC_API_KEY environment variable
2. ~/.config/audaxic/config.json config file

Memory Search & Context Injection

After a user prompt is received and before the agent answers, the plugin:

1. Takes the latest user message (excluding synthetic parts like file-read output).
2. Searches your memory via POST /search (up to 5 results, 8s timeout, 2 attempts).
3. 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 — it never persists to the session, so you won't see it in the conversation history or 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 |

Related

• Audaxic Memory Documentation
• Audaxic Memory MCP Server
• OpenCode Plugins Documentation

License

MIT