Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions .antigravity-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,12 @@ This directory is the source of truth for what gets installed at
├── mcp_config.json # auto-registers the mempalace-mcp stdio server
├── hooks.json.tmpl # template — installer renders to hooks.json
├── skills/
│ └── mempalace/
│ └── SKILL.md # the in-plugin skill discovered by Antigravity
│ ├── mempalace/
│ │ └── SKILL.md # ops skill: setup, mine, status, CLI delegation
│ └── mempalace-recall/
│ └── SKILL.md # recall-only skill: search-before-answer protocol
├── rules/
│ └── mempalace-recall.md # optional recall rule (complements the skill)
└── README.md # this file
```

Expand All @@ -23,6 +27,35 @@ copies them into `<install-dir>/hooks/` and renders `hooks.json.tmpl`
into a `hooks.json` whose `command` paths point at the absolute install
location.

## Three recall layers

MemPalace can store everything, but it only helps if the agent actually
*reads* the palace before answering. Three layers wire that in, from
eager to on-demand:

1. **Wake hook** (`hooks/antigravity/mempal_wake_hook_antigravity.sh`,
`PreInvocation` event, gated to `invocationNum == 1`). On the first
model call of a conversation it runs `mempalace wake-up` and injects
the **actual palace content verbatim** via Antigravity's
`injectSteps[].ephemeralMessage` output. This is Antigravity's native
equivalent of Cursor's `sessionStart` `additional_context`, except it
delivers the memory itself rather than a directive to go fetch it.
2. **Recall skill** (`skills/mempalace-recall/SKILL.md`). The
search-before-answer protocol the agent follows when a turn is
recall-relevant — tool selection, unhappy paths, anti-patterns. It
covers recall only; the `mempalace` skill covers setup / mine /
status.
3. **Optional recall rule** (`rules/mempalace-recall.md`). A lightweight
markdown rule that nudges the agent to search before answering when
Antigravity's matcher decides the turn is recall-relevant. It is
deliberately recall-scoped (not an always-on global rule) so it never
adds latency to greenfield work, honouring MemPalace's "memory should
feel instant" budget.

All three point to the single canonical protocol in
[`integrations/shared/recall-protocol.md`](../integrations/shared/recall-protocol.md)
so the skill and rule never drift.

## Install

```bash
Expand Down
18 changes: 18 additions & 0 deletions .antigravity-plugin/rules/mempalace-recall.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# MemPalace recall

Before answering anything that may already be in the user's memory
palace — past work, prior decisions, a person, a project, or "what did
we do / decide / discuss last time?" — search the palace first:

1. Call `mempalace_search` with a short keyword query. Use
`mempalace_kg_query` for relational or time-bound facts.
2. Quote the drawer's **verbatim** text. Never summarize or paraphrase
stored content.
3. If results are empty, say so — do not invent an answer. If the MCP
server is unavailable, surface the error; do not fall back to guessing.

Skip recall for pure greenfield work with no memory relevance (renaming
a variable, fixing a typo). Recall is question-driven, not reflexive.

Full protocol: <https://github.com/MemPalace/mempalace/blob/main/integrations/shared/recall-protocol.md>. Deeper guidance:
the `mempalace-recall` skill.
113 changes: 113 additions & 0 deletions .antigravity-plugin/skills/mempalace-recall/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
---
name: mempalace-recall
description: "Recall protocol for MemPalace — search the palace before answering about past work, people, projects, or prior decisions. Apply when the user asks what was decided, what happened before, who someone is, what was discussed last time, or anything that may already be filed in their memory palace; or when mempalace-recall is invoked. Complements the mempalace setup skill and requires the mempalace-mcp server."
---

# MemPalace Recall

Search-before-answer protocol for MemPalace. This skill makes the agent
read the user's memory palace before answering anything that may already
be filed there, instead of guessing from model memory. It complements
the `mempalace` skill, which covers install / mine / status; this one
covers recall only.

## Step 0 — Verify MemPalace is available

Before relying on recall, confirm MemPalace is installed and reachable:

- Official release page: <https://github.com/MemPalace/mempalace/releases>
- Check installed: `mempalace --version`
- Do not assume a version — the MCP tool set is the source of truth for
what this installed build supports.

If the `mempalace_*` MCP tools are not available, tell the user the
server is not connected and point them at the `mempalace` skill to set
it up. Do not silently fall back to answering from model memory.

## Identity

Act as a senior AI-memory systems engineer with decades of experience
building verbatim recall, semantic retrieval, and temporal knowledge
graphs. Verbatim recall from the palace always beats a confident guess
from model memory — wrong is worse than slow.

## When to recall

Search the palace **before answering** whenever the user asks about
something that may already be filed:

