docs: token-efficient query pattern — progressive disclosure (kg_query → search → diary_read)

[anastasiiaanfimova]

Problem

The current docs don't suggest a query order when retrieving from MemPalace. Users (and agents) tend to jump straight to mempalace_search or mempalace_diary_read even for simple fact lookups — spending 200-400 tokens when 50 would suffice.

Proposed Pattern: 3-Layer Progressive Disclosure

Inspired by claude-mem's approach, each layer costs more tokens — go deeper only if the previous layer didn't answer the question:

Layer	Tool	~Tokens	Use when
1	mempalace_kg_query(entity)	~50	Looking up facts about a known entity
2	mempalace_search(query, wing=..., room=...)	~200-400	Need semantic match, layer 1 insufficient
3	mempalace_diary_read(agent_name, last_n=5)	expensive	Need full session context or chronology

Rule: never skip to layer 3. kg_query → search → diary_read.

Also: always specify wing and room in mempalace_search when known — reduces noise and token cost.

Where to add

A "Best Practices" or "Query Guide" section in the docs, or a note in the mempalace_search / mempalace_kg_query tool descriptions themselves.

Why it matters

• kg_query returns typed facts in ~50 tokens for most "what do I know about X?" questions
• mempalace_search is 4-8x more expensive and often returns overlapping results
• diary_read with no filter is the most expensive and rarely needed for factual lookups

This pattern can significantly reduce per-session token usage for agents that query memory frequently.