diff --git a/integrations/openclaw/SKILL.md b/integrations/openclaw/SKILL.md new file mode 100644 index 0000000..88f0b2f --- /dev/null +++ b/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. diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index 0ecda2c..997a864 100644 --- a/website/.vitepress/config.mts +++ b/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' }, diff --git a/website/concepts/the-palace.md b/website/concepts/the-palace.md index ca94fa3..2ef01a4 100644 --- a/website/concepts/the-palace.md +++ b/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 - subgraph wing_person["WING: Person"] +graph LR + 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 --> CA["Closet"] - CA --> DA["Drawer (verbatim)"] + RA["Room A"] + RB["Room B"] + 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 --> CA2["Closet"] - CA2 --> DA2["Drawer (verbatim)"] + RA2["Room A"] + RC["Room C"] + 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 - style wing_project fill:#164e63,stroke:#06b6d4,color:#cffafe - style RA fill:#312e81,stroke:#6366f1,color:#e0e7ff - style RB fill:#312e81,stroke:#6366f1,color:#e0e7ff - style CA fill:#3b0764,stroke:#8b5cf6,color:#f3e8ff - 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 + class W1 wingPerson; + class W2 wingProject; + class RA,RB,RA2,RC room; + class CA,CA2 closet; + class DA,DA2 drawer; ``` ## Components diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md index f02259d..5d32034 100644 --- a/website/guide/getting-started.md +++ b/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+ diff --git a/website/guide/mcp-integration.md b/website/guide/mcp-integration.md index b48af9b..0e00789 100644 --- a/website/guide/mcp-integration.md +++ b/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) diff --git a/website/guide/openclaw.md b/website/guide/openclaw.md new file mode 100644 index 0000000..b6bf421 --- /dev/null +++ b/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. diff --git a/website/reference/cli.md b/website/reference/cli.md index 20c980e..3bf054c 100644 --- a/website/reference/cli.md +++ b/website/reference/cli.md @@ -128,6 +128,15 @@ mempalace repair Creates a backup at `.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. diff --git a/website/reference/mcp-tools.md b/website/reference/mcp-tools.md index 86ec550..d20d8f4 100644 --- a/website/reference/mcp-tools.md +++ b/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 }] }`