- Past work or prior decisions — "what did we decide / try / do?"
- A person, project, or entity — "who is …", "what is …"
- An earlier session — "remember when …", "last time …", "the thing we
discussed"
- A preference, fact, or relationship that could have changed over time

Do **not** search on pure greenfield work with no memory relevance
(e.g. "rename this variable", "fix this typo"). Recall is
question-driven, not reflexive — a search on every turn wastes latency
and violates MemPalace's "memory should feel instant" budget.

## Protocol

1. On wake-up, the MemPalace PreInvocation hook injects verbatim palace
content via `injectSteps[].ephemeralMessage` on the first model call
of a conversation. If memory was injected, start from it before
searching further.
2. Before responding about people / projects / past events / prior
decisions: call `mempalace_search` first. Use `mempalace_kg_query`
for relational or time-bound facts.
3. If unsure about a fact: say "let me check the palace" and query.
4. Return the drawer's **verbatim** text. Never summarize or paraphrase
stored content — quoting the exact words is the point of the system.
5. After a substantive session, record continuity with
`mempalace_diary_write` (skip if a background hook already saved).
6. When a fact changes: `mempalace_kg_invalidate` the old fact, then
`mempalace_kg_add` the new one.

Comment on lines +50 to +70

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The protocol steps described here have already drifted from the canonical protocol defined in integrations/shared/recall-protocol.md. For example:

  • Step 3: The canonical protocol includes specific examples (name, age, relationship, preference) and the phrase "Wrong is worse than slow." which are missing here.
  • Step 4: The canonical protocol uses "Return verbatim. Quote the drawer's exact stored words. Never summarize, paraphrase, or lossy-compress..." whereas this skill uses "Return the drawer's verbatim text. Never summarize or paraphrase...".
  • Step 5: The canonical protocol has different phrasing regarding background hooks and double-filing.

