From a511dc9b945d48b9b0fe95f8775743189ed33e73 Mon Sep 17 00:00:00 2001 From: Grace Gettert Date: Tue, 21 Jul 2026 23:17:07 +0000 Subject: [PATCH 1/2] docs(openclaw): document KG supersede in skill Requested-by: Grace Gettert --- integrations/openclaw/SKILL.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/integrations/openclaw/SKILL.md b/integrations/openclaw/SKILL.md index 7d8a5a0322..8b7206ab1e 100644 --- a/integrations/openclaw/SKILL.md +++ b/integrations/openclaw/SKILL.md @@ -42,7 +42,7 @@ You have access to a local memory palace via MCP tools. The palace stores verbat 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. +5. **WHEN FACTS CHANGE**: For single-valued replacements (model, employer, owner, address, current status), call `mempalace_kg_supersede`. Use `mempalace_kg_invalidate` only when a fact ends without a replacement, and `mempalace_kg_add` for independent facts that can coexist. ## Available Tools @@ -82,6 +82,10 @@ tool-specific workflow below says to. - `subject`, `predicate`, `object` (required) - `valid_from`: when this became true - `source_closet`: source reference +- `mempalace_kg_supersede` — Atomically replace one single-valued fact with its successor at a shared boundary + - `subject`, `predicate`, `old_object`, `new_object` (required) + - `at`: boundary instant; defaults to now UTC + - Use for changing model, employer, address, owner, or current status so point-in-time queries return only the new value at the boundary - `mempalace_kg_invalidate` — Mark a fact as no longer true - `subject`, `predicate`, `object` (required) - `ended`: when it stopped being true (default: today) @@ -208,6 +212,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server - 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. +- For single-valued facts that change, use `mempalace_kg_supersede`; do not hand-roll invalidate + add because boundary queries can briefly show both values. - 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. From aa4ceb467045cf28f7895a4baa6cc691b21b9595 Mon Sep 17 00:00:00 2001 From: Grace Gettert Date: Tue, 21 Jul 2026 23:41:30 +0000 Subject: [PATCH 2/2] docs(openclaw): streamline MemPalace skill Requested-by: Grace Gettert --- integrations/openclaw/SKILL.md | 265 +++++------------- integrations/openclaw/references/setup.md | 34 +++ .../openclaw/references/tool-selection.md | 55 ++++ 3 files changed, 158 insertions(+), 196 deletions(-) create mode 100644 integrations/openclaw/references/setup.md create mode 100644 integrations/openclaw/references/tool-selection.md diff --git a/integrations/openclaw/SKILL.md b/integrations/openclaw/SKILL.md index 8b7206ab1e..f684bd2939 100644 --- a/integrations/openclaw/SKILL.md +++ b/integrations/openclaw/SKILL.md @@ -1,222 +1,95 @@ --- 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." +description: "MemPalace memory: semantic search, temporal KG, diary, and palace graph MCP tools." version: 3.7.0 homepage: https://github.com/MemPalace/mempalace user-invocable: true metadata: openclaw: - emoji: "\U0001F3DB" - os: - - darwin - - linux - - win32 + emoji: "🏛" + os: [darwin, linux, win32] requires: - anyBins: - - mempalace - - python3 + anyBins: [mempalace, python3] install: - id: mempalace-pip kind: uv label: "Install MemPalace (Python, local ChromaDB)" package: mempalace - bins: - - 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. +Use MemPalace when the user asks about memories, people, projects, past work, +durable facts, session recap, or knowledge graph state. It stores verbatim +drawers and temporal facts locally; no cloud service is required. ## 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**: For single-valued replacements (model, employer, owner, address, current status), call `mempalace_kg_supersede`. Use `mempalace_kg_invalidate` only when a fact ends without a replacement, and `mempalace_kg_add` for independent facts that can coexist. - -## Available Tools - -Full MCP surface: 36 tools. Destructive or host-level tools are documented so -you know they exist, but use them only when the user explicitly asks or when a -tool-specific workflow below says to. - -### 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_list_drawers` — Paginated drawer listing - - `wing`, `room`: optional filters - - `since`: only drawers filed on/after this ISO date/time - - `before`: only drawers filed before this ISO date/time - - `limit`: max results (default 20) - - `offset`: pagination offset (default 0) -- `mempalace_get_drawer` — Fetch a single drawer by ID. Returns full verbatim content and metadata. - - `drawer_id` (required) -- `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_supersede` — Atomically replace one single-valued fact with its successor at a shared boundary - - `subject`, `predicate`, `old_object`, `new_object` (required) - - `at`: boundary instant; defaults to now UTC - - Use for changing model, employer, address, owner, or current status so point-in-time queries return only the new value at the boundary -- `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 via *implicit* overlap (rooms whose drawers naturally share content across wings — discovered, not declared) - - `wing_a`, `wing_b`: optional filters; omit both to scan all wing pairs -- `mempalace_create_tunnel` — Create an *explicit* cross-wing tunnel: a user/agent-declared link between two locations. Use when you notice content in one project relates to another (e.g. API design in `project_api` connects to schema in `project_database`). - - `source_wing`, `source_room`, `target_wing`, `target_room` (required) - - `label`: short description of the relationship - - `source_drawer_id`, `target_drawer_id`: anchor to specific drawers -- `mempalace_list_tunnels` — List all explicit tunnels, optionally filtered by wing - - `wing`: optional filter -- `mempalace_delete_tunnel` — Remove an explicit tunnel by ID - - `tunnel_id` (required) -- `mempalace_list_hallways` — List within-wing entity hallways (entity-to-entity co-occurrence links built at mine time) - - `wing`: optional filter -- `mempalace_delete_hallway` — Remove a hallway record by ID - - `hallway_id` (required) -- `mempalace_follow_tunnels` — From a room, follow explicit tunnels to connected drawers in other wings - - `wing`, `room` (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 - - `added_by`: optional filing agent label - - Checks for duplicates automatically -- `mempalace_checkpoint` — Save a whole session in one call: dedup each item, file non-duplicates, then write one diary entry - - `items` (required): array of `{wing, room, content}`; content must be verbatim - - `diary`: optional `{agent_name, entry, topic?, wing?}`; entry should use AAAK format - - `dedup_threshold`: similarity threshold (default 0.9) - - `added_by`: optional filing agent label (defaults to the diary `agent_name`, else `checkpoint`) -- `mempalace_update_drawer` — Update an existing drawer's content and/or move it to a different wing/room - - `drawer_id` (required) - - `content`, `wing`, `room`: at least one must be provided (no-op otherwise) -- `mempalace_delete_drawer` — Remove a drawer by ID - - `drawer_id` (required) - -### Ingest & Cleanup -- `mempalace_mine` — Mine a directory into the palace. Host-level ingest; call only when the user asks to import files. - - `source` (required): directory to mine - - `mode`: `projects` (default), `convos`, or `extract` - - `wing`: target wing (default: source directory name) - - `agent`: recorded on every drawer (default `mempalace`) - - `limit`: max files to process (0 = all) - - `dry_run`: preview without writing - - `extract`: convos extraction strategy (`exchange` default, or `general`) -- `mempalace_sync` — Prune drawers whose source files are gitignored, deleted, or moved. Use dry-run first. - - `project_dir`: optional project root scope - - `wing`: optional wing scope - - `apply`: actually delete; default is dry-run preview -- `mempalace_delete_by_source` — Bulk-delete drawers with one exact `source_file`. Destructive; use dry-run first. - - `source_file` (required): exact metadata value to remove - - `dry_run`: preview match count and sample (default true) - -### Diary & Session -- `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) -- `mempalace_memories_filed_away` — Acknowledge the latest silent auto-save checkpoint. - - Returns: how many messages were tucked into drawers since the last ack - - When to call: at the START of a session, to confirm prior-conversation persistence - -### System -- `mempalace_hook_settings` — Get or set auto-save hook behavior. Host-level setting; do not change silently. - - `silent_save`: true saves directly without MCP-level clutter - - `desktop_toast`: true shows a desktop notification when saves complete -- `mempalace_reconnect` — Force reconnect to the palace database after external writes or stale index state - -## Setup - -Install MemPalace and populate the palace (uv recommended): - -```bash -uv tool install mempalace # or: 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 -``` +- **Wings**: people, projects, or domains. +- **Rooms**: topics within a wing. +- **Drawers**: verbatim memory chunks. +- **Knowledge Graph**: typed facts with temporal validity. +- **Tunnels / hallways**: graph connections between rooms and entities. + +## Protocol + +1. **Wake-up**: call `mempalace_status` to load the palace overview. +2. **Before answering about people, projects, or past events**: call + `mempalace_search` or `mempalace_kg_query`. Never guess from memory. +3. **If unsure about a fact**: say you are checking, then query. +4. **After meaningful sessions**: write continuity with `mempalace_diary_write`, + or use `mempalace_checkpoint` for multi-drawer wrap-ups. +5. **When facts change**: + - Single-valued replacement (model, employer, owner, address, current status) + → `mempalace_kg_supersede`. + - Fact ended with no replacement → `mempalace_kg_invalidate`. + - Independent/coexisting fact → `mempalace_kg_add`. + +Do not hand-roll invalidate + add for single-valued replacements; boundary +queries can briefly show both values. `supersede` is the correct handoff. + +## Tool selection + +Start with search for context, use KG tools for durable time-valid facts, and +file durable context verbatim. + +- Search/browse: `mempalace_search`, `mempalace_get_drawer`, list/taxonomy + tools, duplicate checks, and `mempalace_get_aaak_spec`. +- Knowledge graph: `mempalace_kg_query`, `mempalace_kg_add`, + `mempalace_kg_supersede`, `mempalace_kg_invalidate`, timeline/stats. +- Write/diary: `mempalace_add_drawer`, `mempalace_checkpoint`, + `mempalace_update_drawer`, `mempalace_diary_write`, `mempalace_diary_read`. +- Graph/ingest/system: tunnels/hallways, `mempalace_mine`, cleanup/delete, + reconnect, hook settings, and silent-checkpoint acknowledgement. + +For detailed tool-selection guidance, read `{baseDir}/references/tool-selection.md`. +For install and MCP config examples, read `{baseDir}/references/setup.md`. + +## Unhappy paths + +- Empty results: say the palace has nothing on this; do not invent an answer. +- MCP unavailable: surface the error and suggest reconnecting/configuring the + server; do not silently fall back to model memory. +- Conflicting facts: prefer time-valid KG answers and repair the fact history + with `supersede`, `invalidate`, or `add` as appropriate. + +## Anti-patterns + +- Answering about past work, people, or decisions without searching first. +- Pasting full conversations or system prompts into `mempalace_search.query`. +- Re-mining to fix index trouble before checking repair/reconnect paths. +- Running bulk ingest, sync, or delete operations without user intent and a + dry-run/preview when available. ## 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. -- For single-valued facts that change, use `mempalace_kg_supersede`; do not hand-roll invalidate + add because boundary queries can briefly show both values. -- 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. +- Search is semantic; questions often work better than single keywords. +- Use KG facts when time validity matters. +- Include provenance (`source_file`, source drawer IDs) when filing from files. +- Read AAAK naturally: expand codes mentally and treat markers as context. ## License -[MemPalace](https://github.com/MemPalace/mempalace) is MIT licensed. Created by Milla Jovovich, Ben Sigman, Igor Lins e Silva, and contributors. +[MemPalace](https://github.com/MemPalace/mempalace) is MIT licensed. Created by +Milla Jovovich, Ben Sigman, Igor Lins e Silva, and contributors. diff --git a/integrations/openclaw/references/setup.md b/integrations/openclaw/references/setup.md new file mode 100644 index 0000000000..1eca77ce9b --- /dev/null +++ b/integrations/openclaw/references/setup.md @@ -0,0 +1,34 @@ +# MemPalace setup for OpenClaw + +Install and initialize MemPalace, then connect the MCP server from your host. + +```bash +uv tool install mempalace # or: pip install mempalace +mempalace init ~/my-convos +mempalace mine ~/my-convos +``` + +OpenClaw MCP config: + +```json +{ + "mcpServers": { + "mempalace": { + "command": "python3", + "args": ["-m", "mempalace.mcp_server"] + } + } +} +``` + +Equivalent CLI form: + +```bash +openclaw mcp set mempalace '{"command":"python3","args":["-m","mempalace.mcp_server"]}' +``` + +Other MCP hosts can run the same server command, for example: + +```bash +claude mcp add mempalace -- python -m mempalace.mcp_server +``` diff --git a/integrations/openclaw/references/tool-selection.md b/integrations/openclaw/references/tool-selection.md new file mode 100644 index 0000000000..804b46c07c --- /dev/null +++ b/integrations/openclaw/references/tool-selection.md @@ -0,0 +1,55 @@ +# MemPalace tool selection + +Use this reference when the compact OpenClaw skill does not contain enough detail +to choose between MemPalace MCP tools. + +## Search and browse + +Start with search for context, then fetch exact drawers when precision matters. + +- `mempalace_search` — semantic search. Keep `query` short; put background in + `context` if available. +- `mempalace_check_duplicate` — check before filing standalone drawers. +- `mempalace_list_wings`, `mempalace_list_rooms`, `mempalace_list_drawers` — + browse taxonomy and recent/filtered drawers. +- `mempalace_get_drawer`, `mempalace_get_taxonomy`, `mempalace_status` — exact + drawer/taxonomy/overview lookup. +- `mempalace_get_aaak_spec` — read the compressed diary/memory dialect. + +## Knowledge graph + +Use KG tools for durable facts about people, projects, ownership, status, +relationships, and dates. + +- `mempalace_kg_query` — current or point-in-time entity facts. +- `mempalace_kg_add` — add an independent fact. +- `mempalace_kg_supersede` — atomically replace one single-valued fact. +- `mempalace_kg_invalidate` — end a fact without replacement. +- `mempalace_kg_timeline`, `mempalace_kg_stats` — inspect graph history/health. + +## Write and diary + +Store durable context verbatim. Do not summarize so far that original meaning is +lost. + +- `mempalace_add_drawer` — file one drawer in a wing/room. +- `mempalace_checkpoint` — semantic-dedup several drawers plus one diary entry. +- `mempalace_update_drawer` — correct or move an existing drawer. +- `mempalace_diary_write`, `mempalace_diary_read` — continuity index across + sessions; use AAAK when the convention calls for it. + +## Graph, ingest, and cleanup + +Use graph tools when relationships between topics matter. Ingest/cleanup tools +can alter many memories or host state, so prefer dry runs and explicit user +intent before destructive actions. + +- Graph: `mempalace_traverse`, `mempalace_follow_tunnels`, + `mempalace_find_tunnels`, `mempalace_list_tunnels`, + `mempalace_create_tunnel`, `mempalace_delete_tunnel`, + `mempalace_list_hallways`, `mempalace_delete_hallway`, + `mempalace_graph_stats`. +- Ingest/cleanup: `mempalace_mine`, `mempalace_sync`, + `mempalace_delete_by_source`, `mempalace_delete_drawer`. +- System/session: `mempalace_reconnect`, `mempalace_hook_settings`, + `mempalace_memories_filed_away`.