mempalace-go

Give your AI a memory. No API key required.

A Go implementation of MemPalace — a memory system for AI assistants that implements the Model Context Protocol (MCP) over stdio.

Overview

mempalace-go provides a single, portable binary with no Python dependencies or persistent daemon processes. It exposes memory operations as MCP tools that AI clients (like Claude Desktop, Cursor, or other MCP-compatible editors) can invoke to store, search, and recall contextual information.

Key Features

• Portable Binary: Single executable, no runtime dependencies
• MCP Server: Stdio-based JSON-RPC protocol for AI client integration
• Vector Search: Semantic memory retrieval using ONNX embeddings (hugot)
• Knowledge Graph: SQLite-based entity relationship tracking with temporal validity
• WAL-based Storage: Write-ahead log for durable memory operations
• CLI Tools: Project mining, search, repair, and palace management

Architecture

┌─────────────┐     MCP/JSON-RPC     ┌───────────────┐
│   MCP      │◄────────────────────►│  mempalace-go │
│   Client   │     stdio            │    server     │
└─────────────┘                     └───────┬───────┘
                                            │
              ┌─────────────────────────────┼──────────────────────────┐
              │                             │                          │
         ┌────▼──────┐              ┌───────▼──────┐          ┌───────▼────────┐
         │  Hugot    │              │   Memory     │          │  Knowledge     │
         │  (ONNX)   │              │   Stack      │          │  Graph (SQLite)│
         └────┬──────┘              └───────▲──────┘          └────────────────┘
              │                             │
         ┌────▼────────────┐          ┌─────▼────┐
         │ Embedding Model │          │ Vector   │
         │ all-MiniLM-L6   │          │ Store    │
         │ (feature extr.) │          │(govector)│
         └─────────────────┘          └──────────┘

Embedding Pipeline

mempalace-go uses hugot for ONNX-based embeddings — no external processes or llamafiles are required. Models are downloaded once and run natively in Go:

1. Text input → hugot feature extraction pipeline
2. ONNX runtime produces 384-dimensional embeddings
3. Vector store (govector with HNSW index) handles similarity search

Installation

Prerequisites

• Go 1.26.2 or later
• ONNX embedding model (auto-downloaded by hugot on first run)

Building

Standard Build (pure Go, no CGo)

go build -o mempalace-go .
# or
make build

No native dependencies required. Uses hugot's pure-Go backend.

ORT Build (Apple Silicon acceleration)

The ORT build enables ONNX Runtime with the CoreML execution provider on darwin/arm64, which allows embedding inference to run on the GPU or ANE where the model graph is supported.

Step 1: Download libtokenizers.a

The ORT backend requires libtokenizers.a, a pre-built Rust library for fast BERT tokenization. Download the darwin/arm64 build once:

mkdir -p ~/lib
curl -fSL https://github.com/daulet/tokenizers/releases/download/v1.26.0/libtokenizers.darwin-aarch64.tar.gz \
    | tar -xz -C ~/lib/

Step 2: Build with ORT tag

export CGO_LDFLAGS="-L${HOME}/lib"
make build-ort
# equivalent to: go build -tags ORT ./...

Step 3 (optional): Install system-wide to avoid the env var

If you prefer not to set CGO_LDFLAGS every time, copy the library to a standard system path:

sudo cp ~/lib/libtokenizers.a /usr/local/lib/libtokenizers.a
# Then: make build-ort  (no CGO_LDFLAGS needed)

Makefile targets

Configuration

mempalace-go uses a config file at ~/.mempalace/config.json:

{
  "palace_path": "~/.mempalace/palace",
  "model_name": "sentence-transformers/all-MiniLM-L6-v2",
  "models_dir": "~/.mempalace/models",
  "collection_name": "default"
}

Configuration Options

Quick Start

1. Initialize a Palace

./mempalace-go init ~/.my-palace

2. Run as MCP Server

./mempalace-go server

3. Mine Project Files

./mempalace-go mine /path/to/project --mode projects

4. Search Memories

./mempalace-go search "authentication flow"

CLI Commands

Core Commands

Maintenance Commands

Advanced Commands

Global Flags

• --palace: Override palace path from config

MCP Tools

When running as an MCP server, mempalace-go exposes the following tools:

Memory Operations

Palace Management

Drawer Operations

Knowledge Graph

Graph Navigation

Agent Diary (AAAK)

Advanced Search

LongMemEval Benchmark Results

