TechEmpower's production fork of MemPalace/mempalace (transferred from jphein/mempalace in May 2026)

A verbatim-first local AI memory system. This fork tracks upstream/develop through the v3.3.6 sync (2026-05-24, commit 6957c7e) and runs in production on a 335K+ drawer Postgres + pgvector + Apache AGE palace behind palace-daemon. It carries ~574 fork-ahead commits that compose with — not replace — bensig's release direction; the v3.3.5 release (2026-05-10) includes our co-authored _get_collection retry-once via upstream #1377. 3908 tests pass on main.

The fork's architectural thinking — the four-layer memory model, the verbatim-vs-derivative thesis, design principles, and the two-memory-layer pairing with Auto Dream — lives in docs/ARCHITECTURE.md. The new things here are what we've learned, not just what we've fixed.

We surveyed the memory-system landscape in April 2026 and found no verbatim-first local system with MCP. The landscape has since fragmented — MCP memory servers proliferated in May 2026 — but the verbatim-vs-derivative axis remains the clearest architectural dividing line. Updated survey as of 2026-05-24:

• The verbatim thesis has academic validation. True Memory (arXiv:2605.04897) independently argues that extraction at ingestion is the wrong primitive, scoring 93.0% on LoCoMo vs Mem0's 61.4%. New entrants iai-mcp and ai-memory both chose verbatim-first designs, suggesting the pattern has reached broader adoption.
• claude-mem (89K+ stars) is the elephant in the room. Explicitly non-verbatim (AI compression), but its community size makes it the default comparison point. The largest system taking the opposite architectural approach.
• Letta V1 rework (Mar 2026) deprecates heartbeats and server-side MCP. MCP support is shifting to client-side skills; the story is less clear-cut than before.
• Mem0 shipped a significant algorithm upgrade (single-pass hierarchical extraction + multi-signal retrieval → 91.6%) without going verbatim. Added opt-in infer=False for verbatim hard constraints — an escape hatch, not a core commitment.
• MCP memory server space fragmented dramatically. At least 6 new systems with MCP support since April: agentmemory, OMEGA, ai-memory, iai-mcp, Open Brain, EngramX v4.0. Most are local-first SQLite. Differentiators narrowing to verbatim-vs-extraction and consolidation strategy.

The April-2026 verbatim cluster (MemPalace, Celiums, Longhand, engram all within ~8 days) is no longer an isolated coincidence — it was the leading edge of a pattern now confirmed by academic work and a second wave of implementations. The differentiator: verbatim storage is the foundation; everything else (tags, KG, decay, summaries, consolidated indices) is enrichment layered on top.

git clone https://github.com/techempower-org/mempalace.git
cd mempalace
uv sync --extra dev          # recommended; or: python -m venv venv && pip install -e ".[dev]"

uv run mempalace init ~/Projects --yes
uv run mempalace mine ~/Projects/myproject
uv run mempalace search "why did we switch to GraphQL"

For a daemon-fronted deployment (recommended once palace size reaches the multi-thousand-drawer range), see palace-daemon's setup. The fork's scripts/deploy.sh is a one-command Syncthing-aware redeploy: push fork main, restart palace-daemon, post-restart import-check that the new fork-ahead surface is loaded.

A Stop hook fires every 15 messages in Claude Code, triggers verbatim transcript mining via the daemon's /mine endpoint (no LLM in the loop), and renders a terminal line so the user sees the ingest land:

{"systemMessage": "✦ Transcript ingest triggered (wing=wing_realmwatch)"}

search_memories (via mempalace_search MCP tool) returns results with scope-authoritative context so callers can tell when the vector layer underdelivered:

{
  "query": "kiyo xhci usb crash fix razer",
  "total_before_filter": 15,
  "available_in_scope": 160351,
  "warnings": [],
  "results": [
    {"drawer_id": "drawer_kiyo-xhci-fix_technical_a8b2c4...", "wing": "projects",
     "room": "technical", "similarity": 0.859, "matched_via": "drawer", ...},
    {"drawer_id": "drawer_kiyo-xhci-fix_technical_d5e7f9...", "wing": "kiyo-xhci-fix",
     "room": "technical", "similarity": 0.852, "matched_via": "drawer", ...}
  ]
}

When the HNSW index is genuinely degraded (rare, post-fix), the same call returns warnings: ["vector search returned 0 of 5 requested; filled 5 from sqlite+BM25 keyword match"] with hits tagged "matched_via": "sqlite_bm25_fallback" — data is never silently hidden.

