Merge branch 'main' into docs/vitepress-site

integrations/openclaw/SKILL.md

@@ -0,0 +1,154 @@
+---
+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.1.0
+homepage: https://github.com/milla-jovovich/mempalace
+user-invocable: true
+metadata:
+  openclaw:
+    emoji: "\U0001F3DB"
+    os:
+      - darwin
+      - linux
+      - win32
+    requires:
+      anyBins:
+        - mempalace
+        - python3
+    install:
+      - id: mempalace-pip
+        kind: uv
+        label: "Install MemPalace (Python, local ChromaDB)"
+        package: mempalace
+        bins:
+          - 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 the user's 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 — lowering to 0.85–0.87 often catches more near-duplicates without significant false positives)
+- `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
+- `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_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
+
+Install MemPalace and populate the palace:
+
+```bash
+pip install mempalace
+mempalace init ~/my-convos
+mempalace mine ~/my-convos
+```
+
+### OpenClaw MCP config
+
+Add to your OpenClaw MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "mempalace": {
+      "command": "python3",
+      "args": ["-m", "mempalace.mcp_server"]
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+openclaw mcp set mempalace '{"command":"python3","args":["-m","mempalace.mcp_server"]}'
+```
+
+### Other MCP hosts
+
+```bash
+# Claude Code
+claude mcp add mempalace -- python -m mempalace.mcp_server
+
+# Cursor — add to .cursor/mcp.json
+# Codex — add to .codex/mcp.json
+```
+
+## 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/milla-jovovich/mempalace) is MIT licensed. Created by Milla Jovovich, Ben Sigman, Igor Lins e Silva, and contributors.

website/.vitepress/config.mts

@@ -40,6 +40,7 @@ export default withMermaid(
               { text: 'MCP Integration', link: '/guide/mcp-integration' },
               { text: 'Claude Code Plugin', link: '/guide/claude-code' },
               { text: 'Gemini CLI', link: '/guide/gemini-cli' },
+              { text: 'OpenClaw Skill', link: '/guide/openclaw' },
               { text: 'Local Models', link: '/guide/local-models' },
               { text: 'Auto-Save Hooks', link: '/guide/hooks' },
               { text: 'Configuration', link: '/guide/configuration' },

website/concepts/the-palace.md

@@ -7,33 +7,43 @@ Ancient Greek orators memorized entire speeches by placing ideas in rooms of an
 Your conversations are organized into a navigable hierarchy:
 
 ```mermaid
-graph TD
+graph LR
-    subgraph wing_person["WING: Person"]
+    classDef wingPerson fill:#1e1b4b,stroke:#4f46e5,color:#e0e7ff,stroke-width:2px,rx:8px,ry:8px;
+    classDef wingProject fill:#164e63,stroke:#06b6d4,color:#cffafe,stroke-width:2px,rx:8px,ry:8px;
+    classDef room fill:#312e81,stroke:#6366f1,color:#e0e7ff,stroke-width:1px,rx:4px,ry:4px;
+    classDef closet fill:#3b0764,stroke:#8b5cf6,color:#f3e8ff,stroke-width:1px,rx:4px,ry:4px;
+    classDef drawer fill:#0f766e,stroke:#14b8a6,color:#ccfbf1,stroke-width:1px,rx:4px,ry:4px;
+    classDef tunnel_link stroke:#8b5cf6,stroke-width:2px,stroke-dasharray: 5 5;
+
+    subgraph W1 [WING: Person]
         direction TB
-        RA["Room A"] -- hall --> RB["Room B"]
+        RA["Room A"]
-        RA --> CA["Closet"]
+        RB["Room B"]
-        CA --> DA["Drawer (verbatim)"]
+        CA["Closet"]
+        DA["Drawer (verbatim)"]
+        
+        RA -- "hall" --> RB
+        RA --> CA --> DA
     end
 
-    subgraph wing_project["WING: Project"]
+    subgraph W2 [WING: Project]
         direction TB
-        RA2["Room A"] -- hall --> RC["Room C"]
+        RA2["Room A"]
-        RA2 --> CA2["Closet"]
+        RC["Room C"]
-        CA2 --> DA2["Drawer (verbatim)"]
+        CA2["Closet"]
+        DA2["Drawer (verbatim)"]
+        
+        RA2 -- "hall" --> RC
+        RA2 --> CA2 --> DA2
     end
 
-    RA -.->|tunnel| RA2
+    RA <==> |tunnel bridge| RA2
 
-    style wing_person fill:#1e1b4b,stroke:#4f46e5,color:#e0e7ff
+    class W1 wingPerson;
-    style wing_project fill:#164e63,stroke:#06b6d4,color:#cffafe
+    class W2 wingProject;
-    style RA fill:#312e81,stroke:#6366f1,color:#e0e7ff
+    class RA,RB,RA2,RC room;
-    style RB fill:#312e81,stroke:#6366f1,color:#e0e7ff
+    class CA,CA2 closet;
-    style CA fill:#3b0764,stroke:#8b5cf6,color:#f3e8ff
+    class DA,DA2 drawer;
-    style DA fill:#0f766e,stroke:#14b8a6,color:#ccfbf1
-    style RA2 fill:#155e75,stroke:#22d3ee,color:#cffafe
-    style RC fill:#155e75,stroke:#22d3ee,color:#cffafe
-    style CA2 fill:#3b0764,stroke:#8b5cf6,color:#f3e8ff
-    style DA2 fill:#0f766e,stroke:#14b8a6,color:#ccfbf1
 ```
 
 ## Components

website/guide/getting-started.md

@@ -8,6 +8,10 @@ Install MemPalace from PyPI:
 pip install mempalace
 ```
 
+::: danger Security Warning
+The domain `mempalace.tech` is a **brand-squatting site** not affiliated with this project. It is known to run ad-redirects and potential malware. The official MemPalace distribution is only available via this [GitHub repository](https://github.com/milla-jovovich/mempalace) and [PyPI](https://pypi.org/project/mempalace/). Never install binaries or scripts from unofficial domains.
+:::
+
 ### Requirements
 
 - Python 3.9+

website/guide/mcp-integration.md

@@ -4,6 +4,14 @@ MemPalace provides 19 tools through the [Model Context Protocol (MCP)](https://m
 
 ## Setup
 
+### Setup Helper
+
+MemPalace includes a setup helper that prints the exact configuration commands for your environment:
+
+```bash
+mempalace mcp
+```
+
 ### Manual Connection
 
 ```bash
@@ -27,6 +35,7 @@ Claude calls `mempalace_search` automatically, gets verbatim results, and answer
 MemPalace works with any tool that supports MCP:
 
 - **Claude Code** — native via plugin or manual MCP
+- **OpenClaw** — via official skill, see [OpenClaw Skill](/guide/openclaw)
 - **ChatGPT** — via MCP bridge
 - **Cursor** — native MCP support
 - **Gemini CLI** — see [Gemini CLI guide](/guide/gemini-cli)

website/guide/openclaw.md

@@ -0,0 +1,35 @@
+# OpenClaw Skill
+
+MemPalace provides an official skill for [OpenClaw](https://github.com/openclaw/openclaw), making it trivial to give your ClawHub agents complete access to the palace's declarative memory and knowledge graph.
+
+## Installation
+
+The skill is built right into the `integrations/openclaw` directory of MemPalace. 
+
+You can add MemPalace as an MCP server to OpenClaw via the CLI:
+
+```bash
+openclaw mcp set mempalace '{"command":"python3","args":["-m","mempalace.mcp_server"]}'
+```
+
+Or by directly editing your OpenClaw configuration:
+
+```json
+{
+  "mcpServers": {
+    "mempalace": {
+      "command": "python3",
+      "args": ["-m", "mempalace.mcp_server"]
+    }
+  }
+}
+```
+
+## How It Works
+
+Once connected, OpenClaw agents receive all 19 tools along with the **Memory Protocol**—a strict behavioral guide indicating they should:
+1. **Never guess**: Query `mempalace_search` or `mempalace_kg_query` before confidently answering.
+2. **Keep an agent diary**: Maintain continuity between sessions by writing to `mempalace_diary_write`.
+3. **Manage the Knowledge Graph**: Update declarative facts when things change using `mempalace_kg_add` and `mempalace_kg_invalidate`.
+
+By connecting OpenClaw to MemPalace, you get both autonomous code execution and persistent, high-recall memory in the same workflow.

website/reference/cli.md

@@ -128,6 +128,15 @@ mempalace repair
 
 Creates a backup at `<palace_path>.backup` before rebuilding.
 
+## `mempalace mcp`
+
+Helper command that outputs setup syntax (like `claude mcp add...`) to connect MemPalace to your AI client, automatically handling paths.
+
+```bash
+mempalace mcp
+mempalace mcp --palace ~/.custom-palace
+```
+
 ## `mempalace hook`
 
 Run hook logic for Claude Code / Codex integration.

website/reference/mcp-tools.md

@@ -68,7 +68,7 @@ Check if content already exists in the palace before filing.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `content` | string | **Yes** | Content to check |
-| `threshold` | number | No | Similarity threshold 0–1 (default: 0.9) |
+| `threshold` | number | No | Similarity threshold 0–1 (default: 0.85–0.87) |
 
 **Returns:** `{ is_duplicate, matches: [{ id, wing, room, similarity, content }] }`