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/
This commit is contained in:
Igor Lins e Silva
@@ -0,0 +1,38 @@
|
||||
# Claude Code Plugin
|
||||
|
||||
The recommended way to use MemPalace with Claude Code — native marketplace install.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
claude plugin marketplace add milla-jovovich/mempalace
|
||||
claude plugin install --scope user mempalace
|
||||
```
|
||||
|
||||
Restart Claude Code, then type `/skills` to verify "mempalace" appears.
|
||||
|
||||
## How It Works
|
||||
|
||||
With the plugin installed, Claude Code automatically:
|
||||
- Starts the MemPalace MCP server on launch
|
||||
- Has access to all 19 tools
|
||||
- Learns the AAAK dialect and memory protocol from the `mempalace_status` response
|
||||
- Searches the palace before answering questions about past work
|
||||
|
||||
No manual configuration needed. Just ask:
|
||||
|
||||
> *"What did we decide about auth last month?"*
|
||||
|
||||
## Alternative: Manual MCP
|
||||
|
||||
If you prefer manual setup over the marketplace plugin:
|
||||
|
||||
```bash
|
||||
claude mcp add mempalace -- python -m mempalace.mcp_server
|
||||
```
|
||||
|
||||
Both approaches give identical functionality. The plugin approach handles server lifecycle automatically.
|
||||
|
||||
## Hooks
|
||||
|
||||
Set up [auto-save hooks](/guide/hooks) to ensure memories are saved automatically during long conversations.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Configuration
|
||||
|
||||
## Global Config
|
||||
|
||||
Located at `~/.mempalace/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"palace_path": "/custom/path/to/palace",
|
||||
"collection_name": "mempalace_drawers",
|
||||
"people_map": {"Kai": "KAI", "Priya": "PRI"}
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
| `palace_path` | `~/.mempalace/palace` | Where ChromaDB stores your drawers |
|
||||
| `collection_name` | `mempalace_drawers` | ChromaDB collection name |
|
||||
| `people_map` | `{}` | Entity name → AAAK code mappings |
|
||||
|
||||
## Project Config
|
||||
|
||||
Generated by `mempalace init` in your project directory:
|
||||
|
||||
### `mempalace.yaml`
|
||||
|
||||
```yaml
|
||||
wing: myproject
|
||||
rooms:
|
||||
- backend
|
||||
- frontend
|
||||
- decisions
|
||||
palace_path: ~/.mempalace/palace
|
||||
```
|
||||
|
||||
### `entities.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"Kai": "KAI",
|
||||
"Priya": "PRI"
|
||||
}
|
||||
```
|
||||
|
||||
Wings are auto-detected during `mempalace init` from:
|
||||
- Directory names → project wings
|
||||
- Detected people in file content → person wings
|
||||
- Explicit `--wing` flag on mine commands
|
||||
|
||||
## Identity
|
||||
|
||||
Located at `~/.mempalace/identity.txt`. Plain text. Becomes Layer 0 — loaded every session.
|
||||
|
||||
```text
|
||||
I am Atlas, a personal AI assistant for Alice.
|
||||
Traits: warm, direct, remembers everything.
|
||||
People: Alice (creator), Bob (Alice's partner).
|
||||
Project: A journaling app that helps people process emotions.
|
||||
```
|
||||
|
||||
::: tip
|
||||
Write your identity file in first person from the AI's perspective. This becomes the AI's self-concept on wake-up.
|
||||
:::
|
||||
|
||||
## Palace Path Override
|
||||
|
||||
All commands accept `--palace <path>` to override the default location:
|
||||
|
||||
```bash
|
||||
mempalace search "query" --palace /tmp/test-palace
|
||||
mempalace mine ~/data/ --palace /tmp/test-palace
|
||||
```
|
||||
|
||||
The MCP server also accepts `--palace`:
|
||||
|
||||
```bash
|
||||
python -m mempalace.mcp_server --palace /custom/palace
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `MEMPALACE_PALACE_PATH` | Override palace path (same as `--palace`) |
|
||||
| `MEMPAL_DIR` | Directory for auto-mining in hooks |
|
||||
@@ -0,0 +1,96 @@
|
||||
# Gemini CLI
|
||||
|
||||
MemPalace works natively with [Gemini CLI](https://github.com/google/gemini-cli), which handles the MCP server and save hooks automatically.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.9+
|
||||
- Gemini CLI installed and configured
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/milla-jovovich/mempalace.git
|
||||
cd mempalace
|
||||
|
||||
# Create a virtual environment
|
||||
python3 -m venv .venv
|
||||
|
||||
# Install dependencies
|
||||
.venv/bin/pip install -e .
|
||||
```
|
||||
|
||||
## Initialize the Palace
|
||||
|
||||
```bash
|
||||
.venv/bin/python3 -m mempalace init .
|
||||
```
|
||||
|
||||
### Identity and Project Configuration (Optional)
|
||||
|
||||
You can optionally create or edit:
|
||||
|
||||
- **`~/.mempalace/identity.txt`** — plain text describing your role and focus
|
||||
- **`./mempalace.yaml`** — per-project MemPalace configuration created by `mempalace init`
|
||||
- **`./entities.json`** — per-project entity mappings used by AAAK compression
|
||||
|
||||
## Connect to Gemini CLI
|
||||
|
||||
Register MemPalace as an MCP server:
|
||||
|
||||
```bash
|
||||
gemini mcp add mempalace /absolute/path/to/mempalace/.venv/bin/python3 \
|
||||
-m mempalace.mcp_server --scope user
|
||||
```
|
||||
|
||||
::: warning
|
||||
Use the **absolute path** to the Python binary to ensure it works from any directory.
|
||||
:::
|
||||
|
||||
## Enable Auto-Saving
|
||||
|
||||
Add a `PreCompress` hook to `~/.gemini/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompress": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/absolute/path/to/mempalace/hooks/mempal_precompact_hook.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Make sure the hook scripts are executable:
|
||||
```bash
|
||||
chmod +x hooks/*.sh
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once connected, Gemini CLI will automatically:
|
||||
- Start the MemPalace server on launch
|
||||
- Use `mempalace_search` to find relevant past discussions
|
||||
- Use the `PreCompress` hook to save memories before context compression
|
||||
|
||||
### Manual Mining
|
||||
|
||||
Mine existing code or docs:
|
||||
```bash
|
||||
.venv/bin/python3 -m mempalace mine /path/to/your/project
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
In a Gemini CLI session:
|
||||
- `/mcp list` — verify `mempalace` is `CONNECTED`
|
||||
- `/hooks panel` — verify the `PreCompress` hook is active
|
||||
@@ -0,0 +1,82 @@
|
||||
# Getting Started
|
||||
|
||||
## Installation
|
||||
|
||||
Install MemPalace from PyPI:
|
||||
|
||||
```bash
|
||||
pip install mempalace
|
||||
```
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.9+
|
||||
- `chromadb>=0.5.0` (installed automatically)
|
||||
- `pyyaml>=6.0` (installed automatically)
|
||||
|
||||
No API key required for the core local workflow. After installation, the main storage and retrieval path runs locally.
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/milla-jovovich/mempalace.git
|
||||
cd mempalace
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
Three steps: **init**, **mine**, **search**.
|
||||
|
||||
### 1. Initialize Your Palace
|
||||
|
||||
```bash
|
||||
mempalace init ~/projects/myapp
|
||||
```
|
||||
|
||||
This scans your project directory and:
|
||||
- Detects people and projects from file content
|
||||
- Creates rooms from your folder structure
|
||||
- Sets up `~/.mempalace/` config directory
|
||||
|
||||
### 2. Mine Your Data
|
||||
|
||||
```bash
|
||||
# Mine project files (code, docs, notes)
|
||||
mempalace mine ~/projects/myapp
|
||||
|
||||
# Mine conversation exports (Claude, ChatGPT, Slack)
|
||||
mempalace mine ~/chats/ --mode convos
|
||||
|
||||
# Mine with auto-classification into memory types
|
||||
mempalace mine ~/chats/ --mode convos --extract general
|
||||
```
|
||||
|
||||
Two mining modes plus one extraction strategy:
|
||||
- **projects** — code and docs, auto-detected rooms
|
||||
- **convos** — conversation exports, chunked by exchange pair
|
||||
- **general extraction** — an `--extract general` option for conversation mining that classifies content into decisions, preferences, milestones, problems, and emotional context
|
||||
|
||||
### 3. Search
|
||||
|
||||
```bash
|
||||
mempalace search "why did we switch to GraphQL"
|
||||
```
|
||||
|
||||
That gives you a working local memory index.
|
||||
|
||||
## What Happens Next
|
||||
|
||||
After the one-time setup, you don't run MemPalace commands manually. Your AI uses it for you through [MCP integration](/guide/mcp-integration) or a [Claude Code plugin](/guide/claude-code).
|
||||
|
||||
Ask your AI anything:
|
||||
|
||||
> *"What did we decide about auth last month?"*
|
||||
|
||||
It calls `mempalace_search` automatically, gets verbatim results, and answers you. You never type `mempalace search` again.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Mining Your Data](/guide/mining) — deep dive into mining modes
|
||||
- [MCP Integration](/guide/mcp-integration) — connect to Claude, ChatGPT, Cursor, Gemini
|
||||
- [The Palace](/concepts/the-palace) — understand wings, rooms, halls, and tunnels
|
||||
@@ -0,0 +1,116 @@
|
||||
# Auto-Save Hooks
|
||||
|
||||
Two hooks for Claude Code and Codex that automatically save memories during work. No manual "save" commands needed.
|
||||
|
||||
## What They Do
|
||||
|
||||
| Hook | When It Fires | What Happens |
|
||||
|------|--------------|-------------|
|
||||
| **Save Hook** | Every 15 human messages | Blocks the AI, tells it to save key topics/decisions/quotes to the palace |
|
||||
| **PreCompact Hook** | Right before context compaction | Emergency save — forces the AI to save everything before losing context |
|
||||
|
||||
The AI does the actual filing — it knows the conversation context, so it classifies memories into the right wings/halls/closets. The hooks just tell it **when** to save.
|
||||
|
||||
## Install — Claude Code
|
||||
|
||||
Add to `.claude/settings.local.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"Stop": [{
|
||||
"matcher": "*",
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "/absolute/path/to/hooks/mempal_save_hook.sh",
|
||||
"timeout": 30
|
||||
}]
|
||||
}],
|
||||
"PreCompact": [{
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "/absolute/path/to/hooks/mempal_precompact_hook.sh",
|
||||
"timeout": 30
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Make them executable:
|
||||
```bash
|
||||
chmod +x hooks/mempal_save_hook.sh hooks/mempal_precompact_hook.sh
|
||||
```
|
||||
|
||||
## Install — Codex CLI
|
||||
|
||||
Add to `.codex/hooks.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Stop": [{
|
||||
"type": "command",
|
||||
"command": "/absolute/path/to/hooks/mempal_save_hook.sh",
|
||||
"timeout": 30
|
||||
}],
|
||||
"PreCompact": [{
|
||||
"type": "command",
|
||||
"command": "/absolute/path/to/hooks/mempal_precompact_hook.sh",
|
||||
"timeout": 30
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Edit `mempal_save_hook.sh` to change:
|
||||
|
||||
- **`SAVE_INTERVAL=15`** — How many messages between saves. Lower = more frequent, higher = less interruption.
|
||||
- **`STATE_DIR`** — Where hook state is stored (defaults to `~/.mempalace/hook_state/`)
|
||||
- **`MEMPAL_DIR`** — Optional. Set to a conversations directory to auto-run `mempalace mine` on each save trigger.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Save Hook (Stop event)
|
||||
|
||||
```
|
||||
User sends message → AI responds → Stop hook fires
|
||||
↓
|
||||
Count human messages in transcript
|
||||
↓
|
||||
┌── < 15 since last save → let AI stop
|
||||
│
|
||||
└── ≥ 15 since last save → block + save
|
||||
↓
|
||||
AI saves to palace
|
||||
↓
|
||||
AI stops (flag set)
|
||||
```
|
||||
|
||||
The `stop_hook_active` flag prevents infinite loops.
|
||||
|
||||
### PreCompact Hook
|
||||
|
||||
```
|
||||
Context window full → PreCompact fires → ALWAYS blocks → AI saves → Compaction proceeds
|
||||
```
|
||||
|
||||
No counting needed — compaction always warrants a save.
|
||||
|
||||
## Debugging
|
||||
|
||||
```bash
|
||||
cat ~/.mempalace/hook_state/hook.log
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
[14:30:15] Session abc123: 12 exchanges, 12 since last save
|
||||
[14:35:22] Session abc123: 15 exchanges, 15 since last save
|
||||
[14:35:22] TRIGGERING SAVE at exchange 15
|
||||
[14:40:01] Session abc123: 18 exchanges, 3 since last save
|
||||
```
|
||||
|
||||
## Cost
|
||||
|
||||
**Zero extra tokens.** The hooks are bash scripts that run locally. They don't call any API. The only "cost" is a few seconds of the AI organizing memories at each checkpoint.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Local Models
|
||||
|
||||
MemPalace works with any local LLM — Llama, Mistral, or any offline model. Since local models generally don't speak MCP yet, there are two approaches.
|
||||
|
||||
## Wake-Up Command
|
||||
|
||||
Load your world into the model's context:
|
||||
|
||||
```bash
|
||||
mempalace wake-up > context.txt
|
||||
# Paste context.txt into your local model's system prompt
|
||||
```
|
||||
|
||||
This gives your local model a bounded wake-up context, typically around **~600-900 tokens** in the current implementation. It includes:
|
||||
- **Layer 0**: Your identity — who you are, what you work on
|
||||
- **Layer 1**: Top moments from the palace — key decisions, recent work
|
||||
|
||||
For project-specific context:
|
||||
```bash
|
||||
mempalace wake-up --wing driftwood > context.txt
|
||||
```
|
||||
|
||||
## CLI Search
|
||||
|
||||
Query on demand, feed results into your prompt:
|
||||
|
||||
```bash
|
||||
mempalace search "auth decisions" > results.txt
|
||||
# Include results.txt in your prompt
|
||||
```
|
||||
|
||||
## Python API
|
||||
|
||||
For programmatic integration with your local model pipeline:
|
||||
|
||||
```python
|
||||
from mempalace.searcher import search_memories
|
||||
|
||||
results = search_memories(
|
||||
"auth decisions",
|
||||
palace_path="~/.mempalace/palace",
|
||||
)
|
||||
|
||||
# Format results for your model's context
|
||||
context = "\n".join(
|
||||
f"[{r['wing']}/{r['room']}] {r['text']}"
|
||||
for r in results["results"]
|
||||
)
|
||||
|
||||
# Inject into your local model's prompt
|
||||
prompt = f"Context from memory:\n{context}\n\nUser: What did we decide about auth?"
|
||||
```
|
||||
|
||||
## AAAK for Compression
|
||||
|
||||
Use [AAAK dialect](/concepts/aaak-dialect) to compress wake-up context further:
|
||||
|
||||
```bash
|
||||
mempalace compress --wing myapp --dry-run
|
||||
```
|
||||
|
||||
AAAK is readable by any LLM that reads text — Claude, GPT, Gemini, Llama, Mistral — without a decoder.
|
||||
|
||||
## Full Offline Stack
|
||||
|
||||
The core memory stack can run offline:
|
||||
- **ChromaDB** on your machine — vector storage and search
|
||||
- **Local model** on your machine — reasoning and responses
|
||||
- **AAAK** for compression — optional, no cloud dependency
|
||||
- **Optional reranking or external model integrations** may introduce cloud calls, depending on how you configure the system
|
||||
@@ -0,0 +1,92 @@
|
||||
# MCP Integration
|
||||
|
||||
MemPalace provides 19 tools through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), giving any MCP-compatible AI full read/write access to your palace.
|
||||
|
||||
## Setup
|
||||
|
||||
### Manual Connection
|
||||
|
||||
```bash
|
||||
claude mcp add mempalace -- python -m mempalace.mcp_server
|
||||
```
|
||||
|
||||
### With Custom Palace Path
|
||||
|
||||
```bash
|
||||
claude mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace
|
||||
```
|
||||
|
||||
Now your AI has all 19 tools available. Ask it anything:
|
||||
|
||||
> *"What did we decide about auth last month?"*
|
||||
|
||||
Claude calls `mempalace_search` automatically, gets verbatim results, and answers you.
|
||||
|
||||
## Compatible Tools
|
||||
|
||||
MemPalace works with any tool that supports MCP:
|
||||
|
||||
- **Claude Code** — native via plugin or manual MCP
|
||||
- **ChatGPT** — via MCP bridge
|
||||
- **Cursor** — native MCP support
|
||||
- **Gemini CLI** — see [Gemini CLI guide](/guide/gemini-cli)
|
||||
|
||||
## Memory Protocol
|
||||
|
||||
When the AI first calls `mempalace_status`, it receives the **Memory Protocol** — a behavior guide that teaches it to:
|
||||
|
||||
1. **On wake-up**: Call `mempalace_status` to load the palace overview
|
||||
2. **Before responding** about any person, project, or past event: search first, never guess
|
||||
3. **If unsure**: Say "let me check" and query the palace
|
||||
4. **After each session**: Write diary entries to record what happened
|
||||
5. **When facts change**: Invalidate old facts, add new ones
|
||||
|
||||
This protocol is what turns storage into memory — the AI knows to verify before speaking.
|
||||
|
||||
## Tool Overview
|
||||
|
||||
### Palace (read)
|
||||
|
||||
| Tool | What |
|
||||
|------|------|
|
||||
| `mempalace_status` | Palace overview + AAAK spec + memory protocol |
|
||||
| `mempalace_list_wings` | Wings with counts |
|
||||
| `mempalace_list_rooms` | Rooms within a wing |
|
||||
| `mempalace_get_taxonomy` | Full wing → room → count tree |
|
||||
| `mempalace_search` | Semantic search with wing/room filters |
|
||||
| `mempalace_check_duplicate` | Check before filing |
|
||||
| `mempalace_get_aaak_spec` | AAAK dialect reference |
|
||||
|
||||
### Palace (write)
|
||||
|
||||
| Tool | What |
|
||||
|------|------|
|
||||
| `mempalace_add_drawer` | File verbatim content |
|
||||
| `mempalace_delete_drawer` | Remove by ID |
|
||||
|
||||
### Knowledge Graph
|
||||
|
||||
| Tool | What |
|
||||
|------|------|
|
||||
| `mempalace_kg_query` | Entity relationships with time filtering |
|
||||
| `mempalace_kg_add` | Add facts |
|
||||
| `mempalace_kg_invalidate` | Mark facts as ended |
|
||||
| `mempalace_kg_timeline` | Chronological entity story |
|
||||
| `mempalace_kg_stats` | Graph overview |
|
||||
|
||||
### Navigation
|
||||
|
||||
| Tool | What |
|
||||
|------|------|
|
||||
| `mempalace_traverse` | Walk the graph from a room across wings |
|
||||
| `mempalace_find_tunnels` | Find rooms bridging two wings |
|
||||
| `mempalace_graph_stats` | Graph connectivity overview |
|
||||
|
||||
### Agent Diary
|
||||
|
||||
| Tool | What |
|
||||
|------|------|
|
||||
| `mempalace_diary_write` | Write AAAK diary entry |
|
||||
| `mempalace_diary_read` | Read recent diary entries |
|
||||
|
||||
For detailed schemas and parameters, see [MCP Tools Reference](/reference/mcp-tools).
|
||||
@@ -0,0 +1,134 @@
|
||||
# Mining Your Data
|
||||
|
||||
MemPalace ingests your data by **mining** — scanning files and filing their content as verbatim drawers in the palace.
|
||||
|
||||
## Mining Modes
|
||||
|
||||
### Projects Mode (default)
|
||||
|
||||
Scans code, docs, and notes. Respects `.gitignore` by default.
|
||||
|
||||
```bash
|
||||
mempalace mine ~/projects/myapp
|
||||
```
|
||||
|
||||
Each file becomes a drawer, tagged with a wing (project name) and room (topic). Rooms are auto-detected from your folder structure during `mempalace init`.
|
||||
|
||||
Options:
|
||||
```bash
|
||||
# Override wing name
|
||||
mempalace mine ~/projects/myapp --wing myapp
|
||||
|
||||
# Ignore .gitignore rules
|
||||
mempalace mine ~/projects/myapp --no-gitignore
|
||||
|
||||
# Include specific ignored paths
|
||||
mempalace mine ~/projects/myapp --include-ignored dist,build
|
||||
|
||||
# Limit number of files
|
||||
mempalace mine ~/projects/myapp --limit 100
|
||||
|
||||
# Preview without filing
|
||||
mempalace mine ~/projects/myapp --dry-run
|
||||
```
|
||||
|
||||
### Conversations Mode
|
||||
|
||||
Indexes conversation exports from Claude, ChatGPT, Slack, and other tools. Chunks by exchange pair (human + assistant turns).
|
||||
|
||||
```bash
|
||||
mempalace mine ~/chats/ --mode convos
|
||||
```
|
||||
|
||||
Supports five chat formats automatically:
|
||||
- Claude JSON exports
|
||||
- ChatGPT exports
|
||||
- Slack exports
|
||||
- Markdown conversations
|
||||
- Plain text transcripts
|
||||
|
||||
### General Extraction
|
||||
|
||||
Auto-classifies conversation content into five memory types:
|
||||
|
||||
```bash
|
||||
mempalace mine ~/chats/ --mode convos --extract general
|
||||
```
|
||||
|
||||
Memory types:
|
||||
- **Decisions** — choices made, options rejected
|
||||
- **Preferences** — habits, likes, opinions
|
||||
- **Milestones** — sessions completed, goals reached
|
||||
- **Problems** — bugs, blockers, issues encountered
|
||||
- **Emotional context** — reactions, concerns, excitement
|
||||
|
||||
## Splitting Mega-Files
|
||||
|
||||
Some transcript exports concatenate multiple sessions into one huge file. Split them first:
|
||||
|
||||
```bash
|
||||
# Preview what would be split
|
||||
mempalace split ~/chats/ --dry-run
|
||||
|
||||
# Split files with 2+ sessions (default)
|
||||
mempalace split ~/chats/
|
||||
|
||||
# Only split files with 3+ sessions
|
||||
mempalace split ~/chats/ --min-sessions 3
|
||||
|
||||
# Output to a different directory
|
||||
mempalace split ~/chats/ --output-dir ~/chats-split/
|
||||
```
|
||||
|
||||
::: tip
|
||||
Always run `mempalace split` before mining conversation files. It's a no-op if files don't need splitting.
|
||||
:::
|
||||
|
||||
## Multi-Project Setup
|
||||
|
||||
Mine each project into its own wing:
|
||||
|
||||
```bash
|
||||
mempalace mine ~/chats/orion/ --mode convos --wing orion
|
||||
mempalace mine ~/chats/nova/ --mode convos --wing nova
|
||||
mempalace mine ~/chats/helios/ --mode convos --wing helios
|
||||
```
|
||||
|
||||
Six months later:
|
||||
```bash
|
||||
# Project-specific search
|
||||
mempalace search "database decision" --wing orion
|
||||
|
||||
# Cross-project search
|
||||
mempalace search "rate limiting approach"
|
||||
# → finds your approach in Orion AND Nova, shows the differences
|
||||
```
|
||||
|
||||
## Team Usage
|
||||
|
||||
Mine Slack exports and AI conversations for team history:
|
||||
|
||||
```bash
|
||||
mempalace mine ~/exports/slack/ --mode convos --wing driftwood
|
||||
mempalace mine ~/.claude/projects/ --mode convos
|
||||
```
|
||||
|
||||
Then search across people and projects:
|
||||
```bash
|
||||
mempalace search "Soren sprint" --wing driftwood
|
||||
# → 14 closets: OAuth refactor, dark mode, component library migration
|
||||
```
|
||||
|
||||
## Agent Tag
|
||||
|
||||
Every drawer is tagged with the agent that filed it:
|
||||
|
||||
```bash
|
||||
# Default agent name
|
||||
mempalace mine ~/data/ --agent mempalace
|
||||
|
||||
# Custom agent name
|
||||
mempalace mine ~/data/ --agent reviewer
|
||||
```
|
||||
|
||||
This is used by [Specialist Agents](/concepts/agents) to partition memories.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user