The bench longmemeval command runs the LongMemEval session-retrieval benchmark (500 questions, ~49 sessions each). Results below are for the session granularity, raw mode, top-50 retrieval, on Apple M-series (pure-Go GoMLX backend, no CoreML).

Accuracy (500 questions)

Embedding Speed

Key optimisations applied:

1. Cross-question session cache — unique session texts across all 500 questions are embedded once upfront. The 18,362 unique sessions are split across 4 parallel workers (each with its own hugot/GoMLX instance). After the cache is warm, each buildCorpus call is a pure in-memory map lookup (~100 ms for vector store writes vs 8.3 s of GEMM before).

2. Rune-based truncation — texts are truncated to 400 Unicode code-points before embedding. Word-count limits fail on long URLs and Unicode math symbols (a single "word" can produce hundreds of subword tokens, crashing GoMLX's shape-specific JIT graphs). At 400 runes, the worst case (all ASCII URLs) produces ≤ 400 tokens, safely under the 512-position limit.

3. Chunk size 32 → 64 — hugot's RunPipeline is called with batches of 64 texts instead of 32, halving the number of forward-pass invocations per question.

mempalace-go/
├── cmd/
│   ├── cli/              # CLI command implementations
│   │   ├── main.go       # Root command (init, mine, search, etc.)
│   │   ├── bench.go      # Benchmark command
│   │   ├── compress.go   # Compress command
│   │   ├── hook.go       # Hook command
│   │   ├── instructions.go # Instructions command
│   │   ├── mcp.go        # MCP server command
│   │   ├── onboard.go    # Onboarding command
│   │   └── split.go      # Split command
│   └── server/           # Standalone MCP server
│       └── main.go       # Server entry point
├── pkg/
│   ├── mcp/              # MCP server implementation
│   └── wal/              # Write-ahead log
├── internal/
│   ├── config/           # Configuration management
│   ├── embedder/         # ONNX embedding models (hugot)
│   ├── layers/           # Memory stack operations
│   ├── miner/            # Project/conversation mining
│   ├── palace/           # Palace graph structure
│   ├── search/           # Semantic search
│   ├── kg/               # Knowledge graph (SQLite)
│   ├── diary/            # Agent diary (AAAK)
│   ├── extractor/        # Memory extraction
│   ├── dialect/          # Text dialect handling
│   ├── entity/           # Entity detection
│   └── sanitizer/        # Input sanitization
├── storage/
│   └── govector/         # Vector storage backend
├── integration/          # Integration tests
├── benchmarks/           # Performance benchmarks
├── docs/                 # Documentation
└── main.go               # Entry point

Storage Model

• Vector Store: vectors.db (govector with HNSW index)
• Knowledge Graph: knowledge_graph.sqlite3 (temporal RDF-style triples)
• WAL Directory: wal/ (write-ahead log for durability)
• Diary: diary/ (agent-specific AAAK entries)

Embedding Models

mempalace-go uses hugot for ONNX-based embeddings. The default model is sentence-transformers/all-MiniLM-L6-v2 which produces 384-dimensional vectors.

Models are auto-downloaded from Hugging Face on first use and cached in the configured models_dir (default: ~/.mempalace/models).

Testing

# Run unit tests
go test ./...

# Run integration tests
go test -v ./integration/ -run TestMCP

# Run benchmarks
go test -bench=. ./benchmarks/

# Or use the integration test runner
./run_integration_tests.sh

Integration with AI Clients

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "mempalace": {
      "command": "/path/to/mempalace-go",
      "args": ["server"]
    }
  }
}

Cursor / VS Code

Configure in your MCP settings to point to the mempalace-go binary with the server argument.

AAAK Dialect

mempalace-go supports the AAAK (Aphantix Abstraction Annotating Kit) dialect for structured symbolic summaries:

• Entity Codes: 3-letter uppercase codes (e.g., KAI, MAX, PRI)
• Topics: Frequency-based with proper noun boosting
• Emotion Codes: vul, joy, fear, trust, grief, wonder, rage, etc.
• Flag Codes: DECISION, ORIGIN, CORE, PIVOT, TECHNICAL

Use mempalace-go get_aaak_spec to retrieve the full specification.

Dependencies

• cobra - CLI framework
• viper - Configuration management
• hugot - ONNX embedding runtime
• govector - Vector storage with HNSW
• sqlite - Pure Go SQLite driver

License

MIT — see LICENSE.

Credits

This is a Go port of the original mempalace Python project by milla-jovovich. The port provides a simpler deployment model with no Python dependencies or daemon processes.