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