opencode-qdrant-memory

Persistent memory for OpenCode AI agents — an MCP server that stores and retrieves knowledge using Qdrant vector search and Ollama embeddings.

When OpenCode learns something about a codebase during a session, it can save it as a memory. Next session, it recalls what it learned — no more re-discovering the same architecture decisions.

How it works

OpenCode ──stdio──▶ memory-ql (MCP server) ──▶ Ollama (embeddings)
                                                    │
                                                    ▼
                                               Qdrant (vector DB)

Prerequisites

| Service | Default | Notes | |---------|---------|-------| | Ollama | http://localhost:11434 | Any embedding model (nomic-embed-text, etc.) | | Qdrant | http://localhost:6333 | Vector database, auto-creates collection on first run |

Quick start

1. Add to OpenCode config

In your opencode.json:

{
  "mcp": {
    "memory-ql": {
      "type": "local",
      "command": ["npx", "-y", "@axelfooley/opencode-qdrant-memory"],
      "enabled": true
    }
  }
}

That's it. OpenCode will download and run the server automatically when it starts.

2. Tell OpenCode to use it

Add this to your AGENTS.md or .cursorrules:

Before starting a task, call `search_knowledge` to recall what you already know.
After learning something important, call `store_knowledge` to persist it.

MCP Tools

store_knowledge

Save a piece of knowledge as a vector memory. Call this after discovering:

• Codebase architecture and component relationships
• User preferences and conventions
• Design decisions and their rationale
• API endpoints and their behavior
• Configuration idiosyncrasies

Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | text | string | ✅ | The knowledge content to remember | | project | string | ❌ | Scope to a project name (e.g. "my-app") | | tags | string[] | ❌ | Categories like architecture, decision, convention |

Example response:

{
  "status": "stored",
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "project": "my-app"
}

search_knowledge

Search stored memories by semantic similarity. The most relevant results return first, ranked by cosine similarity.

Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | query | string | ✅ | Natural language query (e.g. "how do we handle auth") | | project | string | ❌ | Filter to a specific project | | tags | string[] | ❌ | Filter by one or more tags | | limit | number | ❌ | Max results (default: 10, max: 5000) |

Example response:

{
  "query": "authentication flow",
  "results_count": 3,
  "results": [
    {
      "rank": 1,
      "score": 0.92,
      "memory_id": "550e8400-...",
      "text": "Auth uses JWT tokens stored in httpOnly cookies...",
      "project": "my-app",
      "tags": ["architecture", "security"],
      "timestamp": "2026-05-02T11:30:00.000Z"
    }
  ]
}

list_knowledge

Browse stored memories, optionally filtered by project or tags.

Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | project | string | ❌ | Filter by project | | tags | string[] | ❌ | Filter by tags | | limit | number | ❌ | Max results (default: 50, max: 5000) | | offset | number | ❌ | Pagination offset (default: 0) |

delete_knowledge

Remove a memory by its ID.

Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | memory_id | string | ✅ | The memory ID from a store/search/list response |

Configuration

All settings via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | QDRANT_URL | http://localhost:6333 | Qdrant server URL | | OLLAMA_URL | http://localhost:11434 | Ollama server URL | | EMBEDDING_MODEL | nomic-embed-text | Ollama embedding model name | | EMBEDDING_DIM | 768 | Embedding dimension (must match model) | | COLLECTION_NAME | opencode_memory | Qdrant collection name |

Example with overrides:

QDRANT_URL=http://localhost:6333 \
OLLAMA_URL=http://localhost:11434 \
EMBEDDING_MODEL=qwen3-embedding \
EMBEDDING_DIM=1024 \
npx @axelfooley/opencode-qdrant-memory

Architecture

┌─────────────┐     stdio      ┌──────────────────┐
│  OpenCode    │◄─────────────►│   memory-ql      │
│  (agent)     │   MCP JSON    │   (MCP server)   │
└─────────────┘                └────────┬─────────┘
                                        │
                               HTTP POST│ /api/embeddings
                                        ▼
                               ┌──────────────────┐
                               │     Ollama        │
                               │  (embeddings)     │
                               └────────┬─────────┘
                                        │
                                        ▼
                               ┌──────────────────┐
                               │     Qdrant        │
                               │  (vector store)   │
                               └──────────────────┘

• Memory model: 100% local. No data leaves your network.
• Embeddings: Generated by Ollama on every write and every search.
• Vector search: Cosine similarity on Qdrant, with payload filtering by project and tags.
• Scoping: The project field isolates memories between different codebases.

Running standalone (without OpenCode)

npx @axelfooley/opencode-qdrant-memory

The server listens on stdio (standard MCP transport). You can connect any MCP-compatible client, or test with a simple script:

# Test store
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"store_knowledge","arguments":{"text":"Hello from memory-ql!","project":"test","tags":["demo"]}}}' | npx @axelfooley/opencode-qdrant-memory

License

MIT