208 lines
10 KiB
Markdown
208 lines
10 KiB
Markdown
# MemPalace — Agent Usage Guide
|
||
|
||
> **For AI agents using MemPalace as memory.** Drop this file into `~/.claude/CLAUDE.md`, a project's `CLAUDE.md`, or paste into Codex / Antigravity system prompts. Tells the agent *that* memory exists, *how* it's structured, and *when* to use which tool.
|
||
|
||
You have access to **MemPalace**, a verbatim memory system reachable through MCP tools (the `mempalace_*` family). It stores everything the user has said to you previously, organized into a searchable structure. Use it. Don't pretend to forget what you've stored, and don't paraphrase or summarize what you find — return user content exactly as it was written.
|
||
|
||
---
|
||
|
||
## Mental model
|
||
|
||
```
|
||
WING (broad bucket — a project, a person, a topic)
|
||
└── ROOM (sub-bucket — backend, decisions, day-2026-05-09)
|
||
└── DRAWER (one verbatim chunk of text)
|
||
```
|
||
|
||
The palace is structured so searches can be **scoped** rather than brute-forced against a flat corpus. Filter by `wing` and `room` whenever you know which one the answer lives in — it's faster and more precise.
|
||
|
||
A separate **knowledge graph** layer stores facts as `subject — predicate — object` triples with `valid_from` / `valid_to` dates. Use it for explicit relationships ("Alice manages project X from 2025-03-01") rather than free-text recall.
|
||
|
||
**Tunnels** link related wings together. Useful when projects share themes: a search in wing A can follow tunnels to find drawers in wing B.
|
||
|
||
---
|
||
|
||
## When to reach for memory
|
||
|
||
Call `mempalace_search` (or a more specific tool below) **before** answering when:
|
||
|
||
- The user references prior decisions, conversations, or work *("we talked about X last week")*
|
||
- The user asks about a person, project, or topic by name
|
||
- You're about to give an opinion on a codebase or domain you've discussed before
|
||
- A new session starts and you need context — start with `mempalace_status` then `mempalace_list_wings`
|
||
- The user contradicts something you said — search for the original to verify
|
||
|
||
**Don't search** for trivial things you already know from the current conversation, generic programming questions, or anything in the prompt context window.
|
||
|
||
---
|
||
|
||
## Tools by frequency of use
|
||
|
||
### Daily — these are the workhorses
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_search(query, wing?, room?, limit?)` | You need to recall *anything* about a topic. Keep `query` short — keywords or one sentence, max 250 chars. Filter by `wing` if you know the project. |
|
||
| `mempalace_status()` | Start of session, when you want a sense of how much history exists. Returns total drawers + breakdown by wing/room. |
|
||
| `mempalace_list_wings()` | "What projects/people have I talked to this user about?" |
|
||
| `mempalace_list_rooms(wing)` | After picking a wing — "what aspects of this project are filed?" |
|
||
|
||
### Filing new content (less often than you think)
|
||
|
||
The auto-save hooks file your conversations automatically. You almost never need to call `mempalace_add_drawer` for chat content — it's already being captured. Use it when:
|
||
|
||
- The user explicitly says "remember this" or "save this for later"
|
||
- You produce a piece of structured output (a design decision, a config snippet, a quoted user preference) that warrants its own retrieval handle
|
||
- You're working from external content (a pasted doc, a tool result) that should outlive the conversation
|
||
|
||
```
|
||
mempalace_add_drawer(
|
||
wing="<project-name>",
|
||
room="decisions" | "config" | "preferences" | ...,
|
||
content="<exact text — never summarize>"
|
||
)
|
||
```
|
||
|
||
Always `mempalace_check_duplicate(content)` first if you're not sure whether you've filed something similar — the palace dedups but the check tells you what already exists.
|
||
|
||
### Knowledge graph — for facts, not for prose
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_kg_query(subject?, predicate?, object?, as_of?)` | "What does the user own / work on / report to as of <date>?" |
|
||
| `mempalace_kg_add(subject, predicate, object, valid_from?, valid_to?)` | The user states a durable fact — relationships, employment, preferences with a clear scope. |
|
||
| `mempalace_kg_invalidate(subject, predicate, object, ended)` | A fact stopped being true — close the validity window instead of deleting. |
|
||
| `mempalace_kg_timeline(entity)` | Show all facts about an entity over time. |
|
||
| `mempalace_kg_stats()` | Sanity check — how many triples exist. |
|
||
|
||
Don't use the KG for vague things ("user likes minimalism"). Use it for crisp triples where each component is a real entity name.
|
||
|
||
### Cross-wing exploration
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_traverse(start_wing, depth?)` | Walk the palace graph from a starting point. Useful for "what's adjacent to project X?" |
|
||
| `mempalace_find_tunnels(from_wing, to_wing)` | "Are these two projects connected, and how?" |
|
||
| `mempalace_follow_tunnels(wing)` | After a search lands in one wing, see what other wings are linked. |
|
||
| `mempalace_create_tunnel(wing_a, wing_b, kind?)` | The user mentions two projects share concepts/people — link them. |
|
||
| `mempalace_list_tunnels()` / `mempalace_delete_tunnel(...)` | Inspection / cleanup. |
|
||
|
||
### Drawer management
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_get_drawer(drawer_id)` | You have an ID from a previous search and want the full content. |
|
||
| `mempalace_list_drawers(wing, room?)` | Browse a room. Use when search isn't returning what you expect. |
|
||
| `mempalace_update_drawer(drawer_id, content)` | Rare — only when correcting a stored drawer's content. |
|
||
| `mempalace_delete_drawer(drawer_id)` | The user explicitly asks to forget something. Irreversible. |
|
||
|
||
### Diary
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_diary_write(agent, content)` | You want to leave a note for your future self that's distinct from user content. Each agent gets its own wing. |
|
||
| `mempalace_diary_read(agent, limit?)` | Read your prior diary entries — gives you continuity across sessions. |
|
||
|
||
### Maintenance — rarely needed
|
||
|
||
| Tool | Use when |
|
||
|---|---|
|
||
| `mempalace_get_taxonomy()` | Full wing → room → count tree. Heavy; prefer `list_wings` + `list_rooms`. |
|
||
| `mempalace_get_aaak_spec()` | You want to scan a compressed index instead of full-text searching. Advanced. |
|
||
| `mempalace_sync(apply?)` | Prune drawers whose source files were deleted/moved. Operator decision; don't apply without asking. |
|
||
| `mempalace_hook_settings()` | Read auto-save hook config. Diagnostic. |
|
||
| `mempalace_memories_filed_away()` | Returns a confirmation banner — used by the hooks, not by you directly. |
|
||
| `mempalace_reconnect()` | Force a cache refresh after external writes. Use only if results look stale. |
|
||
|
||
---
|
||
|
||
## Workflow patterns
|
||
|
||
### New session, unknown context
|
||
|
||
```
|
||
1. mempalace_status() → "23,000 drawers across 14 wings"
|
||
2. mempalace_list_wings() → see project names
|
||
3. (user mentions project X)
|
||
4. mempalace_list_rooms(wing="x") → see what's filed
|
||
5. mempalace_search(query="...", wing="x")
|
||
```
|
||
|
||
### User asks about a past decision
|
||
|
||
```
|
||
1. mempalace_search(query="why did we pick redis", wing="<project>")
|
||
2. If the top hit's distance is < 1.0 — that's the answer; quote it verbatim.
|
||
3. If distance is 1.0–1.5 — relevant but tangential; show it and ask if it's what they meant.
|
||
4. If > 1.5 — say you don't have a stored decision on that and ask if they want to file one now.
|
||
```
|
||
|
||
### User provides a durable fact
|
||
|
||
User: *"I've moved from Acme to Globex as of Monday."*
|
||
|
||
```
|
||
1. mempalace_kg_invalidate(
|
||
subject="user", predicate="works_at", object="Acme",
|
||
ended="2026-05-04" # or whatever Monday resolves to
|
||
)
|
||
2. mempalace_kg_add(
|
||
subject="user", predicate="works_at", object="Globex",
|
||
valid_from="2026-05-04"
|
||
)
|
||
```
|
||
|
||
### User shares a config or design doc
|
||
|
||
```
|
||
1. mempalace_check_duplicate(content="<the doc>")
|
||
2. If new:
|
||
mempalace_add_drawer(
|
||
wing="<project>",
|
||
room="config" | "design" | "specs",
|
||
content="<exact pasted content — do NOT reformat>"
|
||
)
|
||
3. Return the drawer_id so the user can reference it later.
|
||
```
|
||
|
||
---
|
||
|
||
## Anti-patterns
|
||
|
||
These violate the system's design and degrade memory quality:
|
||
|
||
- ❌ **Summarizing user content before filing.** Store exact words. The whole point of MemPalace is verbatim recall.
|
||
- ❌ **Paraphrasing search results when reporting them back.** Quote the drawer. Use blockquotes.
|
||
- ❌ **Filing every conversation turn manually.** The auto-save hooks (`Stop` / `PreCompact`) handle session capture. Filing manually duplicates work and can cause `MineAlreadyRunning` collisions.
|
||
- ❌ **Using free-text drawers for crisp facts.** A relationship like "Alice → manages → ProjectX from 2025-03-01" belongs in the knowledge graph (`mempalace_kg_add`), not as prose in a drawer.
|
||
- ❌ **Putting room names where wing names go.** Wings are top-level (people/projects); rooms live inside them. `wing="backend"` is almost always wrong unless "backend" is literally a project.
|
||
- ❌ **Long search queries.** `query` has a 250-char limit and works best with 3–10 keywords. Put background reasoning in `context`, not `query`.
|
||
- ❌ **Calling `mempalace_delete_drawer` without explicit user instruction.** Irreversible. Always confirm.
|
||
|
||
---
|
||
|
||
## Things you don't need to worry about
|
||
|
||
- **Authentication.** The MCP transport handles bearer tokens transparently. Don't try to inject `Authorization` headers in tool args.
|
||
- **Token / data limits.** Drawer content is unlimited within reason; the server caps individual transcript uploads at 50 MB.
|
||
- **Session persistence.** Auto-save hooks capture transcripts every 15 user turns and at PreCompact. You can rely on it. If the user worries about losing context, point them at the hook log: `~/.mempalace/hook_state/hook.log`.
|
||
- **Cross-machine sync.** All clients (Claude Code, Codex, Antigravity, on any machine) point at the same palace. What you file from one machine is searchable from another instantly.
|
||
- **Embedding model.** Server-side, runs locally on CPU. No API key, no cloud round-trip.
|
||
|
||
---
|
||
|
||
## When the system is unavailable
|
||
|
||
If MCP tool calls fail (timeout, 401, connection refused), tell the user clearly: "I can't reach MemPalace right now — the server may be down or the token is wrong." Don't fall back to inventing memory. Don't pretend you remember things you'd normally retrieve.
|
||
|
||
Diagnostics the user can run:
|
||
|
||
```bash
|
||
# from any client machine:
|
||
curl -k "$MEMPAL_REMOTE_URL/healthz"
|
||
|
||
# expected: {"status":"ok","version":"3.3.x"}
|
||
```
|
||
|
||
If that fails, the server is down. If it succeeds but tool calls still fail, the bearer token is wrong or the MCP client config is stale.
|