# @memorystack/opencode

> Persistent cognitive memory for [OpenCode](https://opencode.ai) — powered by [MemoryStack](https://memorystack.app)

Give your OpenCode AI agent the ability to **remember, learn, and grow** across sessions. No more repeating yourself — your agent knows your coding style, project architecture, and past decisions.

## Quick Start

**1. Install**

Add to your `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@memorystack/opencode"]
}
```

**2. Set API Key**

```bash
export MEMORYSTACK_API_KEY="mem_live_..."
```

Get your free key at [memorystack.app/dashboard](https://memorystack.app/dashboard)

**3. Start coding** — memory works automatically!

```bash
opencode
```

## What It Does

| Hook | Event | When | What Happens |
|---|---|---|---|
| 🟢 Session Start | `session.created` | You open OpenCode | Fetches your profile + project memories |
| 📝 Message Detection | `message.part.updated` | You send a message | Detects "remember this" signals |
| 🔧 Tool Tracking | `tool.execute.after` | AI edits/runs code | Compresses output to one-liners |
| 💤 Session Save | `session.idle` | AI finishes responding | Saves session summary to MemoryStack |
| 📦 Compaction | `session.compacting` | Context gets compacted | Injects memories to survive compaction |

### Bonus: Custom AI Tools

The AI can directly use two memory tools:

- **`memory_search`** — "What did we decide about authentication?"
- **`memory_save`** — "Remember: we use PostgreSQL with Drizzle ORM"

## Dual-Scope Memory

| Scope | What's Stored | Who Gets It |
|---|---|---|
| **Personal** | Your coding style, habits, preferences | Only you |
| **Project** | Architecture decisions, patterns, conventions | Your whole team |

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `MEMORYSTACK_API_KEY` | Your MemoryStack API key (required) | — |
| `MEMORYSTACK_DEBUG` | Enable debug logging | `false` |

## How It Works

```
Session Start → Profile Injection (your memories loaded)
     ↓
User Messages → Signal Detection ("remember this" → flagged)
     ↓
Tool Use → Activity Compression (edits/bash → one-liners)
     ↓
Context Compaction → Memory Injection (survive the cut)
     ↓
Session Idle → Smart Save (weighted summary → MemoryStack)
```

## License

MIT — [MemoryStack](https://memorystack.app)