MemPalace Go
A Go implementation of [MemPalace](https://github.com/milla-jovovich/mempalace) β a memory system for AI assistants that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) over stdio.
Ask AI about MemPalace Go
Powered by Claude Β· Grounded in docs
I know everything about MemPalace Go. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
- Text input β hugot feature extraction pipeline
- ONNX runtime produces 384-dimensional embeddings
- 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
| Target | Description |
|---|---|
make build | Pure Go build, no CGo |
make build-ort | ORT + CoreML build (requires libtokenizers.a) |
make test | Run all tests (pure Go) |
make test-ort | Run all tests with ORT backend |
make bench-perf | Run embedding/storage timing benchmark (pure Go) |
make bench-perf-ort | Run benchmark with ORT + CoreML |
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
| Field | Description | Default |
|---|---|---|
palace_path | Path to the memory palace data | ~/.mempalace/palace |
model_name | Hugging Face model name for embeddings | sentence-transformers/all-MiniLM-L6-v2 |
models_dir | Directory for cached ONNX models | ~/.mempalace/models |
collection_name | Collection identifier | default |
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
| Command | Description |
|---|---|
mempalace-go init [dir] | Initialize a new memory palace |
mempalace-go mine [dir] --mode [projects|convos] | Mine files or conversations into the palace |
mempalace-go search [query] | Search memories by query |
mempalace-go wake-up --wing [wing] | Show L0 + L1 context for a wing |
mempalace-go status | Show palace configuration status |
Maintenance Commands
| Command | Description |
|---|---|
mempalace-go repair | Rebuild palace vector index from WAL files |
mempalace-go compress | Compress palace storage |
mempalace-go split | Split palace data |
mempalace-go hook | Manage hooks |
Advanced Commands
| Command | Description |
|---|---|
mempalace-go mcp | Run MCP server (alias for server) |
mempalace-go instructions | Show usage instructions |
mempalace-go onboard | Interactive onboarding |
mempalace-go bench | Run benchmarks |
Global Flags
--palace: Override palace path from config
MCP Tools
When running as an MCP server, mempalace-go exposes the following tools:
Memory Operations
| Tool | Description | Parameters |
|---|---|---|
search | Search memories by query | query, wing (optional), room (optional) |
wake | Wake up memory with wing context | wing (optional) |
recall | Recall memories from wing/room | wing, room, count (default: 10) |
Palace Management
| Tool | Description | Parameters |
|---|---|---|
mempalace_status | Get palace status and overview | None |
mempalace_list_wings | List all wings with drawer counts | None |
mempalace_list_rooms | List rooms within a wing | wing (optional) |
mempalace_get_taxonomy | Get full wing β room β count tree | None |
Drawer Operations
| Tool | Description | Parameters |
|---|---|---|
mempalace_add_drawer | Add content to a wing/room | content, wing, room, source (optional) |
mempalace_delete_drawer | Delete a drawer by ID | id |
mempalace_check_duplicate | Check if content already exists | content, wing (optional), room (optional) |
Knowledge Graph
| Tool | Description | Parameters |
|---|---|---|
kg_query | Query knowledge graph for entity relationships | entity, as_of (optional), direction (default: "outgoing") |
mempalace_kg_add | Add fact to knowledge graph | subject, predicate, object, valid_from, valid_to, confidence |
mempalace_kg_invalidate | Mark facts as ended | subject, predicate, object, valid_to |
mempalace_kg_timeline | Get chronological entity story | entity |
mempalace_kg_stats | Get knowledge graph statistics | None |
Graph Navigation
| Tool | Description | Parameters |
|---|---|---|
mempalace_traverse | Walk the palace graph from a room | room, max_hops (default: 3) |
mempalace_find_tunnels | Find rooms bridging two wings | wing_a, wing_b |
mempalace_graph_stats | Get palace graph connectivity | None |
Agent Diary (AAAK)
| Tool | Description | Parameters |
|---|---|---|
mempalace_diary_write | Write AAAK diary entry for a specialist agent | agent, content, wing (optional) |
mempalace_diary_read | Read recent diary entries | agent (optional), wing (optional), limit (default: 10), hours (default: 24) |
mempalace_get_aaak_spec | Get AAAK dialect reference specification | None |
Advanced Search
| Tool | Description | Parameters |
|---|---|---|
mempalace_deep_search | L3 deep semantic search with full results | query, wing (optional), room (optional), count (default: 20) |
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)
| Metric | Score |
|---|---|
| Recall@5 | 92.8% |
| Recall@10 | 96.2% |
| NDCG@10 | 0.809 |
| Type | n | R@5 | R@10 | NDCG@10 |
|---|---|---|---|---|
| knowledge-update | 78 | 98.7% | 100.0% | 0.835 |
| multi-session | 133 | 94.7% | 98.5% | 0.823 |
| single-session-assistant | 56 | 96.4% | 98.2% | 0.950 |
| single-session-preference | 30 | 90.0% | 96.7% | 0.797 |
| temporal-reasoning | 133 | 90.2% | 94.7% | 0.755 |
| single-session-user | 70 | 85.7% | 88.6% | 0.753 |
Embedding Speed
| Phase | Before (baseline) | After (cache + 4 workers) |
|---|---|---|
| Per-question embed (avg) | ~8.3 s | ~100 ms (cache hit) |
| Cache build (18,362 sessions) | N/A | ~11 min (one-time, 4 workers) |
| Total 500-question run | ~69 min (est.) | ~12 min |
Key optimisations applied:
-
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
buildCorpuscall is a pure in-memory map lookup (~100 ms for vector store writes vs 8.3 s of GEMM before). -
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.
-
Chunk size 32 β 64 β hugot's
RunPipelineis 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.
