# Installing opencode-mnemosyne

## Prerequisites

1. **Mnemosyne gateway** running (`mnemosyne --no-launch --port 8080`)
2. **opencode** installed and configured
3. **OAuth authenticated** (`mnemosyne --login`)

## Quick Install (Local Development)

```bash
# From the contextmanager project root
cd opencode-plugin
npm install && npm run build

# Register as a local plugin in opencode
# Add to your ~/.config/opencode/opencode.json:
```

```json
{
  "plugin": [
    "oh-my-opencode@latest",
    "file:///var/home/joey/Projects/contextmanager/opencode-plugin"
  ]
}
```

## Configuration

The plugin is configured via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MNEMOSYNE_HOST` | `127.0.0.1` | Gateway host |
| `MNEMOSYNE_PORT` | `8080` | Gateway port |
| `MNEMOSYNE_LOG_LEVEL` | `info` | Log level: silent, error, info, debug |

## Usage

### 1. Start the Mnemosyne Gateway

```bash
cd ~/Projects/contextmanager
mnemosyne --no-launch --port 8080
```

### 2. Start opencode normally

The plugin automatically:
- Routes Anthropic API calls through the gateway (via `baseURL` injection)
- Enriches compaction prompts with memory context
- Provides `mnemosyne_status` and `mnemosyne_query` tools

### 3. Custom Tools

Once loaded, the LLM has access to two new tools:

- **`mnemosyne_status`** — Show memory state (objects, tokens, evictions, faults)
- **`mnemosyne_query`** — Query the backing store for previously evicted context

### How It Works

```
opencode → plugin (config hook injects baseURL) → Mnemosyne gateway → Anthropic API
                                                        ↕
                                              Object Store (backing store)
                                              Helper LLM (Haiku 4.5)
                                              Fidelity Manager
                                              Segmenter + Embedder
```

The plugin's `config` hook dynamically sets `provider.anthropic.options.baseURL` to
the gateway URL. This means all Anthropic API calls are transparently proxied through
Mnemosyne, which:

1. **Segments** conversation into semantic objects
2. **Stores** objects with embeddings in the backing store
3. **Compresses** old objects via multi-fidelity degradation (L0→L1→L2→L3→L4)
4. **Retrieves** evicted content on demand via micro-faults
5. **Detects** topic shifts and reclassifies goals

### Graceful Degradation

If the gateway is not running, the plugin silently skips all hooks. opencode works
normally with no proxy — zero impact on the user experience.

## npm Install (once published)

```bash
# In your opencode.json
{
  "plugin": [
    "opencode-mnemosyne@latest"
  ]
}
```

Then set `MNEMOSYNE_PORT=8080` in your environment.