Files

T

2026-05-09 10:59:58 -05:00

10 KiB

Raw Blame History

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 ?"
`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:

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

10 KiB Raw Blame History Unescape Escape