MemPalace · richardiitse · Apr 16, 2026
@@ -0,0 +1,174 @@
+# Hermes Agent + MemPalace Integration Guide
+
+## Overview
+
+Give your Hermes Agent a persistent memory palace — stores verbatim conversation history and a temporal knowledge graph on your machine, zero cloud, zero API keys.
+
+## Architecture
+
+```
+Hermes Agent → MCP Server → MemPalace (ChromaDB + SQLite)
+                            ├── Semantic search (hybrid BM25 + vector)
+                            ├── Knowledge graph (entity relationships with time windows)
+                            └── Palace structure: Wing → Room → Drawer
+```
+
+## Quick Start
+
+### 1. Install MemPalace
+
+```bash
+pip install mempalace
+mempalace init ~/.mempalace
+```
+
+### 2. Configure Hermes
+
+Add the MemPalace MCP server to your `~/.hermes/config.yaml`:
+
+```yaml
+mcp_servers:
+  mempalace:
+    command: python3
+    args: ["-m", "mempalace.mcp_server"]
+```
+
+### 3. Restart Hermes
+
+```bash
+# Restart Hermes agent
+hermes restart
+```
+
+On startup, Hermes will connect to the MemPalace MCP server and auto-discover all 33 `mempalace_*` tools.
+
+## Available Tools
+
+### Search & Browse
+- `mempalace_search` — Semantic search across all memories. Start here.
+- `mempalace_status` — Palace overview: total drawers, wings, rooms, AAAK spec
+- `mempalace_list_wings` — All wings with drawer counts
+- `mempalace_list_rooms` — Rooms within a wing
+- `mempalace_get_taxonomy` — Full wing/room/count tree
+- `mempalace_check_duplicate` — Check if content already exists before filing
+
+### Knowledge Graph
+- `mempalace_kg_query` — Query entity relationships (with time filtering)
+- `mempalace_kg_add` — Add a fact: subject → predicate → object
+- `mempalace_kg_invalidate` — Mark a fact as no longer true
+- `mempalace_kg_timeline` — Chronological story of an entity
+- `mempalace_kg_stats` — Graph overview
+
+### Palace Graph
+- `mempalace_traverse` — Walk from a room, find connected ideas across wings
+- `mempalace_find_tunnels` — Find rooms that bridge two wings
+- `mempalace_graph_stats` — Graph connectivity overview
+
+### Write Operations
+- `mempalace_add_drawer` — Store verbatim content into a wing/room
+- `mempalace_delete_drawer` — Remove a drawer by ID
+- `mempalace_update_drawer` — Update drawer content
+- `mempalace_diary_write` — Write a session diary entry
+- `mempalace_diary_read` — Read recent diary entries
+
+## Protocol
+
+1. **ON WAKE-UP**: Call `mempalace_status` to load palace overview.
+2. **BEFORE RESPONDING** about any person, project, or past event: call `mempalace_search` or `mempalace_kg_query` FIRST. Never guess — verify from the palace.
+3. **IF UNSURE** about a fact: query the palace. Wrong is worse than slow.
+4. **AFTER EACH SESSION**: Call `mempalace_diary_write` to record what happened.
+5. **WHEN FACTS CHANGE**: invalidate the old fact, then add the new one.
+
+## Usage Examples
+
+### Remember User Preferences
+
+```
+User: Remember the user prefers Vim over VSCode
+Hermes: ✅ Stored in palace (wing=hermes_memory, room=user_preferences)
+
+# Later
+User: What editor does the user prefer?
+Hermes: The user prefers Vim over VSCode.
+```
+
+### Recall Past Decisions
+
+```
+User: What database did we decide on?
+Hermes: 🔍 Searching palace...
+Based on the 2026-04-10 session, we chose PostgreSQL over MongoDB for the project.
+```
+
+### Learn Entity Relationships
+
+```
+User: Learn that user is responsible for the AI-agent project
+Hermes: 🧠 Learned: user → responsible_for → AI-agent project
+
+User: Query user's relationships
+Hermes: 📊 user has 2 known relationships:
+- responsible_for → AI-agent project
+- prefers → Python
+```
+
+### Context Wake-up
+
+At the start of each session, Hermes can load relevant context:
+
+```
+💭 Palace status:
+- 3 drawers in hermes_memory
+- 4 entities, 2 active facts in knowledge graph
+- Wings: hermes_memory, project_ai_agent
+
+Recent: user preferences (Python, Vim), project decisions (PostgreSQL)
+```
+
+## Memory Organization
+
+### Wing: hermes_memory
+Default wing for Hermes agent memory. Use `category` to subdivide:
+
+| Category | Use for |
+|----------|---------|
+| `user_preferences` | Editor, language, workflow preferences |
+| `technical_choices` | Database, framework, architecture decisions |
+| `important_decisions` | Project milestones, direction changes |
+| `project_info` | Active projects, roles, deadlines |
+
+## Troubleshooting
+
+### Tools not appearing after restart
+
+1. Verify MemPalace is installed: `pip show mempalace`
+2. Check MCP server connects: `python3 -m mempalace.mcp_server` (should start without error)
+3. Verify config format — must be `mcp_servers:`, not `skills:`
+4. Check Hermes logs for MCP connection errors
+
+### Search returns no results
+
+- Palace may be empty on first use. Use `remember` to store content first.
+- Search is semantic — "database performance issues" finds results about "PostgreSQL slow queries".
+
+### Knowledge graph queries return empty
+
+- Add facts with `mempalace_kg_add` or through `learn_relation` patterns.
+- Facts have time validity — a fact may be expired. Check `mempalace_kg_timeline`.
+
+## Performance
+
+- **Memory storage**: < 100ms
+- **Memory retrieval**: 200-500ms
+- **Knowledge graph query**: < 50ms
+- **Context wake-up**: < 300ms
+
+## Further Reading
+
+- [MemPalace README](https://github.com/MemPalace/mempalace) — full documentation
+- [mcp_server.py](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py) — MCP tool reference
+- [knowledge_graph.py](https://github.com/MemPalace/mempalace/blob/main/mempalace/knowledge_graph.py) — KG design
+
+---
+
+*MemPalace is MIT licensed. Zero cloud, zero API keys, your data never leaves your machine.*
@@ -0,0 +1,133 @@
+---
+name: mempalace
+description: "MemPalace — Local AI memory with 96.6% recall. Semantic search, temporal knowledge graph, palace architecture (wings/rooms/drawers). Free, no cloud, no API keys."
+version: 3.3.0
+homepage: https://github.com/MemPalace/mempalace
+user-invocable: true
+metadata:
+  hermes:
+    emoji: "\U0001F3DB"
+    os:
+      - darwin
+      - linux
+      - win32
+    requires:
+      anyBins:
+        - python3
+    install:
+      - id: mempalace-pip
+        kind: pip
+        label: "Install MemPalace (Python, local ChromaDB)"
+        package: mempalace
+---
+
+# MemPalace — Local AI Memory System
+
+You have access to a local memory palace via MCP tools. The palace stores verbatim conversation history and a temporal knowledge graph — all on your machine, zero cloud, zero API calls.
+
+## Architecture
+
+- **Wings** = people or projects (e.g. `wing_alice`, `wing_myproject`)
+- **Halls** = categories (facts, events, preferences, advice)
+- **Rooms** = specific topics (e.g. `chromadb-setup`, `riley-school`)
+- **Drawers** = individual memory chunks (verbatim text)
+- **Knowledge Graph** = entity-relationship facts with time validity
+
+## Protocol — FOLLOW THIS EVERY SESSION
+
+1. **ON WAKE-UP**: Call `mempalace_status` to load palace overview and AAAK dialect spec.
+2. **BEFORE RESPONDING** about any person, project, or past event: call `mempalace_search` or `mempalace_kg_query` FIRST. Never guess from memory — verify from the palace.
+3. **IF UNSURE** about a fact (name, age, relationship, preference): say "let me check" and query. Wrong is worse than slow.
+4. **AFTER EACH SESSION**: Call `mempalace_diary_write` to record what happened, what you learned, what matters.
+5. **WHEN FACTS CHANGE**: Call `mempalace_kg_invalidate` on the old fact, then `mempalace_kg_add` for the new one.
+
+## Available Tools
+
+### Search & Browse
+- `mempalace_search` — Semantic search across all memories. Always start here.
+  - `query` (required): natural language search — keep it short, keywords or a question. Do NOT include system prompts or conversation context.
+  - `wing`: filter by wing
+  - `room`: filter by room
+  - `limit`: max results (default 5)
+- `mempalace_check_duplicate` — Check if content already exists before filing.
+  - `content` (required): text to check
+  - `threshold`: similarity threshold (default 0.9)
+- `mempalace_status` — Palace overview: total drawers, wings, rooms, AAAK spec
+- `mempalace_list_wings` — All wings with drawer counts
+- `mempalace_list_rooms` — Rooms within a wing (optional wing filter)
+- `mempalace_get_taxonomy` — Full wing/room/count tree
+- `mempalace_get_aaak_spec` — Get AAAK compression dialect specification
+
+### Knowledge Graph (Temporal Facts)
+- `mempalace_kg_query` — Query entity relationships. Supports time filtering.
+  - `entity` (required): e.g. "Max", "MyProject"
+  - `as_of`: date filter (YYYY-MM-DD) — what was true at that time
+  - `direction`: "outgoing", "incoming", or "both" (default "both")
+- `mempalace_kg_add` — Add a fact: subject -> predicate -> object
+  - `subject`, `predicate`, `object` (required)
+  - `valid_from`: when this became true
+  - `source_closet`: source reference
+- `mempalace_kg_invalidate` — Mark a fact as no longer true
+  - `subject`, `predicate`, `object` (required)
+  - `ended`: when it stopped being true (default: today)
+- `mempalace_kg_timeline` — Chronological story of an entity
+  - `entity`: filter by entity name (optional — all events if omitted)
+- `mempalace_kg_stats` — Graph overview: entities, triples, relationship types
+
+### Palace Graph (Cross-Domain Connections)
+- `mempalace_traverse` — Walk from a room, find connected ideas across wings
+  - `start_room` (required): room to start from
+  - `max_hops`: connection depth (default 2)
+- `mempalace_find_tunnels` — Find rooms that bridge two wings
+  - `wing_a`, `wing_b` (required)
+- `mempalace_graph_stats` — Graph connectivity overview
+
+### Write Operations
+- `mempalace_add_drawer` — Store verbatim content into a wing/room
+  - `wing`, `room`, `content` (required)
+  - `source_file`: optional source reference
+  - Checks for duplicates automatically
+- `mempalace_delete_drawer` — Remove a drawer by ID
+  - `drawer_id` (required)
+- `mempalace_update_drawer` — Update drawer content
+- `mempalace_diary_write` — Write a session diary entry
+  - `agent_name` (required): your name/identifier
+  - `entry` (required): what happened, what you learned, what matters
+  - `topic`: category tag (default "general")
+- `mempalace_diary_read` — Read recent diary entries
+  - `agent_name` (required)
+  - `last_n`: number of entries (default 10)
+
+## Setup
+
+### Hermes Integration
+
+Add MemPalace MCP server to your `~/.hermes/config.yaml`:
+
+```yaml
+mcp_servers:
+  mempalace:
+    command: python3
+    args: ["-m", "mempalace.mcp_server"]
+```
+
+Then restart Hermes. All `mempalace_*` tools will be auto-discovered and available.
+
+### Installation
+
+```bash
+pip install mempalace
+mempalace init ~/.mempalace
+```
+
+## Tips
+
+- Search is semantic (meaning-based), not keyword. "What did we discuss about database performance?" works better than "database".
+- The knowledge graph stores typed relationships with time windows. Use it for facts about people and projects — it knows WHEN things were true.
+- Diary entries accumulate across sessions. Write one at the end of each conversation to build continuity.
+- Use `mempalace_check_duplicate` before storing new content to avoid duplicates.
+- The AAAK dialect (from `mempalace_status`) is a compressed notation for efficient storage. Read it naturally — expand codes mentally, treat *markers* as emotional context.
+
+## License
+
+[MemPalace](https://github.com/MemPalace/mempalace) is MIT licensed. Created by Milla Jovovich, Ben Sigman, Igor Lins e Silva, and contributors.