memoryhub

MCP server for persistent memory using Qdrant vector store.

Stores text memories with LLM-generated embeddings and retrieves them via semantic search.

Install

npm install @taraksh011/memoryhub

Or run directly:

npx @taraksh011/memoryhub

Related MCP server: mcp-server-qdrant

Quick Start

# Start Qdrant (see docs/install-qdrant.md for help)
docker run -p 6333:6333 qdrant/qdrant

# Set API credentials (or use config file)
export LLM_BASE=https://api.openai.com/v1
export LLM_KEY=sk-...
export LLM_MODEL=gpt-4o-mini

# Start memoryhub in stdio mode (for MCP clients)
memoryhub

# Or auto-start Qdrant + serve in one step
memoryhub bootstrap

Prerequisites

Memory Hub needs three things:

1. Qdrant — vector database (install guide)

2. LLM API — extracts facts from text (e.g. OpenAI, Anthropic, local Ollama)

3. Embedding API — converts text to vectors (e.g. OpenAI text-embedding-3-small, local Ollama)

If your LLM and embedding APIs are the same provider, you can set just the LLM values and reuse them (see config example below).

Configuration

Configuration is checked in this order: config file → environment variable → default.

Config file

Create a memoryhub.json in your project root, or config.json in the memoryhub directory (~/.memoryhub/ by default):

{
  "qdrant": {
    "url": "http://localhost:6333"
  },
  "collection": "memories",
  "vector_size": 768,
  "llm": {
    "model": "gpt-4o-mini",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
  },
  "embedder": {
    "model": "text-embedding-3-small",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
  }
}

If your embedder matches your LLM provider, you can omit embedder — it falls back to the llm settings.

Environment variables

Short names (LLM_BASE, LLM_KEY) are preferred. Long names (LLM_BASE_URL, LLM_API_KEY) are supported for backward compatibility.

Memory Scopes

Memories can be global or project-scoped:

• Omit project → memory is global (visible to all searches)

• Pass project="my-repo" → memory is scoped to that project

• Search/list without project → returns all memories (global + all projects)

• Search/list with project="my-repo" → returns only that project's memories

Use scopes to keep memories isolated per repo, per feature, or any other boundary.

MCP Tools

Config changes via update_config are in-memory only — lost on restart. Use config file or env vars for permanent changes.

Retry

LLM and embedding API calls retry up to 3 times on transient errors (rate limits, server errors) with exponential backoff.

CLI

Transport Modes

• stdio (default): Connect MCP clients via stdin/stdout

• HTTP/SSE: memoryhub serve starts an HTTP server on port 9876

Build

pnpm build       # type-check + bundle
pnpm typecheck   # type-check only
pnpm dev         # run with tsx

License

MIT