Substrate (2026-05-15). Postgres + pgvector + Apache AGE shipped on main and serving production traffic. PG16 + pgvector 0.8.2 + AGE 1.6.0 on familiar.jphe.in:5433. One engine consolidates vector search, full-text search (tsvector BM25), graph traversal, and the temporal entity-relationship store — previously four separate systems (ChromaDB + SQLite + graph cache). 8/9 bench suites pass. Full operator narrative at docs/operators/pgvector-cutover-runbook.md.

AGE integration (2026-05-22). PR #101 merged — six-phase AGE integration complete. Writethrough middleware on every drawer write extracts entities and creates :MENTIONS edges in the AGE graph. Backfill running against 335K+ existing drawers at ~5/s. The mempalace_walk_palace MCP tool enables Cypher traversal by wing, room, or entity. A 2026-05-17 spike showed graph signal adds +9pp R@5 over vector-only retrieval.

Hybrid retrieval (2026-05-24). candidate_strategy="hybrid" (vector ∪ tsvector BM25 ∪ AGE graph-expanded candidates, hybrid-reranked) is now the MCP default for all callers.

Three bands of work, all instances of the architectural principles. Detail rows in the fork change inventory and FORK_CHANGELOG.md.

• Structural retrieval fixes. Verbatim-only model: hooks no longer write 1KB checkpoint summaries; auto-mined transcript chunks land in mempalace_drawers and mempalace_search reaches them directly. One collection, one search path, no kind-filter / over-fetch hack.
• Single-writer architecture. palace-daemon is the only process that opens the palace; clients connect over HTTP. ChromaDB HNSW concurrency hazards become structurally impossible.
• Deterministic hook saves. Silent saves bypass auto-memory conflicts — the LLM is no longer in the save path. Verbatim transcript ingest is the entire save path.

Organized around the verbatim-vs-derivative axis. Each item evaluated against the architectural principles.

