A Go implementation of the HMLR (Hierarchical Memory Lookup & Routing) memory system, exposed as an MCP (Model Context Protocol) server for integration with Claude Code and other MCP clients.
What is HMLR?
HMLR replaces traditional vector-only RAG systems with a structured, state-aware memory architecture that achieves across adversarial benchmarks.
Go MCP server for HMLR hierarchical memory system with semantic search
perfect (1.00) faithfulness and context recall
Key Features:
🧠 Temporal Resolution: Automatically handles conflicting facts across time
📋 Bridge Blocks: Organizes conversations by topic with smart routing
🎯 4 Routing Scenarios: Continuation, Resumption, New Topic, Topic Shift
🔍 Semantic Recall: Retrieves relevant memories even with zero keyword overlap
💾 XDG Compliant: Stores data in ~/.local/share/remember/
Quick Start
Prerequisites
Go 1.23+ installed
OpenAI API key (for embeddings and LLM features)
Installation
Clone the repository:
git clone <your-repo-url>
cd remember-standalone
Create .env file with your API keys:
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
Example .env:
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-... # Optional, for future features
MEMORY_OPENAI_MODEL=gpt-4o-mini # Optional, defaults to gpt-4o-mini
Build the server:
go build -o bin/hmlr-server ./cmd/server
Run the server:
./bin/hmlr-server
The server will start on stdio and wait for MCP protocol messages.
Configuration
Environment Variables
Required:
OPENAI_API_KEY - Your OpenAI API key for embeddings and LLM features
Optional:
MEMORY_OPENAI_MODEL - Chat model to use (default: gpt-4o-mini)
Options: gpt-4o-mini, gpt-4o, o1-mini, etc.
Affects metadata extraction, fact extraction, and user profile learning
gpt-4o-mini is recommended for best balance of speed and quality
Model Selection Guide:
gpt-4o-mini: Recommended - Good balance of speed, quality, and cost (~$0.15/1M input tokens)
gpt-4o: Highest quality, slower, more expensive (~$2.50/1M input tokens)
# Run all scenario tests (with REAL storage, no mocks!)
go test -v ./.scratch/
# Run specific scenario
go test -v ./.scratch/ -run TestScenario01
Project Structure
remember-standalone/
├── cmd/
│ └── server/ # Main entry point
├── internal/
│ ├── core/ # Governor, ChunkEngine
│ ├── storage/ # Storage implementation
│ ├── models/ # Data structures
│ └── mcp/ # MCP tools and handlers
├── .scratch/ # Scenario tests (not committed)
├── scenarios.jsonl # Documented test scenarios
└── DESIGN.md # Full architecture design
Scenario Testing
This project follows scenario-driven testing with zero mocks:
# All tests use REAL storage, REAL SQLite, REAL files
.scratch/scenario_01_store_retrieve_test.go # Basic storage
.scratch/scenario_02_routing_test.go # Governor routing
.scratch/scenario_03_chunking_test.go # Hierarchical chunking
See scenarios.jsonl for documented test scenarios.
Implementation Status
✅ Phase 1: Foundation
XDG storage initialization
Bridge Block JSON storage
SQLite facts database
✅ Phase 2: Core Components
Governor with 4 routing scenarios
ChunkEngine for hierarchical chunking
FactScrubber with LLM-based extraction
ContextHydrator for intelligent prompt assembly
LatticeCrawler for vector-based candidate retrieval
✅ Phase 3: Background Agents
Scribe agent for async user profile learning
Goroutine-based async processing
✅ Phase 4: MCP Server
Stdio transport
All 5 MCP tools implemented
.env loading for API keys
✅ Phase 5: Advanced Features
Vector embeddings with OpenAI (text-embedding-3-small)