Skip to content

Commit bc9c052

Browse files
igorlsigorls
authored
Merge pull request #1810 from MemPalace/develop
Release v3.4.1 — promote develop to main
2 parents be95467 + db6e4f0 commit bc9c052

126 files changed

Lines changed: 15420 additions & 393 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.antigravity-plugin/README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# MemPalace — Antigravity plugin
2+
3+
In-repo packaging for the MemPalace integration with Google's [Antigravity IDE](https://antigravity.google/).
4+
5+
This directory is the source of truth for what gets installed at
6+
`~/.gemini/config/plugins/mempalace/` when the user runs the installer.
7+
8+
## Layout
9+
10+
```
11+
.antigravity-plugin/
12+
├── plugin.json # marker manifest (verified minimal schema)
13+
├── mcp_config.json # auto-registers the mempalace-mcp stdio server
14+
├── hooks.json.tmpl # template — installer renders to hooks.json
15+
├── skills/
16+
│ ├── mempalace/
17+
│ │ └── SKILL.md # ops skill: setup, mine, status, CLI delegation
18+
│ └── mempalace-recall/
19+
│ └── SKILL.md # recall-only skill: search-before-answer protocol
20+
├── rules/
21+
│ └── mempalace-recall.md # optional recall rule (complements the skill)
22+
└── README.md # this file
23+
```
24+
25+
The hook scripts themselves live at `hooks/antigravity/`. The installer
26+
copies them into `<install-dir>/hooks/` and renders `hooks.json.tmpl`
27+
into a `hooks.json` whose `command` paths point at the absolute install
28+
location.
29+
30+
## Three recall layers
31+
32+
MemPalace can store everything, but it only helps if the agent actually
33+
*reads* the palace before answering. Three layers wire that in, from
34+
eager to on-demand:
35+
36+
1. **Wake hook** (`hooks/antigravity/mempal_wake_hook_antigravity.sh`,
37+
`PreInvocation` event, gated to `invocationNum == 1`). On the first
38+
model call of a conversation it runs `mempalace wake-up` and injects
39+
the **actual palace content verbatim** via Antigravity's
40+
`injectSteps[].ephemeralMessage` output. This is Antigravity's native
41+
equivalent of Cursor's `sessionStart` `additional_context`, except it
42+
delivers the memory itself rather than a directive to go fetch it.
43+
2. **Recall skill** (`skills/mempalace-recall/SKILL.md`). The
44+
search-before-answer protocol the agent follows when a turn is
45+
recall-relevant — tool selection, unhappy paths, anti-patterns. It
46+
covers recall only; the `mempalace` skill covers setup / mine /
47+
status.
48+
3. **Optional recall rule** (`rules/mempalace-recall.md`). A lightweight
49+
markdown rule that nudges the agent to search before answering when
50+
Antigravity's matcher decides the turn is recall-relevant. It is
51+
deliberately recall-scoped (not an always-on global rule) so it never
52+
adds latency to greenfield work, honouring MemPalace's "memory should
53+
feel instant" budget.
54+
55+
All three point to the single canonical protocol in
56+
[`integrations/shared/recall-protocol.md`](../integrations/shared/recall-protocol.md)
57+
so the skill and rule never drift.
58+
59+
## Install
60+
61+
```bash
62+
bash hooks/antigravity/install.sh
63+
```
64+
65+
The installer is idempotent and the uninstaller matches by basename, so
66+
re-runs and partial installs are safe.
67+
68+
See [website/guide/antigravity.md](../website/guide/antigravity.md) for
69+
the full user-facing guide and [hooks/antigravity/README.md](../hooks/antigravity/README.md)
70+
for the hooks-specific documentation.
71+
72+
## Verified surfaces
73+
74+
Every file in this directory maps to a surface verified against
75+
[Google's Antigravity docs](https://antigravity.google/docs/). See
76+
[hooks/antigravity/INVESTIGATION.md](../hooks/antigravity/INVESTIGATION.md)
77+
for the full audit, including the surfaces deliberately not shipped.

‎.antigravity-plugin/hooks.json.tmpl‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"mempalace-save": {
3+
"Stop": [
4+
{
5+
"type": "command",
6+
"command": "__PLUGIN_DIR__/hooks/mempal_save_hook_antigravity.sh",
7+
"timeout": 30
8+
}
9+
]
10+
},
11+
"mempalace-wake": {
12+
"PreInvocation": [
13+
{
14+
"type": "command",
15+
"command": "__PLUGIN_DIR__/hooks/mempal_wake_hook_antigravity.sh",
16+
"timeout": 5
17+
}
18+
]
19+
}
20+
}

