opencode-metis 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# opencode-metis
+
+Persistent memory system for [OpenCode](https://opencode.ai) sessions. Captures observations, enables semantic search, and preserves context across compaction.
+
+## Features
+
+- **Observation capture** — Automatically records tool executions, decisions, and session summaries
+- **Semantic search** — Find relevant memories by meaning, not just keywords
+- **Compaction survival** — Saves and restores context when OpenCode compacts messages
+- **Quality checks** — TDD enforcement and file-length warnings on every edit
+- **Tool redirection** — Block or redirect specific tools via configuration
+- **Local-only** — All data stays on your machine at `~/.config/opencode/memory/`
+
+## Prerequisites
+
+- **Bun** >= 1.0.0
+- **ChromaDB** (optional) — for semantic vector search. Install via `pip install chromadb` or Docker.
+
+## Installation
+
+1. Install globally:
+
+   ```bash
+   bun add -g @metis/opencode
+   ```
+
+2. Run the setup command from your project root (or any directory):
+
+   ```bash
+   opencode-metis init
+   ```
+
+   This merges the required `plugin` and `mcp` entries into `~/.config/opencode/opencode.json`, copies framework files (agents, commands, skills) into `~/.config/opencode/`, and checks for ChromaDB availability. Existing config is backed up before modification.
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `opencode-metis init` | Configure `opencode.json` and copy framework files |
+| `opencode-metis start` | Start the memory worker and launch opencode |
+| `opencode-metis stop` | Stop the memory worker |
+
+## Configuration
+
+The memory system has its own optional config file at `~/.config/opencode/memory/settings.json` (separate from OpenCode's config). All fields have sensible defaults:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `workerPort` | number | `41777` | HTTP port for the worker daemon |
+| `workerBind` | string | `"127.0.0.1"` | Bind address for the worker |
+| `chromaDbUrl` | string | `"http://localhost:8000"` | ChromaDB server URL |
+| `recencyWindowDays` | number | `90` | Days to boost recent results |
+| `retentionDays` | number | `365` | Days before observations expire |
+| `tddEnabled` | boolean | `true` | Enforce test-file checks on edit |
+| `fileLengthWarn` | number | `300` | Line count warning threshold |
+| `fileLengthCritical` | number | `500` | Line count critical threshold |
+| `testFilePatterns` | string[] | `["*.test.ts", "*.spec.ts", "*_test.go", "test_*.py"]` | Glob patterns for test files |
+| `toolRedirectRules` | array | `[]` | Rules to deny or redirect specific tools |
+
+## Architecture
+
+The system has four components, each built as a separate bundle under `dist/`:
+
+- **CLI** (`dist/cli.cjs`) — Orchestrates init, start, and stop commands
+- **Plugin** (`dist/plugin.cjs`) — Hooks into OpenCode's lifecycle events to capture observations and enforce quality checks
+- **Worker** (`dist/worker.cjs`) — HTTP daemon that stores observations in SQLite, manages ChromaDB embeddings, and serves search queries
+- **MCP Server** (`dist/mcp-server.cjs`) — Exposes memory tools to the AI via the Model Context Protocol
+
+## MCP Tools
+
+Tools available to the AI through the MCP server:
+
+| Tool | Description |
+|------|-------------|
+| `search` | Semantic or keyword search across observations. Accepts `query`, optional `limit`, `type`, and `project` filters. |
+| `timeline` | Chronological context around an observation. Accepts `anchor` (ID, session ID, timestamp, or query) with `depth_before`/`depth_after`. |
+| `get_observations` | Fetch full details for specific observation IDs. |
+| `save_memory` | Save a new observation with `text`, optional `title` and `project`. |
+| `decisions` | Search decision-type observations. Optional `query` and `project` filters. |
+| `changes` | Get recent change-type observations. Optional `project` and `limit`. |
+
+The plugin also registers `memory_search` and `memory_save` as custom tools directly in OpenCode.
+
+## Plugin Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `session.created` | Injects relevant memory context at session start |
+| `tool.execute.before` | Enforces tool redirect rules (deny/redirect) before execution |
+| `tool.execute.after` | Captures tool executions as observations |
+| `session.idle` | Saves session summaries when the session goes idle |
+| `experimental.session.compacting` | Saves active plan and task state before compaction |
+| `session.compacted` | Restores memory context after compaction |
+| `file.edited` | Checks for missing test files and warns on file length |
+
+## Local Development
+
+### Setup
+
+Build and link the plugin into OpenCode's config directory using [GNU Stow](https://www.gnu.org/software/stow/):
+
+```bash
+bun install
+bun run build
+bun run link        # stows into ~/.config/opencode/plugins/
+```
+
+Then add the MCP server to `~/.config/opencode/opencode.json` (no `plugin` entry needed — stow handles that):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mem-search": {
+      "type": "local",
+      "command": ["bun", "run", "/absolute/path/to/opencode-metis/dist/mcp-server.cjs"]
+    }
+  }
+}
+```
+
+To remove the symlink:
+
+```bash
+bun run unlink      # unstow
+```
+
+### Commands
+
+```bash
+bun test          # Run tests
+bun run build     # Build all four bundles
+bun run lint      # ESLint + Prettier
+bun run typecheck # TypeScript type checking
+bun run dev       # Watch mode for worker
+```
+
+## License
+
+MIT