Goldie 🐕

A multi-agent memory MCP server written in Go that runs locally on your machine. Goldie stores typed, named memories in a shared SQLite vector index so multiple agents (Claude, Codex, etc.) can remember, recall, update_memory, and forget from one pool — replacing per-project MEMORY.md files with a backend they can all share.

Features

• Typed memories: Each memory has a type (user, feedback, project, reference, opinion, idea, todo, reminder), a unique name, optional description, body, agent, and source
• Shared pool: Scope is a SQLite file — point any number of agents at the same DB and they share memory
• Semantic recall: Filtered KNN over chunk embeddings; recall returns the parent memory plus the matched excerpt
• Graph recall: Memories get graph nodes; Goldie harvests stable concepts and facets from names and sources so broad recalls can return grouped context like Acme -> Acme Cloud
• Multiple embedding backends: MiniLM (local via ONNX Runtime) or Ollama (any embedding model)
• File ingestion: index_file / index_directory import files as reference memories named by absolute path (checksum-gated upsert)
• Async job queue: Long-running indexing operations and graph harvest/backfill jobs run in the background with progress tracking

Graph Recall

Goldie v4 adds a graph layer beside semantic search. Each memory has a memory node, and Goldie harvests concept nodes from descriptive memory names and file/source paths. Shared prefixes become facets through part_of edges, so memories like acme_cloud_passwordless_auth and acme_cloud_pricing can group under Acme Cloud, which itself belongs to Acme.

recall remains backward-compatible: it still returns the flat results list. When a query resolves to a concept, the response also includes concept_recall with the matched concept, facet groups, and directly attached memories. Clients that ignore concept_recall continue to work.

When a query contains a known concept or facet, recall can also include automatic_recall: an inspectable graph path with branch scores, convergence status, and a stop reason. Ambiguous queries fall back instead of forcing a precise answer.

Graph harvest runs asynchronously. remember creates the memory and memory node, then queues a debounced graph_harvest job so concept extraction does not hold the write lock. Existing databases are backfilled through the same job queue.

Optional graph hints can reinforce the harvested graph. about attaches a memory to concept labels, aliases adds alternate names to the memory node, and links adds explicit graph edges as {relation, target} objects. Hint-origin edges and aliases are preserved across harvest.

Graph inspection and cleanup tools are available for maintenance: list_nodes, get_node (aliased as map), and explain_recall show what the graph is doing; link_memory manually attaches a memory to a concept; merge_nodes merges duplicate concepts with collision-safe edge and alias movement.

Upgrading Existing Databases

Goldie v4 upgrades existing SQLite databases in place. On first launch it adds the graph tables, memory node references, and concept-node vector index. Existing memories keep working immediately through normal vector recall while graph backfill runs asynchronously.

Before first v4 launch, back up the database if it contains important memories:

cp ~/.local/share/goldie/index.db ~/.local/share/goldie/index.db.v3-backup

Backfill jobs use the same async queue as file indexing. Use list_jobs and job_status to inspect progress.

Requirements

MiniLM Backend (requires ONNX Runtime)

# macOS
brew install onnxruntime

# Ubuntu/Debian
sudo apt install libonnxruntime-dev

# Fedora/RHEL
sudo dnf install onnxruntime-devel

# Arch Linux
sudo pacman -S onnxruntime

Ollama Backend

If you want to use Ollama instead of MiniLM, you only need Ollama installed:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Pull an embedding model
ollama pull nomic-embed-text

Skip the ONNX Runtime installation below if you only plan to use Ollama.

Installation

From Releases (recommended)

Download a pre-built binary from the releases page:

| Platform | Binary | |----------|--------| | macOS (Apple Silicon) | goldie-mcp-darwin-arm64 | | macOS (Intel) | goldie-mcp-darwin-amd64 | | Linux (x86_64) | goldie-mcp-linux-amd64 | | Linux (ARM64) | goldie-mcp-linux-arm64 |

# Example for macOS Apple Silicon
curl -LO https://github.com/srfrog/goldie-mcp/releases/latest/download/goldie-mcp-darwin-arm64
chmod +x goldie-mcp-darwin-arm64
mv goldie-mcp-darwin-arm64 ~/bin/goldie-mcp

The release binaries are ad-hoc codesigned for macOS and include the MiniLM model, so no additional downloads are required.

Build from Source

Requires Go 1.22+, CGO enabled, and Git LFS (the model file is stored with LFS):

git lfs install  # if not already configured
git clone https://github.com/srfrog/goldie-mcp
cd goldie-mcp
make build

Configuration

Command Line Flags

| Flag | Description | Default | |------|-------------|---------| | -b | Embedding backend: minilm or ollama | minilm | | -l | Log file path | stderr |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GOLDIE_DB_PATH | Path to SQLite database | ~/.local/share/goldie/index.db | | GOLDIE_JOURNAL_MODE | SQLite journal_mode PRAGMA. Default is safe for cloud-synced storage. Set WAL for local-only DBs to enable read-during-write concurrency | DELETE | | ONNXRUNTIME_LIB_PATH | Path to libonnxruntime shared library (MiniLM only) | Auto-detected | | OLLAMA_HOST | Ollama API base URL (Ollama only) | http://localhost:11434 | | OLLAMA_EMBED_MODEL | Ollama embedding model name (Ollama only) | nomic-embed-text | | OLLAMA_EMBED_DIMENSIONS | Custom model dimensions (Ollama only) | Auto-detected for known models |