‎.antigravity-plugin/mcp_config.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"mcpServers": {
3+
"mempalace": {
4+
"command": "mempalace-mcp"
5+
}
6+
}
7+
}

‎.antigravity-plugin/plugin.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"name": "mempalace"
3+
}

‎.antigravity-plugin/rules/mempalace-recall.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# MemPalace recall
2+
3+
Before answering anything that may already be in the user's memory
4+
palace — past work, prior decisions, a person, a project, or "what did
5+
we do / decide / discuss last time?" — search the palace first:
6+
7+
1. Call `mempalace_search` with a short keyword query. Use
8+
`mempalace_kg_query` for relational or time-bound facts.
9+
2. Quote the drawer's **verbatim** text. Never summarize or paraphrase
10+
stored content.
11+
3. If results are empty, say so — do not invent an answer. If the MCP
12+
server is unavailable, surface the error; do not fall back to guessing.
13+
14+
Skip recall for pure greenfield work with no memory relevance (renaming
15+
a variable, fixing a typo). Recall is question-driven, not reflexive.
16+
17+
Full protocol: <https://github.com/MemPalace/mempalace/blob/main/integrations/shared/recall-protocol.md>. Deeper guidance:
18+
the `mempalace-recall` skill.

‎.antigravity-plugin/skills/mempalace-recall/SKILL.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
name: mempalace-recall
3+
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."
4+
---
5+
6+
# MemPalace Recall
7+
8+
Search-before-answer protocol for MemPalace. This skill makes the agent
9+
read the user's memory palace before answering anything that may already
10+
be filed there, instead of guessing from model memory. It complements
11+
the `mempalace` skill, which covers install / mine / status; this one
12+
covers recall only.
13+
14+
## Step 0 — Verify MemPalace is available
15+
16+
Before relying on recall, confirm MemPalace is installed and reachable:
17+
18+
- Official release page: <https://github.com/MemPalace/mempalace/releases>
19+
- Check installed: `mempalace --version`
20+
- Do not assume a version — the MCP tool set is the source of truth for
21+
what this installed build supports.
22+
23+
If the `mempalace_*` MCP tools are not available, tell the user the
24+
server is not connected and point them at the `mempalace` skill to set
25+
it up. Do not silently fall back to answering from model memory.
26+
27+
## Identity
28+
29+
Act as a senior AI-memory systems engineer with decades of experience
30+
building verbatim recall, semantic retrieval, and temporal knowledge
31+
graphs. Verbatim recall from the palace always beats a confident guess
32+
from model memory — wrong is worse than slow.
33+
34+
## When to recall
35+
36+
Search the palace **before answering** whenever the user asks about
37+
something that may already be filed:
38+
39+
- Past work or prior decisions — "what did we decide / try / do?"
40+
- A person, project, or entity — "who is …", "what is …"
41+
- An earlier session — "remember when …", "last time …", "the thing we
42+
discussed"
43+
- A preference, fact, or relationship that could have changed over time
44+
45+
Do **not** search on pure greenfield work with no memory relevance
46+
(e.g. "rename this variable", "fix this typo"). Recall is
47+
question-driven, not reflexive — a search on every turn wastes latency
48+
and violates MemPalace's "memory should feel instant" budget.
49+
50+
## Protocol
51+
52+
1. On wake-up, the MemPalace PreInvocation hook injects verbatim palace
53+
content via `injectSteps[].ephemeralMessage` on the first model call
54+
of a conversation. If memory was injected, start from it before
55+
searching further.
56+
2. **Before responding** about people, projects, past events, or prior
57+
decisions: call `mempalace_search` first. For relational or temporal
58+
facts ("who reported to whom in March", "what was true then"), call
59+
`mempalace_kg_query` instead or as well.
60+
3. **If unsure** about a fact (name, age, relationship, preference): say
61+
"let me check the palace" and query. Wrong is worse than slow.
62+
4. **Return verbatim.** Quote the drawer's exact stored words. Never
63+
summarize, paraphrase, or lossy-compress what the palace returns —
64+
that is the whole point of the system.
65+
5. **After a substantive session**, record continuity with
66+
`mempalace_diary_write` (background hooks may already do this — do not
67+
double-file).
68+
6. **When a fact changes**, call `mempalace_kg_invalidate` on the old
69+
fact, then `mempalace_kg_add` for the new one.
70+
71+
The full canonical protocol — shared verbatim with the Antigravity
72+
recall rule and the other integrations — lives in
73+
[`integrations/shared/recall-protocol.md`](https://github.com/MemPalace/mempalace/blob/main/integrations/shared/recall-protocol.md).
74+
75+
## Tool selection
76+
77+
| You need | Tool |
78+
|---|---|
79+
| Find any memory by meaning | `mempalace_search` (start here) |
80+
| Relational / time-bound facts about an entity | `mempalace_kg_query` |
81+
| The chronological story of an entity | `mempalace_kg_timeline` |
82+
| Recent session continuity | `mempalace_diary_read` |
83+
| Which wings / rooms exist (scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
84+
| Record this session | `mempalace_diary_write` |
85+
86+
`mempalace_search` takes a short natural-language `query` (keywords or a
87+
question — not a system prompt or pasted conversation) plus optional
88+
`wing` / `room` filters and `limit` (default 5).
89+
90+
## Unhappy paths
91+
92+
- **Empty results.** Say the palace has nothing on this; do not invent an
93+
answer to fill the gap. Offer to widen the search (drop the wing
94+
filter) or to file the new information.
95+
- **MCP unavailable / tool error.** Surface the error plainly and suggest
96+
the user verify the server (`mempalace status`, or re-run the
97+
installer `hooks/antigravity/install.sh`). Do not silently fall back
98+
to guessing from model memory.
99+
- **Stale or conflicting facts.** Prefer the knowledge graph's
100+
time-valid answer; if a fact has changed, invalidate the old one and
101+
add the new one rather than overwriting context silently.
102+
103+
## Anti-patterns — never do these
104+
105+
- Answering about past work, people, or decisions from model memory when
106+
the palace might know — search first.
107+
- Paraphrasing or summarizing stored content instead of quoting it
108+
verbatim.
109+
- Searching reflexively on every turn, including pure greenfield coding
110+
with no memory relevance.
111+
- Pasting the full conversation or a system prompt into the `query`
112+
argument — keep queries short and keyword-driven.
113+
114+
## Official References
115+
116+
- MemPalace: <https://github.com/MemPalace/mempalace>
117+
- MemPalace releases: <https://github.com/MemPalace/mempalace/releases>
118+
- Antigravity documentation: <https://antigravity.google/docs>
119+
- Agent Skills specification: <https://agentskills.io/specification>

‎.antigravity-plugin/skills/mempalace/SKILL.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: mempalace
3+
description: MemPalace — mine projects and conversations into a searchable memory palace. Use when the user asks about MemPalace, memory palace, mining memories, searching memories, palace setup, wings, rooms, or drawers; or when they want to recall past work that may already be filed in their palace.
4+
---
5+
6+
# MemPalace
7+
8+
A searchable memory palace for AI — mine projects and conversations, then search them semantically. Verbatim storage, local-first, zero external API by default.
9+
10+
## Prerequisites
11+
12+
Ensure `mempalace` is installed:
13+
14+
```bash
15+
mempalace --version
16+
```
17+
18+
If not installed (uv recommended):
19+
20+
```bash
21+
uv tool install mempalace # or: pip install mempalace
22+
```
23+
24+
## Dynamic, version-correct instructions
25+
26+
MemPalace exposes operation-specific instructions through the CLI so this skill stays accurate as MemPalace evolves. To get instructions for any operation:
27+
28+
```bash
29+
mempalace instructions <command>
30+
```
31+
32+
Always prefer the CLI output over what is written here when the two disagree — the CLI is the single source of truth for the installed version.
33+
34+
## Common operations
35+
36+
These are the five operations users ask for most often. Each one wraps a single MemPalace CLI subcommand. The `mempalace instructions <name>` form returns the full, version-correct guidance.
37+
38+
### `help` — discover what MemPalace can do
39+
40+
```bash
41+
mempalace instructions help
42+
```
43+
44+
Use when the user is new, unsure what's possible, or asks "what can you do".
45+
46+
### `init` — first-run setup of the palace
47+
48+
```bash
49+
mempalace instructions init
50+
```
51+
52+
Use when the user has just installed MemPalace, no palace exists yet, or the user explicitly asks to set up / configure / re-initialize their palace.
53+
54+
### `mine` — ingest a project or conversation directory
55+
56+
```bash
57+
mempalace instructions mine
58+
```
59+
60+
Use when the user wants to fold a project's files into their palace, or to ingest exported conversation transcripts into the palace as searchable memory.
61+
62+
### `search` — find verbatim memories by semantic query
63+
64+
```bash
65+
mempalace instructions search
66+
```
67+
68+
Use when the user wants to recall something from the past, find a previous decision, or rediscover code/notes/conversations they already wrote.
69+
70+
### `status` — what's in the palace right now
71+
72+
```bash
73+
mempalace instructions status
74+
```
75+
76+
Use when the user asks "what's in my palace", "how big is my palace", or wants a summary of wings, rooms, and drawer counts.
77+
78+
## MCP tools (preferred over CLI)
79+
80+
Inside Antigravity, the MemPalace MCP server registers a rich set of tools. Use these instead of shelling out to the CLI for live operations (search, diary writes, drawer adds, knowledge graph queries, palace status). The MCP tools always reflect the current palace state without spawning a subprocess.
81+
82+
The MCP server is auto-registered when this plugin is installed at `~/.gemini/config/plugins/mempalace/`. If the server does not appear in Antigravity's MCP store, run `mempalace-mcp --version` to verify the binary is on PATH, then restart Antigravity.
83+
84+
## Design principles (verbatim from the project)
85+
86+
- **Verbatim always** — never summarize, paraphrase, or lossy-compress user data.
87+
- **Local-first, zero external API by default** — extraction, embedding, and LLM-assisted refinement happen on the user's machine.
88+
- **Privacy by architecture** — the system never calls out to external services for core operations.
89+
- **Performance budgets** — hooks under 500ms; startup injection under 100ms.
90+
- **Background everything** — filing, indexing, and timestamps happen via hooks in the background; zero tokens spent on bookkeeping in the chat window.
91+
92+
If a request would violate any of these principles, refuse and explain — even if it would be technically convenient.

‎.claude-plugin/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# MemPalace Claude Code Plugin
22

3-
A Claude Code plugin that gives your AI a persistent memory system. Mine projects and conversations into a searchable palace backed by ChromaDB, with 19 MCP tools, auto-save hooks, and 5 guided skills.
3+
A Claude Code plugin that gives your AI a persistent memory system. Mine projects and conversations into a searchable palace backed by ChromaDB, with 33 MCP tools, auto-save hooks, and 5 guided skills.
44

55
## Prerequisites
66

@@ -50,7 +50,7 @@ Set the `MEMPAL_DIR` environment variable to a directory path to automatically r
5050

5151
## MCP Server
5252

53-
The plugin automatically configures a local MCP server with 19 tools for storing, searching, and managing memories. No manual MCP setup is required -- `/mempalace:init` handles everything.
53+
The plugin automatically configures a local MCP server with 33 tools for storing, searching, and managing memories. No manual MCP setup is required -- `/mempalace:init` handles everything.
5454

5555
## Full Documentation
5656

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88
{
99
"name": "mempalace",
1010
"source": "./.claude-plugin",
11-
"description": "AI memory system — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, guided setup.",
12-
"version": "3.4.0",
11+
"description": "AI memory system — mine projects and conversations into a searchable palace. 33 MCP tools, auto-save hooks, guided setup.",
12+
"version": "3.4.1",
1313
"author": {
1414
"name": "milla-jovovich"
1515
}

‎.claude-plugin/plugin.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "mempalace",
3-
"version": "3.4.0",
4-
"description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, and guided setup.",
3+
"version": "3.4.1",
4+
"description": "Give your AI a memory — mine projects and conversations into a searchable palace. 33 MCP tools, auto-save hooks, and guided setup.",
55
"author": {
66
"name": "milla-jovovich"
77
},

0 commit comments

Comments
 (0)