# 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.