the-nexus/FINDINGS-issue-1047.md

FINDINGS: MemPalace Local AI Memory System Assessment & Leverage Plan

Issue: #1047 Date: 2026-04-10 Investigator: mimo-v2-pro (swarm researcher)

---

1. What Issue #1047 Claims

The issue (authored by Bezalel, dated 2026-04-07) describes MemPalace as:

• An open-source local-first AI memory system with highest published LongMemEval scores (96.6% R@5)
• A Python CLI + MCP server using ChromaDB + SQLite with a "palace" hierarchy metaphor
• AAAK compression dialect for ~30x context compression
• 19 MCP tools for agent memory

It recommends that every wizard clone/vendor MemPalace, configure rooms, mine workspace, and wire the searcher into heartbeats.

2. What Actually Exists in the Codebase (Current State)

The Nexus repo already contains substantial MemPalace integration that goes well beyond the original research proposal. Here is the full inventory:

2.1 Core Python Layer — nexus/mempalace/ (3 files, ~290 lines)

File	Purpose
config.py	Environment-driven config: palace paths, fleet path, wing name, core rooms, collection name
searcher.py	ChromaDB-backed search/write API with search_memories(), search_fleet(), add_memory()
__init__.py	Package marker

Status: Functional. Clean API. Lazy ChromaDB import with graceful MemPalaceUnavailable exception.

2.2 Fleet Management Tools — mempalace/ (8 files, ~800 lines)

File	Purpose
rooms.yaml	Fleet-wide room taxonomy standard (5 core rooms + optional rooms)
validate_rooms.py	Validates wizard mempalace.yaml against fleet standard
audit_privacy.py	Scans fleet palace for policy violations (raw drawers, oversized closets, private paths)
retain_closets.py	90-day retention enforcement for closet aging
export_closets.sh	Privacy-safe closet export for rsync to Alpha fleet palace
fleet_api.py	HTTP API for shared fleet palace (search, record, wings)
tunnel_sync.py	Pull closets from remote wizard's fleet API into local palace
__init__.py	Package marker

Status: Well-structured. Each tool has clear CLI interface and proper error handling.

2.3 Evennia MUD Integration — nexus/evennia_mempalace/ (6 files, ~580 lines)

File	Purpose
commands/recall.py	CmdRecall (semantic search), CmdEnterRoom (teleport), CmdAsk (NPC query)
commands/write.py	CmdRecord, CmdNote, CmdEvent (memory writing commands)
typeclasses/rooms.py	MemPalaceRoom typeclass
typeclasses/npcs.py	StewardNPC with question-answering via palace search

Status: Complete. Evennia stub fallback for testing outside live environment.

2.4 3D Visualization — nexus/components/spatial-memory.js (~665 lines)

Maps memory categories to spatial regions in the Nexus Three.js world:

