opencode-memory

Local memory system for OpenCode with semantic + keyword hybrid search.

Features

• Hybrid Search: Combines vector similarity (semantic) with full-text search (keyword) for accurate results
• Multiple Embedding Providers: Supports local models (via node-llama-cpp), OpenAI, and Gemini
• Incremental Sync: Only re-indexes changed files for efficiency
• OpenCode Plugin: Seamlessly integrates with OpenCode as a plugin
• CLI Interface: Command-line tools for status, indexing, and search

Installation

npm install opencode-memory

Configuration

Create .opencode/memory.json:

{
  "embedding": {
    "provider": {
      "kind": "auto"
    }
  }
}

Provider Options

Auto (default) - Automatically selects the best available provider:

{ "embedding": { "provider": { "kind": "auto" } } }

Local - Uses local GGUF models via node-llama-cpp:

{
  "embedding": {
    "provider": {
      "kind": "builtin",
      "name": "local",
      "options": {
        "modelPath": "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
      }
    }
  }
}

OpenAI:

{
  "embedding": {
    "provider": {
      "kind": "builtin",
      "name": "openai",
      "options": {
        "apiKey": "your-api-key",
        "model": "text-embedding-3-small"
      }
    }
  }
}

Gemini:

{
  "embedding": {
    "provider": {
      "kind": "builtin",
      "name": "gemini",
      "options": {
        "apiKey": "your-api-key",
        "model": "embedding-001"
      }
    }
  }
}

Usage

As Plugin

Add to opencode.json:

{
  "plugin": ["opencode-memory"]
}

The plugin automatically:

• Indexes memory files on startup
• Provides memory_search, memory_read, memory_status, and memory_write tools
• Injects relevant context into chat messages

CLI

# Check status
npx opencode-memory status

# Index memory files
npx opencode-memory index

# Search
npx opencode-memory search "architecture"

# Force full reindex
npx opencode-memory index --force

Memory Files

Create MEMORY.md or memory/*.md files in your project root. These files are automatically indexed and searchable.

Example MEMORY.md:

# Project Memory

## Architecture
This project uses a layered architecture with clear separation of concerns.

## API Design
- RESTful endpoints
- JSON request/response
- Authentication via JWT

## Known Issues
- Performance bottleneck in data processing pipeline

API

MemoryManager

import { MemoryManager } from 'opencode-memory';
import { createLocalEmbeddingProvider } from 'opencode-memory/providers';

const provider = await createLocalEmbeddingProvider({}, context);
const manager = new MemoryManager({
  dbPath: './memory.db',
  cwd: process.cwd(),
  provider
});

// Initialize
await manager.init();

// Sync memory files
await manager.sync({ force: true });

// Search
const results = await manager.search('query', { maxResults: 5 });

// Read file
const content = manager.readFile('MEMORY.md');

// Get status
const status = manager.getStatus();

// Cleanup
await manager.close();

License

MIT