Supported Ollama Embedding Models

| Model | Dimensions | Notes | |-------|------------|-------| | nomic-embed-text | 768 | Default, good general purpose | | mxbai-embed-large | 1024 | Higher quality, slower | | all-minilm | 384 | Same as MiniLM backend |

For other models, set OLLAMA_EMBED_DIMENSIONS to the model's output dimensions.

Usage with Claude Code

With MiniLM (default)

claude mcp add -s user -e GOLDIE_DB_PATH=~/.local/share/goldie/index.db goldie /path/to/goldie-mcp

Note: ONNXRUNTIME_LIB_PATH is optional if the library is in a standard location.

With Ollama

claude mcp add -s user -e GOLDIE_DB_PATH=~/.local/share/goldie/index.db goldie /path/to/goldie-mcp -- -b ollama

Note: Make sure Ollama is running (ollama serve) before starting Claude Code.

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

With MiniLM (default)

{
  "mcpServers": {
    "goldie": {
      "type": "stdio",
      "command": "/path/to/goldie-mcp",
      "env": {
        "GOLDIE_DB_PATH": "/home/user/.local/share/goldie/index.db"
      }
    }
  }
}

With Ollama

{
  "mcpServers": {
    "goldie": {
      "type": "stdio",
      "command": "/path/to/goldie-mcp",
      "args": ["-b", "ollama"],
      "env": {
        "GOLDIE_DB_PATH": "/home/user/.local/share/goldie/index.db",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

Usage with OpenAI Codex

Add to your Codex configuration (~/.codex/config.toml):

With MiniLM (default)

[mcp_servers.goldie]
command = "/path/to/goldie-mcp"

[mcp_servers.goldie.env]
GOLDIE_DB_PATH = "/home/user/.local/share/goldie/index.db"
ONNXRUNTIME_LIB_PATH = "/path/to/libonnxruntime.so"

Note: ONNXRUNTIME_LIB_PATH is optional if the library is in a standard location. Homebrew will install it to /opt/homebrew/lib/libonnxruntime.dylib on macOS. In Linux, find it with ldconfig -p | grep onnxruntime.

With Ollama

[mcp_servers.goldie]
command = "/path/to/goldie-mcp"
args = ["-b", "ollama"]

[mcp_servers.goldie.env]
GOLDIE_DB_PATH = "/home/user/.local/share/goldie/index.db"
OLLAMA_EMBED_MODEL = "nomic-embed-text"

Memory Model

Goldie's index is a flat pool of memories. Each memory has these fields:

| Field | Required | Notes | |---------------|----------|-----------------------------------------------------------------------| | name | yes | Unique within the database. Names collide → remember fails (see below) | | type | yes | One of: user, feedback, project, reference, opinion, idea, todo, reminder | | body | yes | The full content. Chunked under the hood for embedding-level recall | | description | no | One-line summary; participates in semantic recall | | agent | no | The agent that created the memory (e.g. claude-opus-4-7, codex) | | source | no | Where the memory came from (file path, editor, URL) |

Sharing. "Scope" is just the SQLite file. Multiple agents pointed at the same GOLDIE_DB_PATH share the same pool of memories — there is no per-agent isolation. Use agent and source to filter on read/delete.

Naming and conflicts. Names must be unique. remember is strict — no upsert. If two agents try to create the same name, the second one gets an error and is expected to recall the existing memory and call update_memory (or pick a different name).

Update semantics. Name is immutable. update_memory accepts patches for type/description/body/source/agent; changes to description or body re-embed the chunks.

File ingestion. index_file / index_directory are the one exception to the no-upsert rule. They import files as memories of type=reference, with name = source = <absolute path>. Re-indexing the same path skips when the SHA-256 checksum matches and replaces the body when it doesn't.

Graph hints. Plain remember is enough for v4 graph recall: Goldie harvests concepts from memory names and file/source paths. Optional about, aliases, and links hints add user-provided graph structure when the name alone is not enough. Hinted graph data is preserved across future harvest runs.

Available Tools

remember

Create a new memory. Fails if name is already in use — recall it and use update_memory instead.

Parameters:

• name (required): Unique identifier (e.g., feedback_testing)
• type (required): One of user, feedback, project, reference, opinion, idea, todo, reminder
• body (required): Full content
• description (optional): One-line summary
• agent (optional): Agent that created the memory
• source (optional): Where the memory was generated
• about (optional): concept labels this memory is about
• aliases (optional): aliases for this memory node
• links (optional): graph links as {relation, target} objects

recall

Hybrid recall over memories. Always returns the backward-compatible flat results list with the best matched excerpt for each memory. When the query resolves to graph concepts, the response may also include grouped concept_recall and inspectable automatic_recall metadata. Filter by type, agent, or source to narrow scope.

Parameters:

• query (required): Topic or question
• limit (optional): Max results (default 5, max 20)
• include_body (optional): Include full memory bodies instead of metadata plus excerpts
• type, agent, source (optional): Filters

get_memory

Fetch a single memory's full record, including body, by