docs: add VitePress documentation site

- 22 content pages across Guide, Concepts, and Reference sections - Custom indigo/cyan theme with Lucide icons and Mermaid diagrams - GitHub Actions workflow for GitHub Pages deployment - Live preview: https://mempalace-docs.netlify.app/
2026-04-09 19:11:23 -03:00
parent 2981433535
commit dfb22f5345
37 changed files with 3673 additions and 0 deletions
@@ -0,0 +1,107 @@
+# Searching Memories
+
+MemPalace uses ChromaDB's semantic vector search to find relevant memories. When you search, you get **verbatim text** — the exact words, never summaries.
+
+## CLI Search
+
+```bash
+# Search everything
+mempalace search "why did we switch to GraphQL"
+
+# Filter by wing (project)
+mempalace search "database decision" --wing myapp
+
+# Filter by room (topic)
+mempalace search "auth decisions" --room auth-migration
+
+# Filter by both
+mempalace search "pricing" --wing driftwood --room costs
+
+# More results
+mempalace search "deploy process" --results 10
+```
+
+## How Search Works
+
+1. Your query is embedded using ChromaDB's default model (`all-MiniLM-L6-v2`)
+2. The embedding is compared against all drawers using cosine similarity
+3. Optional wing/room filters narrow the search scope
+4. Results are returned with similarity scores and source metadata
+
+### Why Structure Matters
+
+Tested on 22,000+ real conversation memories:
+
+```
+Search all closets:          60.9%  R@10
+Search within wing:          73.1%  (+12%)
+Search wing + hall:          84.8%  (+24%)
+Search wing + room:          94.8%  (+34%)
+```
+
+Wings and rooms aren't cosmetic — they're a **34% retrieval improvement**.
+
+## Programmatic Search
+
+Use the Python API for integration:
+
+```python
+from mempalace.searcher import search_memories
+
+results = search_memories(
+    query="auth decisions",
+    palace_path="~/.mempalace/palace",
+    wing="myapp",
+    room="auth",
+    n_results=5,
+)
+
+for hit in results["results"]:
+    print(f"[{hit['similarity']}] {hit['wing']}/{hit['room']}")
+    print(f"  {hit['text'][:200]}")
+```
+
+The `search_memories()` function returns a dict:
+
+```python
+{
+    "query": "auth decisions",
+    "filters": {"wing": "myapp", "room": "auth"},
+    "results": [
+        {
+            "text": "We decided to migrate auth to Clerk because...",
+            "wing": "myapp",
+            "room": "auth-migration",
+            "source_file": "session_2026-01-15.md",
+            "similarity": 0.892,
+        },
+        # ...
+    ],
+}
+```
+
+## MCP Search
+
+When connected via MCP, your AI searches automatically:
+
+> *"What did we decide about auth last month?"*
+
+The AI calls `mempalace_search` behind the scenes. You never type a search command.
+
+See [MCP Integration](/guide/mcp-integration) for setup.
+
+## Wake-Up Context
+
+Instead of searching, you can load a compact context of your world:
+
+```bash
+# Load identity + top memories (~600-900 tokens in typical use)
+mempalace wake-up
+
+# Project-specific context
+mempalace wake-up --wing driftwood
+```
+
+This loads Layer 0 (identity) and Layer 1 (essential story) as bounded startup context before the first retrieval call.
+
+See [Memory Stack](/concepts/memory-stack) for details on the 4-layer architecture.