opencode-agent-memory

Persistent, semantic memory for OpenCode agents. Provides memory_store, memory_recall, memory_forget, memory_list, memory_update, and memory_stats tools to any agent running in your workspace.

Memory is stored per-workspace in a LanceDB vector database, with embeddings generated by a local Ollama model. No data leaves your machine.

Prerequisites

• Node.js 18+
• Python 3.8+ with pip
• Ollama running locally with the bge-m3:latest embedding model
• LanceDB Python dependencies:

pip install lancedb pyarrow

Pull the embedding model:

ollama pull bge-m3:latest

Installation

OpenCode loads plugins from its own node_modules directory — not from the global npm registry. You must install into the OpenCode config directory.

Global (recommended) — tools available in all workspaces

cd ~/.config/opencode
npm install @chiaboon/opencode-agent-memory

Add to your global OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": ["@chiaboon/opencode-agent-memory"]
}

Per-workspace — tools available in one workspace only

cd /path/to/your/workspace/.opencode
npm install @chiaboon/opencode-agent-memory

Add to your workspace's .opencode/opencode.json:

{
  "plugin": ["@chiaboon/opencode-agent-memory"]
}

Note: npm install -g will NOT make the plugin available to OpenCode. OpenCode resolves plugins relative to its own config directory (~/.config/opencode/node_modules/).

How It Works

• Plugin (dist/bundle.js) registers the memory_* tools with OpenCode
• Python CLI (bin/agent-memory.py) handles all DB operations via subprocess
• Database is isolated per workspace at .opencode/memory/agent-memory.db (relative to OPENCODE_WORKDIR)
• Embeddings are generated locally via Ollama — no external API calls

Tools

| Tool | Description | |------|-------------| | memory_store | Store a new memory with category, scope, and importance | | memory_recall | Semantic search across memories using vector similarity | | memory_forget | Delete memories by ID, query, or scope | | memory_list | List memories by scope or category (no semantic search) | | memory_update | Update text, category, importance, or scope of an existing memory | | memory_stats | Get total count, breakdown by category and scope |

Scope Convention

Use <agent>:<scope-type> to namespace memories by agent and lifetime:

| Scope | When to use | |-------|-------------| | admin:global | Admin agent cross-session memories (default) | | vault-navigator:global | Specialist agent cross-session memories | | admin:session-2026-03-06 | Session-scoped memories for a single day |

Configuration

Create .opencode/memory-config.json in your workspace to override defaults:

{
  "dbPath": ".opencode/memory/agent-memory.db",
  "embedding": {
    "model": "bge-m3:latest",
    "ollamaUrl": "http://localhost:11434"
  },
  "retrieval": {
    "defaultLimit": 10,
    "minScore": 0.0
  },
  "cli": {
    "timeout_seconds": 30
  }
}

Memory Categories

| Category | Use for | |----------|---------| | preference | How the user likes things | | fact | Information and findings | | decision | Persistent choices and their rationale | | error | Bugs and failures | | learned | Lessons and patterns | | uncertain | Low-confidence observations |

Related

• opencode-distill — automatic memory distillation pipeline that converts accumulated memories into reusable agent skills. Requires opencode-agent-memory.

License

Apache-2.0