hindsight-memory

Hindsight MemPalace

Hierarchical memory for AI agents. Storage + taxonomy in one system.

A hybrid of two open-source projects:

Project	What it does	What it lacks
Hindsight by vectorize-io	Long-term vector memory for AI agents. Stores, embeds, recalls.	No structure — all memories in one flat pile
MemPalace by milla-jovovich	Hierarchical taxonomy: rooms, halls, layers — the method of loci for AI	No storage engine — a spec without a database

This fork connects them. Hindsight's vector store + MemPalace's taxonomy = structured memory with semantic search.

---

How it works

┌──────────────────────────────────────────────────────┐
│                    MEMPALACE                          │
│                                                      │
│  ┌─── Room: auth ──┐  ┌─── Room: pipeline ──┐       │
│  │ Hall: facts      │  │ Hall: decisions     │       │
│  │ Hall: procedures │  │ Hall: events        │       │
│  │ Hall: warnings   │  │ Hall: facts         │       │
│  │                  │  │                     │       │
│  │  L0 ████ always  │  │  L0 ████ always     │       │
│  │  L1 ███░ warm    │  │  L1 ███░ warm       │       │
│  │  L2 ██░░ cold    │  │  L2 ██░░ cold       │       │
│  │  L3 █░░░ archive │  │  L3 █░░░ archive    │       │
│  └──────────────────┘  └─────────────────────┘       │
│           │                      │                   │
│           └──── Tunnel ──────────┘                   │
│                (cross-bank bridge)                   │
│                                                      │
│  Closets: compressed summaries + source pointers     │
└──────────────────────┬───────────────────────────────┘
                       │
              Hindsight vector store
              (embeddings + semantic search)

Rooms — topic isolation. Auth, pipeline, infrastructure, schema — each topic in its own room. An agent searching for auth facts won't wade through 500 deploy memories.

Halls — knowledge typing within a room. Fact, event, decision, procedure, warning. The system knows what it's looking at before reading — like Content-Type for memory.

Layers L0–L3 — four priority tiers. L0 (core) is always loaded. L3 (archive) is deep-search only. Same idea as CPU cache hierarchy: L1 is fast and small, RAM is slow but holds everything.

Closets — AI-compressed summaries with source pointers. Deduplication at the knowledge level: 10 related facts → 1 paragraph + references.

Tunnels — cross-bank bridges between agents. Agent A discovers an insight — Agent B sees it through a tunnel without data duplication.

Comparison

	Hindsight	MemPalace	This fork
What it is	Long-term memory store	Hierarchical taxonomy spec	Storage + taxonomy hybrid
Storage	Vector store + embeddings	None (spec only)	Vector store + embeddings
Memory structure	Flat (all memories equal)	Rooms → Halls → Layers	Rooms → Halls → Layers + embeddings
Retrieval	Semantic search	No retrieval engine	Room-scoped semantic search
Classification	None	Defined in spec	Keyword-based, <1ms, zero LLM cost
Priority tiers	All memories equal	L0–L3 (spec)	L0–L3 (implemented)
Compression	None	Closets (spec)	Closets with source pointers
Multi-agent	Shared bank	Tunnels (spec)	Tunnels (cross-bank bridges)
MCP integration	API only	None	5 tools via MCP protocol
Setup	Docker	Manual config	Docker (drop-in upgrade)

Quick start

git clone https://github.com/holetron/hindsight-mempalace.git
cd hindsight-mempalace
cp .env.example .env
# edit .env with your config
docker compose -f docker-compose.mempalace.yml up -d

API available at http://localhost:5100. Drop-in replacement for vanilla Hindsight — same API, same clients, new brain.

MCP Server

The mcp-server/ directory contains a standalone MCP server. Any MCP-compatible client (Claude Code, OpenClaw, Cursor, etc.) connects and gets structured long-term memory.

Tools

Tool	Description
memory_retain	Save a memory with automatic room/hall classification
memory_recall	Scoped semantic search with room/hall/layer filters
memory_reflect	Deep reasoning — synthesize facts, find patterns, answer with citations
memory_compress	Create closet summaries from accumulated facts
memory_bridge	Cross-bank tunnels between related memories

Setup

cd mcp-server
npm install
HINDSIGHT_URL=http://localhost:5100 node server.js

Claude Code config

Add to ~/.claude/mcp.json: