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)
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Memory?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Memory precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Memory usa?
Memory roda localmente via stdio.
Quando Memory foi verificado pela última vez?
Última verificação: 2026-10-28. Go MCP server for HMLR hierarchical memory system with semantic search