While some platform-specific details (like Antigravity's PreInvocation hook in Step 1) are appropriate here, the core instructions, unhappy paths, and anti-patterns should be kept synchronized with the canonical source of truth to ensure consistent agent behavior across all integrations.

The full canonical protocol — shared verbatim with the Antigravity
recall rule and the other integrations — lives in
[`integrations/shared/recall-protocol.md`](https://github.com/MemPalace/mempalace/blob/main/integrations/shared/recall-protocol.md).

## Tool selection

| You need | Tool |
|---|---|
| Find any memory by meaning | `mempalace_search` (start here) |
| Relational / time-bound facts about an entity | `mempalace_kg_query` |
| The chronological story of an entity | `mempalace_kg_timeline` |
| Recent session continuity | `mempalace_diary_read` |
| Which wings / rooms exist (scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
| Record this session | `mempalace_diary_write` |

`mempalace_search` takes a short natural-language `query` (keywords or a
question — not a system prompt or pasted conversation) plus optional
`wing` / `room` filters and `limit` (default 5).

## Unhappy paths

- **Empty results.** Say the palace has nothing on this; do not invent an
answer. Offer to widen the search (drop the `wing` filter) or to file
the new information.
- **MCP error / server down.** Surface the error and suggest the user
run `mempalace status` or re-run the installer
(`hooks/antigravity/install.sh`). Never fall back to guessing.
- **Conflicting facts.** Trust the knowledge graph's time-valid answer;
invalidate-then-add rather than overwriting silently.

## Anti-patterns — never do these

- Answering about past work, people, or decisions from model memory when
the palace might know — search first.
- Paraphrasing or summarizing what the palace returns instead of quoting
it verbatim.
- Searching on every turn, including greenfield tasks with no memory
relevance.
- Pasting the whole conversation or a system prompt into the `query`
argument — keep queries short and keyword-driven.

## Official References

- MemPalace: <https://github.com/MemPalace/mempalace>
- MemPalace releases: <https://github.com/MemPalace/mempalace/releases>
- Antigravity documentation: <https://antigravity.google/docs>
- Agent Skills specification: <https://agentskills.io/specification>
17 changes: 16 additions & 1 deletion hooks/antigravity/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,8 @@ log info "install dir: $INSTALL_DIR"
# ── Install: directories ─────────────────────────────────────────────
run mkdir -p "$INSTALL_DIR" \
"$INSTALL_DIR/skills/mempalace" \
"$INSTALL_DIR/skills/mempalace-recall" \
"$INSTALL_DIR/rules" \
"$INSTALL_DIR/hooks" \
"$INSTALL_DIR/hooks/lib"

Expand All @@ -313,9 +315,22 @@ copy_file "$PLUGIN_SRC/plugin.json" "$INSTALL_DIR/plugin.json"
copy_file "$PLUGIN_SRC/mcp_config.json" "$INSTALL_DIR/mcp_config.json"
copy_file "$PLUGIN_SRC/README.md" "$INSTALL_DIR/README.md"

# ── Install: skill (real file, no symlinks at the discovery path) ────
# ── Install: skills (real files, no symlinks at the discovery path) ──
copy_file "$PLUGIN_SRC/skills/mempalace/SKILL.md" \
"$INSTALL_DIR/skills/mempalace/SKILL.md"
copy_file "$PLUGIN_SRC/skills/mempalace-recall/SKILL.md" \
"$INSTALL_DIR/skills/mempalace-recall/SKILL.md"

# ── Install: optional recall rule ────────────────────────────────────
#
# Antigravity discovers markdown rules under the plugin's rules/
# directory. This one is recall-only and intentionally lightweight —
# it complements the mempalace-recall skill. Shipping it as a plugin
# rule (not an always-on global rule) keeps it scoped to recall-
# relevant turns, honouring MemPalace's "memory should feel instant"
# budget.
copy_file "$PLUGIN_SRC/rules/mempalace-recall.md" \
"$INSTALL_DIR/rules/mempalace-recall.md"

# ── Install: hooks ───────────────────────────────────────────────────
copy_file "$HOOKS_SRC/lib/common.sh" "$INSTALL_DIR/hooks/lib/common.sh"
Expand Down
92 changes: 92 additions & 0 deletions integrations/shared/recall-protocol.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# MemPalace Recall Protocol

The canonical "search before answering" protocol shared across every
MemPalace integration (Cursor, Antigravity, Claude Code, Codex,
OpenClaw). This file is the single source of truth — skills and rules
should link here rather than restating the protocol, so the rule never
drifts from the skill.

The protocol exists to honour MemPalace's foundational promise:
**100% recall, verbatim, never guess.** When the palace might hold the
answer, the agent must read the palace before answering from model
memory.

## When to recall

Search the palace **before answering** whenever the user asks about
anything that may already be filed:

- Past work, prior decisions, or "what did we do / decide / try?"
- A person, project, or entity ("who is …", "what is …")
- Something that happened in an earlier session ("remember when …",
"last time …", "the thing we discussed")
- A preference, fact, or relationship that could have changed over time

If the question is pure greenfield work with no memory relevance (e.g.
"rename this variable", "fix this typo"), do not search — recall is
question-driven, not reflexive.

## The protocol

1. **On wake-up** (if a session-start hook injected context, honour its
wing scoping): scope recall to the wing inferred from the workspace,
then continue.
2. **Before responding** about people, projects, past events, or prior
decisions: call `mempalace_search` first. For relational or temporal
facts ("who reported to whom in March", "what was true then"), call
`mempalace_kg_query` instead or as well.
3. **If unsure** about a fact (name, age, relationship, preference): say
"let me check the palace" and query. Wrong is worse than slow.
4. **Return verbatim.** Quote the drawer's exact stored words. Never
summarize, paraphrase, or lossy-compress what the palace returns —
that is the whole point of the system.
5. **After a substantive session**, record continuity with
`mempalace_diary_write` (background hooks may already do this — do not
double-file).
6. **When a fact changes**, call `mempalace_kg_invalidate` on the old
fact, then `mempalace_kg_add` for the new one.

## Tool selection

| You need | Tool |
|---|---|
| Find any memory by meaning | `mempalace_search` (start here) |
| Relational / time-bound facts about an entity | `mempalace_kg_query` |
| The chronological story of an entity | `mempalace_kg_timeline` |
| Recent session continuity | `mempalace_diary_read` |
| Which wings / rooms exist (when scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
| Record this session | `mempalace_diary_write` |

`mempalace_search` takes a short natural-language `query` (keywords or a
question — not a system prompt or pasted conversation) plus optional
`wing` / `room` filters and `limit` (default 5).

## Unhappy paths

- **Empty results.** Say the palace has nothing on this; do not invent an
answer to fill the gap. Offer to widen the search (drop the wing
filter) or to file the new information.
- **MCP unavailable / tool error.** Surface the error plainly and suggest
the user verify the server (`mempalace status`, or re-run install).
Do not silently fall back to guessing from model memory.
- **Stale or conflicting facts.** Prefer the knowledge graph's
time-valid answer; if a fact has changed, invalidate the old one and
add the new one rather than overwriting context silently.

## Anti-patterns

- Answering about past work, people, or decisions from model memory when
the palace might know — search first.
- Paraphrasing or summarizing stored content instead of quoting it
verbatim.
- Searching reflexively on every turn, including pure greenfield coding
with no memory relevance.
- Pasting the full conversation or a system prompt into the `query`
argument — keep queries short and keyword-driven.

## See also

- [`integrations/openclaw/SKILL.md`](../openclaw/SKILL.md) — the original
full-protocol skill this is distilled from.
- MemPalace design principles (verbatim, local-first, never summarize):
<https://github.com/MemPalace/mempalace>
Loading
Loading