• Inner ring: Documents, Projects, Code, Conversations, Working Memory, Archive
• Outer ring (MemPalace zones, issue #1168): User Preferences, Project Facts, Tool Knowledge, General Facts
• Crystal geometry with deterministic positioning, connection lines, localStorage persistence

Status: Functional 3D visualization with region markers, memory crystals, and animation.

2.5 Frontend Integration — mempalace.js (~44 lines)

Basic Electron/browser integration class that:

• Initializes a palace wing
• Auto-mines chat content every 30 seconds
• Exposes search() method
• Updates stats display

Status: Minimal but functional as a bridge between browser UI and CLI mempalace.

2.6 Scripts & Automation — scripts/ (5 files)

File	Purpose
mempalace-incremental-mine.sh	Re-mines only changed files since last run
mempalace_nightly.sh	Nightly maintenance
mempalace_export.py	Export utility
validate_mempalace_taxonomy.py	Taxonomy validation script
audit_mempalace_privacy.py	Privacy audit script
sync_fleet_to_alpha.sh	Fleet sync to Alpha server

2.7 Tests — tests/ (7 test files)

File	Tests
test_mempalace_searcher.py	Searcher API, config
test_mempalace_validate_rooms.py	Room taxonomy validation
test_mempalace_retain_closets.py	Closet retention
test_mempalace_audit_privacy.py	Privacy auditor
test_mempalace_fleet_api.py	Fleet HTTP API
test_mempalace_tunnel_sync.py	Remote wizard sync
test_evennia_mempalace_commands.py	Evennia commands + NPC helpers

2.8 CI/CD

• ci.yml: Validates palace taxonomy on every PR, plus Python/JSON/YAML syntax checks
• weekly-audit.yml: Monday 05:00 UTC — runs privacy audit + dry-run retention against test fixtures

2.9 Documentation

• docs/mempalace_taxonomy.yaml — Full taxonomy standard (145 lines)
• docs/mempalace/rooms.yaml — Rooms documentation
• docs/mempalace/bezalel_example.yaml — Example wizard config
• docs/bezalel/evennia/ — Evennia integration examples (steward NPC, palace commands)
• reports/bezalel/2026-04-07-mempalace-field-report.md — Original field report

3. Gap Analysis: Issue #1047 vs. Reality

Issue #1047 Proposes	Current State	Gap
"Each wizard should clone/vendor it"	Vendor infrastructure exists (scripts/mempalace-incremental-mine.sh)	DONE
"Write a mempalace.yaml"	Fleet taxonomy standard + validator exist	DONE
"Run mempalace mine"	Incremental mining script exists	DONE
"Wire searcher into heartbeat scripts"	nexus/mempalace/searcher.py provides API	DONE (needs adoption verification)
AAAK compression	Not implemented in repo	OPEN — no AAAK dialect code
MCP server (19 tools)	No MCP server integration	OPEN — no MCP tool definitions
Benchmark validation	No LongMemEval test harness in repo	OPEN — claims unverified locally
Fleet-wide adoption	Only Bezalel field report exists	OPEN — no evidence of Timmy/Allegro/Ezra adoption
Hermes harness integration	No direct harness/memory-tool bridge	OPEN — searcher exists but no harness wiring

4. What's Actually Broken

4.1 No AAAK Implementation

The issue describes AAAK (~30x compression, ~170 tokens wake-up context) as a key feature, but there is zero AAAK code in the repo. The nexus/mempalace/ layer has no compression functions. This is a missing feature, not a bug.

4.2 No MCP Server Bridge

The upstream MemPalace offers 19 MCP tools, but the Nexus integration only exposes the ChromaDB Python API. There is no MCP server definition, no tool registration for the harness, and no bridge to the mcp_config.json at repo root.

4.3 Fleet Adoption Gap

Only Bezalel has a documented field report (#1072). There is no evidence that Timmy, Allegro, or Ezra have populated palaces, configured room taxonomies, or run incremental mining. The export_closets.sh script hardcodes Bezalel paths.

4.4 Frontend Integration Stale

mempalace.js references window.electronAPI.execPython() which only works in the Electron shell. The main app.js (Three.js world) does not import or use mempalace.js. The spatial-memory.js component defines MemPalace zones but has no data pipeline to populate them from actual palace data.

4.5 Upstream Quality Concern

Bezalel's field report notes the upstream repo is "astroturfed hype" — 13.4k LOC in a single commit, 5,769 GitHub stars in 48 hours, ~125 lines of tests. The code is not malicious but is not production-grade. The Nexus has effectively forked/vendored the useful parts and rewritten the critical integration layers.

5. What's Working Well

1. Clean architecture separation — nexus/mempalace/ is a proper Python package with config/searcher separation. Testable without ChromaDB installed.

2. Privacy-first fleet design — closet-only export policy, privacy auditor, retention enforcement, and private path detection are solid operational safeguards.

3. Taxonomy standardization — rooms.yaml + validator ensures consistent memory structure across wizards.

4. CI integration — Taxonomy validation in PR checks + weekly privacy audit cron are good DevOps practices.

5. Evennia integration — The MUD commands (recall, enter room, ask steward) are well-designed and testable outside Evennia via stubs.

6. Spatial visualization — spatial-memory.js is a creative 3D representation with deterministic positioning and category zones.

6. Recommended Actions

Priority 1: Fleet Adoption Verification (effort: small)

• Confirm each wizard (Timmy, Allegro, Ezra) has run mempalace mine and has a populated palace
• Verify mempalace.yaml exists on each wizard's VPS
• Update export_closets.sh to not hardcode Bezalel paths (use env vars)

Priority 2: Hermes Harness Bridge (effort: medium)

• Wire nexus/mempalace/searcher.py into the Hermes harness as a memory tool
• Add memory search/recall to the agent loop so wizards get cross-session context automatically
• Map MemPalace search to the existing memory/fact_store tools or add a dedicated palace_search tool

Priority 3: MCP Server Registration (effort: medium)

• Create an MCP server that exposes search, write, and status tools
• Register in mcp_config.json
• Enable any harness agent to use MemPalace without Python imports

Priority 4: AAAK Compression (effort: large, optional)

• Implement or port the AAAK compression dialect
• Generate wake-up context summaries from palace data
• This is a nice-to-have, not critical — the raw ChromaDB search is functional

Priority 5: 3D Pipeline Bridge (effort: medium)

• Connect spatial-memory.js to live palace data via WebSocket or REST
• Populate memory crystals from actual search results
• Visual feedback when new memories are added

7. Effort Summary

Action	Effort	Impact
Fleet adoption verification	2-4 hours	High — ensures all wizards have memory
Hermes harness bridge	1-2 days	High — automatic cross-session context
MCP server registration	1 day	Medium — enables any agent to use palace
AAAK compression	2-3 days	Low — nice-to-have
3D pipeline bridge	1-2 days	Medium — visual representation of memory
Fix export_closets.sh hardcoded paths	30 min	Low — operational hygiene

8. Conclusion

Issue #1047 was a research request from 2026-04-07. Since then, significant implementation work has been completed — far exceeding the original proposal. The core memory infrastructure (searcher, fleet tools, privacy, taxonomy, Evennia integration, tests, CI) is built and functional.

The primary remaining gap is fleet-wide adoption (only Bezalel has documented use) and harness integration (the searcher exists but isn't wired into the agent loop). The AAAK and MCP features from the original research are not implemented but are not blocking — the ChromaDB-backed search provides the core value proposition.

Verdict: The MemPalace integration is substantially complete at the infrastructure level. The next bottleneck is operational adoption and harness wiring, not new feature development.