• End-to-end QA measurement on the post-structural-fix palace — the "17% E2E QA" attribution to engram-2 in earlier drafts was not substantiated in their published materials; the corpus-shape pathology it surfaced (checkpoint domination of mempalace_search results, pre-migration kind=content returning 3 tokens/Q vs post-migration 1,267) is real and is closed. Results published in notebook/data/cat9-postmigrate-e2e/REPORT.md: on LongMemEval oracle (n=500, reader o4-mini / judge gpt-5.3-chat), the default /search path scores 97.0% R@5 and 60.40% E2E QA — a +38.4pp retrieval→answer gap that locates the open work in consumption, not retrieval. (age-fused 17.60% is a known-broken-harness reading — snippet-width starvation + empty triples layer — not a verdict on graph fusion.)
• Cat 9 / The Handshake — generalizable measurement of the retrieval→consumption gap. 46.67% / 78.33% on RLM-vs-Familiar. Scaling across the verbatim-first cohort via jphein/multipass-structural-memory-eval.
• Multi-palace separation — curated "authority" vs auto-mined memory (upstream #1018). P8 may absorb. Design doc.

A meaningful shift in 2026-04 and 2026-05: this fork increasingly composes with upstream rather than carrying parallel implementations.

• Cherry-picks (in-flight upstream PRs we use early): #665 PostgreSQL backend (commit 5e90c72, the substrate work above), #1085 batched inserts (6be6fff — CLOSED 2026-05-16, superseded by merged #1185; safe to drop on next sync), #1087 rewrite cmd_purge via delete(where=) (366a9ad), #1094 None-metadata coercion (43d728d).
• Co-authored merges: #1377 (surgical _get_collection retry-once, shipped in v3.3.5 — originated from this fork via #1286 which igorls closed and re-extracted with Co-authored-by credit).
• Coordinated reviews: #1199 (rmdes' unbounded-ingest fix), #1219 (pepo72's drawer_id), RFC 001 #743 (storage backend spec).
• Closed in favor of upstream: #1171 cross-process write lock (closed 2026-04-25 — Felipe's #976 plus daemon-strict architecture obsoleted ours).

The fork ships structural moves first, validates them on the canonical palace, then either contributes upstream as PRs or aligns with upstream's parallel implementation. The composition is the point.

Four peer builds converged on the same architectural agreements as this fork (verbatim base layer, no LLM in index path, wings as scope routing, consumption problem unsolved by retrieval): Familiar (78.33% recall), CampaignGenerator (19.82x cost reduction), Kent (APO training), adaptmem (orthogonal encoder lift). The multipass-structural-memory-eval framework provides the Cat 9 / Handshake diagnostic.

Full inventory of companion tools, evaluation frameworks, competing systems, peer builds, and active forks in docs/ECOSYSTEM.md.

Open from this fork as of 2026-05-24. Run gh pr list --repo MemPalace/mempalace --author jphein --state open for the live list. Recently merged: #1142 (RELEASING.md, 2026-05-22), #1494 (recovery runbook, 2026-05-22), #1487 (rebuild_index progress, 2026-05-13), #1024 (configurable chunking, 2026-05-15), #1459 (empty-metadata sentinel, 2026-05-13) and #1474 (convo_miner bulk pre-fetch, 2026-05-13).

• Publish Cat 9 end-to-end results on the post-migration palace, with adapter parity numbers across the verbatim-first cohort.
• Publish the multipass-structural-memory-eval harness with adapters for MemPalace, Longhand, Celiums, mcp-memory-service.
• Land P1 (derive hierarchy from cwd / transcript path) and P5 (temporal fact validity) — the remaining open planned-work items; P0 (tags), P2 (decay/recency), and P3 (rating feedback) have shipped fork-side.
• Agent-shaped CLI surface — shipped. A fast direct-to-daemon CLI quartet — mempalace list, mempalace graph, mempalace cypher, mempalace stats — each with --json/--format json for non-MCP integration. These skip the MCP/AI round-trip and hit the daemon directly, so they're faster than the equivalent tool call. Prior art: Grafana's GCX CLI.
• First-class support across AI coding agents — Claude Code, OpenCode, Cursor, Aider, Gemini CLI, Codex CLI, Warp. Path: upstream's RFC 002 source-adapter spec. Three cells: read (MCP, already agent-agnostic), mine (per-agent via RFC 002), hook/event (per-host or mining-on-cron fallback).

# Setup
git clone https://github.com/techempower-org/mempalace.git
cd mempalace
uv sync --extra dev                       # recommended; or pip install -e ".[dev]"

# Develop
uv run pytest tests/ -q                   # 3498 tests (benchmarks deselected)
uv run mempalace status                   # palace health
uv run ruff check . && uv run ruff format --check .

# Doc maintenance (canonical YAML + renderer, see CLAUDE.md)
./scripts/render-docs.py                  # regenerate FORK_CHANGELOG from docs/fork-changes.yaml
./scripts/check-docs.sh                   # lint test count, fork hashes, render parity, upstream PR states

# Deploy fork main → palace-daemon on familiar.jphe.in:8085
./scripts/deploy.sh                       # one command: push, sync, restart, health, import-check

The full enumeration of fork-ahead changes. The canonical source is docs/fork-changes.yaml; FORK_CHANGELOG.md is regenerated from it and contains the complete open/pending table. Run ./scripts/check-docs.sh to verify everything resolves to live state.

• 2026-05-22: #1142 (docs/RELEASING.md), #1494 (recovery runbook for chromadb dimensionality=None corruption)
• 2026-05-15: #1024 — Configurable chunk_size / chunk_overlap / min_chunk_size exposed via MempalaceConfig
• 2026-05-13: #1487 (rebuild_index progress callback), #1459 (empty-metadata sentinel), #1474 (convo_miner bulk pre-fetch)
• 2026-05-06 (in v3.3.5): #1377 — _get_collection retry-once + log-on-failure (co-authored from this fork via the closed #1286)
• 2026-05-01 (post-v3.3.4): #1262, #1289, #1303
• 2026-04-26: #1173, #1177, #1198, #1201
• 2026-04-23: #659 — diary wing parameter
• 2026-04-22: #661, #673, #1021
• 2026-04-21 (in v3.3.2): #1000, #1023, #681
• 2026-04-18: #999 — None-metadata guards across 8 read paths
• In v3.3.0: #664, #682, #683, #684, #635 (via #667)

• #1085 (cherry-pick — closed by @midweste 2026-05-16, superseded by merged upstream #1185)
• #1286 (drifted; @igorls closed and re-extracted the surgical fix as #1377 with co-author credit)
• #1171 (cross-process write lock — superseded by #976 + daemon-strict)
• #1146, #1115, #629, #632, #662, #663, #738, #1036 — all superseded

• The Verbatim-vs-Derivative Axis — standalone treatment of Principle 1. Structural argument, the April-May 2026 recovery-collection episode (210× token-budget gap closed by one structural change), and Anthropic's Dreams API as independent vendor-API ratification of the same axis.
• True Memory vs MemPalace — six-vs-four layers, benchmark comparison, convergent verbatim-first design.
• Memory System Benchmarks (2026-05) — LongMemEval/LoCoMo/BEAM landscape survey across 20+ systems.
• Three Patterns for Agent Memory — Familiar / RLM / parallel hybrid on jp-realm-v0.1; invocation as bottleneck.

See docs/BIBLIOGRAPHY.md for the complete documentation index and external references.

MIT — see LICENSE.