# opencode-agent-memory

Persistent, semantic memory for [OpenCode](https://opencode.ai) 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](https://lancedb.com) vector database, with embeddings generated by a local [Ollama](https://ollama.ai) 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:**

```bash
pip install lancedb pyarrow
```

Pull the embedding model:

```bash
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

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

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

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

### Per-workspace — tools available in one workspace only

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

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

```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:

```json
{
  "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](https://github.com/ChiaBoon/opencode-distill)** — automatic memory distillation pipeline that converts accumulated memories into reusable agent skills. Requires `opencode-agent-memory`.

---

## License

Apache-2.0