@byte5ai/palaia 2.1.0 → 2.2.0

package/skill/SKILL.md

@@ -1,873 +1,451 @@
 ---
 name: palaia
+version: "2.2.0"
 description: >
   Local, crash-safe persistent memory for OpenClaw agents.
-  Semantic search, projects, auto-capture, auto-recall.
-  This SKILL.md is bundled with the npm plugin — no ClawHub needed.
+  SQLite-backed by default. Semantic search, projects, scopes, auto-capture.
 ---
 
-> **Note:** This SKILL.md is bundled with the `@byte5ai/palaia` npm plugin.
-> For the full documentation including installation instructions, see: https://github.com/iret77/palaia
+# Palaia v2.2 — Agent Memory (Plugin)
 
-# Palaia — Agent Memory Skill
+Palaia is your memory system. It gives you persistent, searchable, crash-safe memory across sessions. Palaia is already installed and configured via the OpenClaw plugin — just use the commands below.
 
 ## Auto-Check (run every time this skill is loaded)
 
-**[INSTRUCTION for LLM]:** Before doing anything else with Palaia, run `palaia doctor` silently. If it reports ANY warnings (version mismatch, missing providers, legacy patterns, incomplete setup), address them immediately by following `palaia doctor --fix` recommendations. Do not proceed with other Palaia tasks until doctor reports no issues. This ensures the memory system is always up-to-date and correctly configured.
+Before doing anything else with Palaia, run `palaia doctor` silently. If it reports ANY warnings, address them immediately by following `palaia doctor --fix` recommendations. Do not proceed with other Palaia tasks until doctor reports no issues.
 
-## Zero-Config: It Just Works
-
-**Palaia works out of the box after installation. No config edits needed.**
-
-After installing the plugin, Palaia immediately:
-- **Injects relevant memories** into every agent prompt (`memoryInject: true`)
-- **Auto-captures significant exchanges** as searchable memories (`autoCapture: true`)
-- **Uses semantic recall** to find context-relevant memories (`recallMode: query`)
-
-No settings to tweak. No README to study. Install it and it works.
-
-**For power users:** All defaults can be customized via `openclaw.json` plugin config or `palaia init --capture-level`. See the Configuration section below.
-
-**Upgrading from v1.x?** Run `palaia doctor --fix` — it detects old defaults and upgrades them. Custom values you've set are preserved.
-
-## Setup Flow (follow this exactly)
-
-### Step 3: Check for existing memory systems (REQUIRED — do not skip)
-```bash
-palaia doctor
-```
-
-Review **every** warning before continuing. For each warning found by `palaia doctor`, immediately offer to fix it — do not wait for the user to ask:
-
-**HEARTBEAT.md legacy patterns:**
-→ Tell the user: "Your heartbeat still uses old memory patterns. Should I update it to use Palaia? (Takes a moment, no data loss)"
-- If yes: update HEARTBEAT.md, replace `memory_search`/`memory_get`/direct file reads with `palaia query`/`palaia write` equivalents
-- If no: skip, move to next warning
-
-**Smart-Memory skill detected:**
-→ Tell the user: "The old smart-memory skill is still installed. Should I remove it? (Only after confirming Palaia has your memories)"
-- If yes: run `palaia migrate <workspace-path>`, then remove the smart-memory skill folder
-- If no: continue, but both systems will run in parallel (not recommended)
-
-**OpenClaw plugin still memory-core:**
-→ Tell the user: "Palaia isn't connected to OpenClaw's memory system yet. Should I switch it? (Requires a quick OpenClaw restart)"
-- If yes: update OpenClaw config (`plugins.slots.memory = "palaia"`), restart OpenClaw
-- If no: Palaia runs standalone (no `memory_search`/`memory_get` tool integration)
-
-**openai-only chain (no local fallback):**
-→ Tell the user: "Your search has no local backup. Should I install fastembed as a fallback? (Small download, no GPU needed)"
-- If yes: `pip install fastembed`, then `palaia warmup`, update chain to include fastembed before bm25
-- If no: skip (warn: "Search may degrade when OpenAI is unavailable")
-
-Rules:
-- For each warning: ask immediately, one question at a time
-- Do not batch all questions — address them in order
-- Do not wait for the user to notice and ask
-- After user answers yes/no, move to next warning
-- Report when all warnings are resolved
-
-**Do not proceed until all warnings are addressed or explicitly dismissed by the user.**
-
-### Onboarding Conversation
-
-After running `palaia doctor` and reviewing warnings, have a brief conversation with your user.
-Keep it short — 3 questions max. No technical details unless the user asks.
-
-**Script:**
-
-Tell the user:
-"I've set up Palaia for you — your memory is now crash-safe and searchable.
-Quick setup: 3 short questions."
-
-**Question 1 — Search quality:**
-
-If an OpenAI API key is present AND a local model (sentence-transformers/fastembed/ollama) is also detected:
-  → Just confirm: "I'll use your OpenAI key with a local backup model. Good setup."
-  → No question needed.
-
-If an OpenAI API key is present BUT no local model is installed:
-  → Tell the user: "You have an OpenAI API key — great for search quality. But without a local backup, search quality drops significantly when OpenAI is unavailable. I recommend installing a small local model (300MB, free, runs offline). Should I do that?"
-  → yes: pip install sentence-transformers (if CUDA issues: pip install fastembed instead — lighter, no GPU needed), then palaia warmup, chain = openai → sentence-transformers → bm25
-  → no: chain = openai → bm25 (warn: "Note: search may fail or degrade without a local fallback.")
+---
 
-If no OpenAI key AND no local model:
-  → Tell the user: "No search provider found yet. I recommend installing a free local model (300MB). Should I do that?"
-  → yes: pip install sentence-transformers (if CUDA issues: pip install fastembed instead — lighter, no GPU needed), then palaia warmup, chain = sentence-transformers → bm25
-  → no: BM25 only (warn: "Search will be keyword-based — you can improve this later with palaia detect.")
+## Core Concepts
 
-If no OpenAI key BUT local model detected:
-  → Just confirm: "Using local search model — works offline, no API costs."
-  → No question needed.
+### Auto-Capture
+Conversations are automatically captured when the OpenClaw plugin is active. You do NOT need to manually write things from conversations — Palaia handles it. Manual `palaia write` is only for structured knowledge: processes, tasks, and knowledge from external sources.
 
-**Question 2 — Existing memory (only ask if legacy memory files exist OR smart-memory detected):**
-  Ask: "You have existing memory. Should I bring it into Palaia?"
-  → yes: run palaia migrate <workspace-path>
-  → no: start fresh (existing files stay untouched)
+### Three Tiers
+- **HOT** — Active memories (< 7 days or frequently accessed). Always searched.
+- **WARM** — Aging memories (7-30 days). Searched by default.
+- **COLD** — Archived memories (> 30 days). Only searched with `--all`.
 
-**Question 3 — Projects (only ask if multiple project folders detected OR more than 1 agent present):**
-  Ask: "Do you work on multiple projects? I can keep their memories separate."
-  → yes: briefly explain: "Use 'palaia project create <name>' for each project. I'll remember which memories belong where."
-  → no: skip
+### Scopes
+- **private** — Only the writing agent can read it
+- **team** — All agents in the workspace can read it (default)
+- **public** — Exportable and shareable across workspaces
 
-**Question 4 — Capture Model (only ask if autoCapture is enabled, which is the default):**
-  Ask: "Auto-Capture saves significant conversations automatically. Which model should it use for extraction? A cheap/fast model is best (e.g. claude-haiku-4-5, gpt-4.1-mini, gemini-2.0-flash)."
-  → User names a model: set `captureModel` in openclaw.json plugin config
-  → User says "use default" or skips: leave unset (primary model will be used, doctor will nudge)
+### Entry Types
+- **memory** — Facts, decisions, learnings (default)
+- **process** — Workflows, checklists, SOPs
+- **task** — Action items with status, priority, assignee, due date
 
-**Wrap up:**
-Tell the user what was configured — one sentence:
-"Done. [Search quality: OpenAI / local model / keyword-only]. [Migration: X entries imported / fresh start]. [Projects: configured / not used]."
+---
 
-Do not explain commands, WAL, BM25, embedding models, or any technical details unless the user explicitly asks.
+## Commands Reference
 
-### Step 4: Migrate existing entries (best practice — do this now)
-If there are existing entries from an earlier Palaia version (or from initial setup), run:
-```bash
-palaia migrate --suggest
-```
-This checks for entries without type classification and suggests improvements. Better to do this early while the store is small — it gets harder as the store grows. Apply the suggestions that make sense.
+### `palaia write` — Save structured knowledge
 
-### Step 5a: Check embedding setup (auto-configured by init)
-```bash
-palaia detect
-```
-Review the detected providers and configured chain. `palaia init` automatically detects available providers
-and configures the best embedding chain — you usually don't need to change anything.
+Only use for explicit process/task entries, or knowledge from external sources. Conversation knowledge is auto-captured.
 
-If the chain looks wrong or you want to change it:
 ```bash
-palaia config set-chain <provider1> [provider2] bm25
-```
+# Save a fact from outside the conversation
+palaia write "API rate limit is 100 req/min" --type memory --tags api,limits
 
-If only BM25 is shown and you want semantic search:
-```bash
-# fastembed — lightweight, no GPU needed, recommended for most systems
-python3 -m pip install fastembed    # or: uv pip install fastembed
-palaia warmup                       # pre-load model + build index
-```
-If fastembed is unavailable, sentence-transformers works too (`python3 -m pip install sentence-transformers`) but is heavier and slower on CPU-only systems.
+# Record a step-by-step process
+palaia write "1. Build 2. Test 3. Deploy" --type process --project myapp
 
-### Step 5b: Warm up models
-```bash
-palaia warmup
-```
-This pre-downloads embedding models so the first search is instant. Always run after chain setup.
+# Create a task with structured fields
+palaia write "fix login bug" --type task --priority high --assignee Elliot --due-date 2026-04-01
 
-### Step 6: Verify setup (mandatory — do not skip)
-Run a test query to verify semantic search works end-to-end:
-```bash
-palaia query "important context and decisions"
+# Save to a specific project with scope
+palaia write "Use JWT for auth" --project backend --scope team --tags decision
 ```
-**Check:**
-- Results must appear (not empty)
-- Response time should be under 5 seconds
-- If it times out or returns no results: check `palaia status` and `palaia detect`, fix any issues before proceeding
 
-Then verify `palaia status` shows indexed entries (Index: N/N, not 0/N).
-If index is 0/N after warmup, run a few queries — indexing happens lazily on first query.
+### `palaia query` — Semantic search
 
-**Do not tell the user "setup complete" until this verification passes.** Assumption is not verification.
+Find memories by meaning, not just keywords.
 
-### Step 7: Optional — migrate additional memory files (skip if done in Step 4)
 ```bash
-palaia migrate <path> --dry-run   # Preview first
-palaia migrate <path>             # Then import
-```
-Note: If smart-memory migration was already handled in Step 3, skip this unless there are other sources to import.
-
-### Step 8: Add Palaia maintenance to your heartbeat (mandatory)
-
-This is required. Palaia's tiering (HOT → WARM → COLD) only runs when triggered.
-Without periodic maintenance, all entries stay HOT forever and search quality degrades over time.
-
-Check if `HEARTBEAT.md` exists in the workspace (`~/.openclaw/workspace/HEARTBEAT.md`).
-
-**If it exists:** Append the following block at the end (before any final comments):
-
-```
-# TASK: Palaia Maintenance (daily + weekly)
-# [INSTRUCTION for LLM]:
-# Daily: run `palaia gc` — moves entries between HOT/WARM/COLD based on age and access.
-# Weekly (Sunday): run `palaia gc --aggressive` — also clears COLD tier.
-# Fast operation, never blocks user queries. Only run if palaia is installed (check: which palaia).
-```
-
-**If it does not exist:** Create `HEARTBEAT.md` with the block above as its first task.
-
-Tell the user: "I've added a Palaia maintenance task to your heartbeat schedule. This keeps your memory organized automatically — nothing you need to do."
-
-## Auto-Capture and Capture Hints
-
-### How Auto-Capture Works
-
-Auto-capture runs automatically after every agent turn (when `autoCapture: true`, which is the default). It:
-
-1. Collects all messages from the completed exchange
-2. Filters out trivial exchanges (short, system content, acknowledgments)
-3. Uses LLM-based extraction to identify significant knowledge: decisions, lessons, processes, commitments, preferences
-4. Writes extracted items to Palaia with appropriate type, tags, scope, and project attribution
-5. Falls back to rule-based extraction if LLM is unavailable
-
-**Agent attribution:** If `PALAIA_AGENT` is set in the environment, all auto-captured entries are attributed to that agent via `--agent`. Otherwise, the CLI uses the configured default.
-
-**Project detection:** Auto-capture passes the list of known projects to the LLM, which assigns entries to the most relevant project (or none if unclear).
-
-**Scope detection:** The LLM also determines scope per item: `private` (personal preference), `team` (shared knowledge), or `public` (documentation).
-
-### When to Use Manual Write vs Auto-Capture
-
-**Auto-Capture** handles conversation knowledge automatically: decisions mentioned in chat, facts discussed, lessons learned during work. You don't need to save these — Palaia does it for you.
+# Basic search
+palaia query "what's the rate limit"
 
-**Manual `palaia write` is for structured knowledge that Auto-Capture cannot create:**
+# Filter by type and status
+palaia query "tasks" --type task --status open
 
-| Use Case | Command | Why Manual? |
-|----------|---------|-------------|
-| Step-by-step procedure | `palaia write "1. Build 2. Test 3. Deploy" --type process` | Structure matters |
-| Task with owner/deadline | `palaia write "fix auth" --type task --priority high --assignee Elliot` | Structured fields |
-| Project setup | `palaia project create myproject` | Explicit organization |
-| Knowledge from external source | `palaia write "API limit: 100/min" --type memory --project api` | Not from conversation |
+# Search within a project
+palaia query "deploy steps" --project myapp
 
-**Do NOT manually write:**
-- Facts, decisions, or preferences that came up in the current conversation (auto-captured)
-- "We decided to use X" after discussing X (auto-captured)
-- Status updates or progress notes (auto-captured if significant)
+# Include archived (COLD) entries
+palaia query "old decisions" --all
 
-**Rule of thumb:** If it just happened in conversation → trust Auto-Capture. If it needs structure (steps, fields, project assignment) → write manually.
-
-### Capture Hints
+# Search across all projects
+palaia query "authentication" --cross-project
 
-When you want to guide auto-capture without writing manually, use `<palaia-hint />` tags in your message:
+# Time-filtered search
+palaia query "deploy" --after 2026-03-01 --before 2026-03-15
 
-```
-<palaia-hint project="myapp" scope="private" />
+# RAG-formatted output for LLM injection
+palaia query "how does auth work" --project api --rag
 ```
 
-Hints are parsed from all messages in the exchange and used as overrides:
-- **Priority:** Hint > LLM detection > Config override > Default
-- **Attributes:** `project`, `scope`, `type`, `tags` (comma-separated)
-- **Stripping:** Hints are automatically removed from outgoing messages — the user never sees them
+### `palaia get` — Read a specific entry
 
-Multiple hints are supported (e.g., for different projects in the same turn):
-```
-<palaia-hint project="frontend" scope="team" tags="decision" />
-<palaia-hint project="backend" type="process" />
+```bash
+palaia get <entry-id>
+palaia get <entry-id> --from 5 --lines 20   # Read a portion
 ```
 
-### Static Config Overrides
-
-For setups where every entry should go to the same project/scope, set in plugin config:
-- `captureScope`: Static scope override (e.g., `"team"`)
-- `captureProject`: Static project override (e.g., `"myapp"`)
-
-These override LLM detection but are overridden by capture hints.
-
-## Knowledge Packages
+Use when you have an entry ID from a query result or nudge message.
 
-Export and import project knowledge as portable package files.
+### `palaia list` — Browse entries
 
 ```bash
-# Export all entries from a project
-palaia package export <project> [--output file.palaia-pkg.json] [--types memory,process]
+# List active entries
+palaia list
 
-# Import a knowledge package
-palaia package import <file> [--project target] [--merge skip|overwrite|append] [--agent name]
+# Filter by tier, type, status
+palaia list --tier warm --type task --status open --priority high
 
-# View package metadata without importing
-palaia package info <file>
+# Filter by project or assignee
+palaia list --project myapp --assignee Elliot
 ```
 
-The `--agent` flag on import attributes all imported entries to a specific agent name.
-
-## Process Runner
-
-Run stored process entries as interactive checklists:
+### `palaia status` — System health check
 
 ```bash
-# List all stored processes
-palaia process list [--project NAME]
-
-# Run a process interactively
-palaia process run <id>
+palaia status
 ```
 
-## Temporal Queries
+Shows: entry counts per tier, entry class breakdown (memory/process/task), active providers, index health, version info. Run this when something seems off or to verify setup.
 
-Filter entries by time with `--before` and `--after`:
+### `palaia project` — Project context management
 
 ```bash
-palaia query "deploy" --after 2026-03-01 --before 2026-03-15
-palaia list --after 2026-03-01
+palaia project create myapp --description "Main application" --default-scope team
+palaia project list
+palaia project show myapp
+palaia project query myapp "deploy steps"
+palaia project write myapp "New convention: use snake_case" --tags convention
+palaia project set-scope myapp private
+palaia project delete myapp   # Entries preserved, just untagged
 ```
 
-Dates are in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS).
-
-## Cross-Project Search
-
-Search across all projects at once:
+### `palaia memo` — Inter-agent messaging
 
 ```bash
-palaia query "authentication" --cross-project
+palaia memo send AgentName "Important update about project X"
+palaia memo broadcast "New process available"
+palaia memo inbox              # Check for messages
+palaia memo ack <memo-id>      # Mark as read
 ```
 
-Without `--cross-project`, queries only search entries in the active project context.
+### `palaia priorities` — Injection priority management
 
-## Bounded Memory and Garbage Collection
-
-Palaia supports budgeted garbage collection to keep the store lean:
+Control which memories are injected into each agent's context.
 
 ```bash
-# Preview what would be collected
-palaia gc --dry-run
-
-# Collect with a target budget (max entries to keep)
-palaia gc --budget 200
-
-# Aggressive collection — also clears COLD tier
-palaia gc --aggressive
-```
-
-GC rotates entries through tiers: HOT (active, <7 days) -> WARM (recent, <30 days) -> COLD (archived).
-
-## Significance Tagging
-
-Auto-capture automatically detects and tags entries with significance markers:
+# Show what would be injected (with score breakdown)
+palaia priorities
 
-| Tag | Meaning | Example |
-|-----|---------|---------|
-| `decision` | A choice was made | "We decided to use PostgreSQL" |
-| `lesson` | Something was learned | "I learned that caching needs invalidation on deploy" |
-| `surprise` | Unexpected discovery | "The API returns 200 even on errors" |
-| `commitment` | Promise or action item | "I will refactor auth by Friday" |
-| `correction` | Error was corrected | "Actually, the limit is 100, not 50" |
-| `preference` | User/agent preference | "I prefer tabs over spaces" |
-| `fact` | Important factual information | "The prod DB is on port 5433" |
+# Block an entry from injection for a specific agent
+palaia priorities block <entry-id> --agent orchestrator
 
-These tags enable targeted queries: `palaia query "decisions" --tags decision`
-
-## Adaptive Nudging
-
-Palaia includes a graduation system that adapts to agent behavior:
-
-**What it does:** When the agent writes an entry that relates to an existing process, Palaia nudges: "Related process found: [title]. Consider following it."
-
-**How it learns:** The nudging system tracks whether agents follow stored processes. Over time:
-- Agents that consistently follow processes see fewer nudges (graduated)
-- Agents that frequently skip processes continue to receive nudges
-- New processes always trigger nudges until a pattern is established
-
-**Important:** SKILL.md documentation is the primary source for agent behavior. Nudging is the safety net for when agents don't read the docs — not a replacement for good documentation.
-
-## Transparency Features
-
-Palaia makes its memory operations visible to the user by default. Both features are enabled out of the box and can be toggled independently.
-
-### Memory Source Footnotes
-
-When Palaia injects memories into the agent context and the agent uses them in a response, a footnote is appended:
+# Set per-agent injection thresholds
+palaia priorities set recallMinScore 0.8 --agent orchestrator
 
+# Adjust type weights per agent
+palaia priorities set typeWeight.process 0.5 --agent orchestrator
 ```
-Palaia: "PostgreSQL migration plan" (Mar 16), "Deploy process" (Mar 10)
-```
-
-This shows the user which memories influenced the response. Max 3 sources are shown, selected by keyword relevance between the memory title and the response text.
 
-**Disable:** `palaia config set showMemorySources false`
-**Re-enable:** `palaia config set showMemorySources true`
+Config stored in `.palaia/priorities.json` with layered overrides: global -> per-agent -> per-project.
 
-### Capture Confirmations
+### `palaia curate analyze/apply` — Knowledge curation
 
-When Palaia auto-captures a significant exchange, a confirmation is shown:
-
-```
-Saved: "Team decided to use PostgreSQL for the project due to JSON support"
-```
-
-This confirms that knowledge was stored and gives the user a preview of what was captured.
-
-**Disable:** `palaia config set showCaptureConfirm false`
-**Re-enable:** `palaia config set showCaptureConfirm true`
-
-### Satisfaction and Preference Nudges
-
-After sustained usage, Palaia nudges agents to check in with the user:
-
-1. **Satisfaction check** (after ~10 successful recalls): Ask the user if the memory system is working well. Suggest `palaia doctor` if there are issues.
-2. **Transparency preference** (after ~50 recalls or ~7 days): Ask the user whether they want to keep seeing footnotes and capture confirmations, or hide them. Both are one-shot nudges that won't repeat.
-
-## Commands Reference
-
-### Basic Memory
+For migrating knowledge to a new instance, cleaning up old entries, or reviewing accumulated knowledge.
 
 ```bash
-# Write a memory entry (default type: memory)
-palaia write "text" [--scope private|team|public] [--project NAME] [--tags a,b] [--title "Title"] [--type memory|process|task] [--instance NAME]
-
-# Write a task with structured fields
-palaia write "fix login bug" --type task --status open --priority high --assignee Elliot --due-date 2026-04-01
-
-# Edit an existing entry (content, metadata, task fields)
-palaia edit <id> ["new content"] [--status done] [--priority high] [--tags new,tags] [--title "New Title"] [--type task]
-
-# Search memories (semantic + keyword) with structured filters
-palaia query "search term" [--project NAME] [--limit N] [--all] [--type task] [--status open] [--priority high] [--assignee NAME] [--instance NAME]
-
-# Read a specific entry by ID
-palaia get <id> [--from LINE] [--lines N]
-
-# List entries in a tier with filters
-palaia list [--tier hot|warm|cold] [--project NAME] [--type task] [--status open] [--priority high] [--assignee NAME] [--instance NAME]
+# Analyze: clusters entries, detects duplicates, recommends KEEP/MERGE/DROP
+palaia curate analyze --project myapp
 
-# System health, active providers, and entry class breakdown
-palaia status
-
-# Suggest type assignments for untyped entries
-palaia migrate --suggest
+# Apply: parses the user-edited report, produces clean export package
+palaia curate apply report.md
 ```
 
-### Projects
-
-Projects group related entries. They're optional — everything works without them.
-
-```bash
-# Create a project
-palaia project create <name> [--description "..."] [--default-scope team]
-
-# List all projects
-palaia project list
-
-# Show project details + entries
-palaia project show <name>
-
-# Write an entry directly to a project
-palaia project write <name> "text" [--scope X] [--tags a,b] [--title "Title"]
+Requires optional dependency: `pip install palaia[curate]` (adds scikit-learn).
 
-# Search within a project only
-palaia project query <name> "search term" [--limit N]
+Tell your user: "I can analyze your memory for cleanup. Want me to run a curation report?"
 
-# Change the project's default scope
-palaia project set-scope <name> <scope>
-
-# Delete a project (entries are preserved, just untagged)
-palaia project delete <name>
-```
-
-### Agent Alias System
-
-Aliases let multiple agent names resolve to the same identity. Scope checks and queries will match both the alias and the canonical name.
+### `palaia sync export/import` — Git-based knowledge exchange
 
 ```bash
-# Set alias: "default" is treated as "HAL"
-palaia alias set default HAL
+# Export entries for sharing
+palaia sync export --project myapp --output ./export/
 
-# List all aliases
-palaia alias list
+# Export to a git remote
+palaia sync export --project myapp --remote git@github.com:team/knowledge.git
 
-# Remove an alias
-palaia alias remove default
+# Import entries
+palaia sync import ./export/ --dry-run   # Preview first
+palaia sync import ./export/
 ```
 
-Use aliases when the same agent runs under different names (e.g., "default" during init, "HAL" during operation). Entries written by either name are accessible to both.
-
-### Project Locking
-
-Advisory locks coordinate multi-agent work on projects. Locks auto-expire after TTL (default: 30 min).
+### `palaia package export/import` — Portable knowledge packages
 
 ```bash
-# Lock a project for exclusive work
-palaia project lock <name> --agent <agent> [--reason "..."] [--ttl 3600]
-
-# Check if a project is locked
-palaia project lock-status <name>
+# Export project knowledge as a portable file
+palaia package export myapp --output myapp.palaia-pkg.json
 
-# Release a lock
-palaia project unlock <name>
-
-# Force-break a stuck lock (use with caution)
-palaia project break-lock <name>
+# Import a knowledge package
+palaia package import myapp.palaia-pkg.json --project target --merge skip
 
-# List all active locks
-palaia project locks
+# View package metadata
+palaia package info myapp.palaia-pkg.json
 ```
 
-Always check lock status before starting work on a shared project. The lock is advisory — it doesn't prevent writes, but agents should respect it.
-
-### Configuration
+### `palaia doctor` — Diagnostics and auto-fix
 
 ```bash
-# Show all settings
-palaia config list
-
-# Get/set a single value
-palaia config set <key> <value>
-
-# Set the embedding fallback chain (ordered by priority)
-palaia config set-chain <provider1> [provider2] [...] bm25
-
-# Detect available embedding providers on this system
-palaia detect
-
-# Pre-download embedding models
-palaia warmup
+palaia doctor              # Check health
+palaia doctor --fix        # Auto-fix issues
+palaia doctor --json       # Machine-readable output
 ```
 
-### Diagnostics
+Run this first whenever something is wrong. It checks versions, repairs chains, rebuilds indexes, detects legacy systems, and handles migration.
 
-```bash
-# Check Palaia health and detect legacy systems
-palaia doctor
-
-# Show guided fix instructions for each warning
-palaia doctor --fix
-
-# Machine-readable output
-palaia doctor --json
-```
-
-### Maintenance
+### `palaia gc` — Garbage collection
 
 ```bash
-# Tier rotation — moves old entries from HOT → WARM → COLD
-palaia gc [--aggressive]
-
-# Replay any interrupted writes from the write-ahead log
-palaia recover
+palaia gc                  # Tier rotation (HOT -> WARM -> COLD)
+palaia gc --dry-run         # Preview what would change
+palaia gc --aggressive      # Also clears COLD tier
+palaia gc --budget 200      # Keep max N entries
 ```
 
-### Document Ingestion (RAG)
+### `palaia config` — Configuration
 
 ```bash
-# Index a file, URL, or directory into the knowledge base
-palaia ingest <file-or-url> [--project X] [--scope X] [--tags a,b] [--chunk-size N] [--dry-run]
-
-# Query with RAG-formatted context (ready for LLM injection)
-palaia query "question" --project X --rag
+palaia config list                        # Show all settings
+palaia config set <key> <value>           # Set a value
+palaia config set-chain fastembed bm25    # Set embedding chain
+palaia config set-alias default HAL       # Agent alias
 ```
 
-### Sync
+### `palaia process` — Multi-step process tracking
 
 ```bash
-# Export entries for sharing
-palaia export [--project NAME] [--output DIR] [--remote GIT_URL]
-
-# Import entries from an export
-palaia import <path> [--dry-run]
-
-# Import from other memory formats (smart-memory, flat-file, json-memory, generic-md)
-palaia migrate <path> [--dry-run] [--format FORMAT] [--scope SCOPE]
+palaia process list --project myapp       # List stored processes
+palaia process run <id>                   # Run interactively
 ```
 
-### JSON Output
+### `palaia lock/unlock` — Entry and project locking
 
-All commands support `--json` for machine-readable output:
 ```bash
-palaia status --json
-palaia query "search" --json
-palaia project list --json
+palaia project lock myapp --agent HAL --reason "refactoring"
+palaia project lock-status myapp
+palaia project unlock myapp
+palaia project break-lock myapp           # Force-break stuck lock
+palaia project locks                      # List all active locks
 ```
 
-## Scope System
+### `palaia edit` — Modify existing entries
 
-Every entry has a visibility scope:
-
-- **`private`** — Only the agent that wrote it can read it
-- **`team`** — All agents in the same workspace can read it (default)
-- **`public`** — Can be exported and shared across workspaces
-
-**Setting defaults:**
 ```bash
-# Global default
-palaia config set default_scope <scope>
-
-# Per-project default
-palaia project set-scope <name> <scope>
+palaia edit <id> --status done
+palaia edit <id> "updated content" --tags new,tags --priority high
 ```
 
-**Scope cascade** (how Palaia decides the scope for a new entry):
-1. Explicit `--scope` flag → always wins
-2. Project default scope → if entry belongs to a project
-3. Global `default_scope` from config
-4. Falls back to `team`
-
-## Projects
-
-- Projects are optional and purely additive — Palaia works fine without them
-- Each project has its own default scope
-- Writing with `--project NAME` or `palaia project write NAME` both assign to a project
-- Deleting a project preserves its entries (they just lose the project tag)
-- `palaia project show NAME` lists all entries with their tier and scope
-
-## When to Use What
+### Other commands
 
-| Situation | Command |
-|-----------|---------|
-| Remember a simple fact | `palaia write "..."` |
-| Remember something for a specific project | `palaia project write <name> "..."` |
-| Create a task/todo | `palaia write "fix bug" --type task --priority high` |
-| Record a process/SOP | `palaia write "deploy steps" --type process` |
-| Mark task as done | `palaia edit <id> --status done` |
-| Find something you stored | `palaia query "..."` |
-| Find open tasks | `palaia query "tasks" --type task --status open` |
-| List high-priority tasks | `palaia list --type task --priority high` |
-| Find something within a project | `palaia project query <name> "..."` |
-| Check what's in active memory | `palaia list` |
-| Check what's in archived memory | `palaia list --tier cold` |
-| See system health + class breakdown | `palaia status` |
-| Clean up old entries | `palaia gc` |
-| Index a document or website | `palaia ingest <file/url> --project <name>` |
-| Get type suggestions for old entries | `palaia migrate --suggest` |
-| Search indexed documents for LLM context | `palaia query "..." --project <name> --rag` |
-
-## Document Knowledge Base
-
-Use `palaia ingest` to index external documents — PDFs, websites, text files, directories.
-Indexed content is chunked, embedded, and stored as regular entries (searchable like memory).
-
-**When to use:**
-- User asks you to "remember" a document, manual, or website
-- You need to search through a large document
-- Building a project-specific knowledge base
-
-**How to use:**
 ```bash
-palaia ingest document.pdf --project my-project
-palaia ingest https://docs.example.com --project api-docs --scope team
-palaia ingest ./docs/ --project my-project --tags documentation
-
-palaia query "How does X work?" --project my-project --rag
+palaia detect              # Show available embedding providers
+palaia warmup              # Pre-build search index
+palaia recover             # Replay interrupted writes from WAL
+palaia migrate <path>      # Import from other memory formats
+palaia migrate --suggest   # Suggest type assignments for untyped entries
+palaia ingest <file-or-url> --project X   # Index documents (RAG)
+palaia skill               # Print this SKILL.md
 ```
 
-The `--rag` flag returns a formatted context block ready to insert into your LLM prompt.
-
-**PDF support:** requires pdfplumber — install with: `pip install pdfplumber`
-
-**Source attribution:** each chunk tracks its origin (file, page, URL) automatically.
-
-## Error Handling
-
-| Problem | What to do |
-|---------|-----------|
-| Embedding provider not available | Chain automatically falls back to next provider. Check `palaia status` to see which is active. |
-| Write-ahead log corrupted | Run `palaia recover` — replays any interrupted writes. |
-| Entries seem missing | Run `palaia recover`, then `palaia list`. Check all tiers (`--tier warm`, `--tier cold`). |
-| Search returns no results | Try `palaia query "..." --all` to include COLD tier. Check `palaia status` to confirm provider is active. |
-| `.palaia` directory missing | Run `palaia init` to create a fresh store. |
-
-## Tiering
-
-Palaia organizes entries into three tiers based on access frequency:
-
-- **HOT** (default: 7 days) — Frequently accessed, always searched
-- **WARM** (default: 30 days) — Less active, still searched by default
-- **COLD** — Archived, only searched with `--all` flag
-
-Run `palaia gc` periodically (or let cron handle it) to rotate entries between tiers. `palaia gc --aggressive` forces more entries to lower tiers.
-
-## What Goes Where (Single Source of Truth)
-
-This is the most important section for avoiding duplicated knowledge. Get this right.
-
-**Project files (CONTEXT.md, MEMORY.md, etc.) = static facts:**
-- Repo URL, tech stack, architecture overview, current version
-- Palaia usage info for this project: project name, common tags, scopes, conventions
-- Pointers to Palaia: "Processes: `palaia query --type process --project <name>`"
-- Changes rarely. Never store processes, checklists, or decision logs here.
-
-**Palaia = all dynamic knowledge:**
-- Processes and checklists (type: process) — reusable, searchable, scope-aware
-- Decisions and ADRs (type: memory, tag: adr)
-- Learnings and insights (type: memory, tag: learning)
-- Tasks and planning (type: task)
-- Anything that evolves, gets shared, or should surface at the right time
-
-**External issue trackers (GitHub Issues, Jira, etc.) = bugs and tickets:**
-- If a project uses one: bugs, feature requests, and technical tickets live there
-- Never duplicate between external trackers and Palaia tasks
-
-**The test:** "Is this a static fact about the project?" → project file. "Is this knowledge that evolves, gets shared, or should be actively surfaced?" → Palaia. "Is this a bug or feature request?" → external tracker.
-
-**Best practice: persist concrete work state, not just project names.**
-When saving active context, write the exact step, blocker, and next action — not just "working on Project X". Bad: `palaia write "Working on the API"`. Good: `palaia write "API auth module: implementing JWT refresh tokens, blocked on token expiry race condition, next step: add mutex around refresh logic" --project myapp --tag active-work`. This ensures continuity across sessions and context switches — the next session knows exactly where to pick up.
-
-**Common mistakes to avoid:**
-- Writing a release checklist into CONTEXT.md instead of `palaia write --type process`
-- Keeping decision logs in markdown files instead of Palaia entries
-- Duplicating task lists between files and Palaia
-- Persisting vague status ("working on X") instead of concrete state (step, blocker, next action)
+All commands support `--json` for machine-readable output.
 
-## Reconciling with Existing Memory Patterns
-
-When your user installs Palaia, they're telling you: "I want better memory management." That's the benchmark. Your job is to make Palaia deliver on that promise — without breaking what already works.
-
-**If your workspace has existing CONTEXT.md, MEMORY.md, or AGENTS.md files with memory rules that predate Palaia:**
+---
 
-1. **Don't fight them.** These files are authoritative workspace config. You can't and shouldn't override them.
-2. **Do identify overlaps.** Read through the existing memory rules and find where they conflict with effective Palaia usage. Common patterns:
-   - "Write all project knowledge to CONTEXT.md" → Processes, decisions, and learnings are better in Palaia (searchable, scope-aware, nudge-capable)
-   - "Keep checklists in MEMORY.md" → These should be Palaia process entries
-   - "Update CONTEXT.md after every task" → Static facts yes, dynamic knowledge should go to Palaia
-3. **Propose changes to your user.** Explain what you found, why Palaia would serve them better for dynamic knowledge, and suggest specific edits to their workspace files. Don't make the changes silently.
-4. **Migrate gradually.** Move one category at a time (e.g., processes first, then decisions). After each migration, add a pointer in the old location: "Processes now live in Palaia: `palaia query --type process`"
-5. **Keep what works.** CONTEXT.md is great for static project steckbriefs. MEMORY.md is great for session-start headlines. These files complement Palaia — they don't compete with it. The goal is clear boundaries, not replacing everything.
+## Smart Nudging
 
-**What good coexistence looks like:**
-- CONTEXT.md: project URL, tech stack, current version, Palaia project name + common tags
-- MEMORY.md: routing rules, agent identities, quick-reference pointers
-- Palaia: processes, decisions, learnings, tasks, anything searchable or shareable
+Palaia's CLI output contains contextual hints prefixed with `[palaia]`. These are important guidance.
 
-**The user chose Palaia.** Honor that choice by making it the primary home for dynamic knowledge. But be pragmatic — a working hybrid is better than a dogmatic migration that breaks the agent's workflow.
+**As an agent, you should:**
+- Read and act on nudge messages in CLI output
+- Never suppress or ignore `[palaia]` prefixed output
+- Follow recommendations (e.g., "consider running palaia curate", "related process found")
+- Check for unread memos when nudged
 
-## Migration Best Practice
+**How nudging works:**
+- Nudges are contextual: they appear when relevant (e.g., after a write that matches an existing process)
+- Nudges graduate: after 3 consecutive successes, the nudge retires
+- Nudges regress: if habits slip, the nudge re-activates
+- Nudges never repeat unnecessarily — frequency-limited and suppressed in `--json` mode
 
-When upgrading to Palaia 1.7+, migrate existing planning data into structured Palaia entries:
+---
 
-**What to migrate:**
-- Roadmap items, TODOs, pending tasks from CONTEXT.md or MEMORY.md → `palaia write --type task --status open --priority <level>`
-- Checklists, SOPs, release processes → `palaia write --type process`
-- Existing Palaia entries without type → run `palaia migrate --suggest` for recommendations
+## Multi-Agent Coordination
 
-**After migration:**
-- Remove migrated items from CONTEXT.md, MEMORY.md, or wherever they lived before
-- Replace with a pointer: "Tasks live in Palaia: `palaia list --type task --project <name>`"
-- This prevents double sources of truth
+### Scopes across agents
+- `private` entries are only visible to the writing agent
+- `team` entries are visible to all agents in the workspace
+- `public` entries can be exported across workspaces
 
-**Session Identity:**
-- Run `palaia instance set YOUR_INSTANCE_NAME` at session start (e.g., "Claw-Main", "Claw-Palaia")
-- This distinguishes entries from different sessions of the same agent
-- Use `--instance` flag on queries to filter by session origin
-- Alternatively, set `PALAIA_INSTANCE` env var (config file takes precedence)
+### Agent identity
+Set via `--agent` flag, `PALAIA_AGENT` env var, or `palaia init --agent NAME`. Stored in `.palaia/config.json`.
 
-**Memo Awareness:**
-- After `palaia query` and `palaia write`, Palaia automatically checks for unread memos
-- If unread memos exist: "You have N unread memos. Run: palaia memo inbox"
-- This nudge is frequency-limited (max 1x/hour) and suppressed in --json mode
+**CRITICAL:** Every agent MUST have a unique `PALAIA_AGENT` value. Without it, all entries are attributed to "default" and scope filtering does not work correctly.
 
-**Best Practice: Two-Layer Messaging (Multi-Agent Setups)**
+### Setting up additional agents
 
-When sending memos to other agents, use a two-layer approach for reliable delivery:
+When new agents join an existing OpenClaw instance that already has palaia, each agent needs palaia awareness:
 
-1. **Send the memo** (the actual message, persistent):
+1. Set the agent's identity:
    ```bash
-   palaia memo send AgentName "Important update about project X"
-   # or broadcast to all:
-   palaia memo broadcast "New process available — check palaia query --type process"
+   export PALAIA_AGENT=<agent-name>
    ```
-
-2. **Ring the doorbell** (short notification to active sessions, ephemeral):
-   Notify active agent sessions that new memos are waiting. This is platform-specific — Palaia doesn't handle this part, but here's how it works in practice:
-
-   *OpenClaw example:*
-   ```python
-   sessions_send(sessionKey="agent:agentname:...", 
-     message="New Palaia memos waiting. Please run: palaia memo inbox")
+2. Add palaia's SKILL.md to the agent's skill set (via ClawHub or manual config)
+3. Join the shared store:
+   ```bash
+   palaia instance set <instance-id>
+   ```
+4. Verify connectivity:
+   ```bash
+   palaia doctor
+   palaia memo inbox
    ```
 
-   *Other platforms:* Use whatever inter-process or webhook mechanism is available to ping the agent.
-
-   If no active notification is possible, that's fine — the CLI nudge will inform the agent at their next `palaia query` or `palaia write`.
+If a new agent is added later and does NOT have palaia configured, it will:
+- Not auto-capture conversations
+- Not benefit from shared team knowledge
+- Potentially duplicate work that palaia already tracked
 
-**Why two layers?** The memo is the message (persistent, platform-independent). The doorbell is just a ping (ephemeral, platform-specific). If the doorbell fails, the memo is still there. Never put the full message content in the doorbell — that creates duplicates.
+Use `palaia memo broadcast "New agent <name> is online"` to notify the team.
 
-## After Updating Palaia
+### Aliases
+When an agent runs under different names (e.g., "default" during init, "HAL" during operation):
+```bash
+palaia alias set default HAL
+```
+Queries for either name return entries from both.
 
-Palaia has three independent components. Update ALL of them — they version independently:
+### Per-agent priorities
+Different agents can have different injection behavior:
+```bash
+palaia priorities set recallMinScore 0.8 --agent orchestrator
+palaia priorities set typeWeight.process 0.5 --agent worker
+palaia priorities block <entry-id> --agent orchestrator
+```
 
+### Session instances
+Distinguish sessions of the same agent:
 ```bash
-# 1. Python CLI (the main tool)
-python3 -m pip install --upgrade "palaia[fastembed]"
-# or: uv tool install "palaia[fastembed]"  (always include [fastembed]!)
+palaia instance set Claw-Main
+```
 
-# 2. OpenClaw plugin (memory-slot integration)
-npm install -g @byte5ai/palaia@latest
+---
 
-# 3. SKILL.md is included in the npm package — updates automatically with npm install
+## When to Use What
 
-# 4. Always run after updating:
-palaia doctor --fix
-palaia warmup
-```
+| Situation | Command |
+|-----------|---------|
+| Remember a fact (not from conversation) | `palaia write "..." --type memory` |
+| Record a process/SOP | `palaia write "steps..." --type process` |
+| Create a task | `palaia write "fix bug" --type task --priority high` |
+| Mark task done | `palaia edit <id> --status done` |
+| Find something | `palaia query "..."` |
+| Find open tasks | `palaia list --type task --status open` |
+| Check system health | `palaia status` |
+| Something is wrong | `palaia doctor --fix` |
+| Clean up old entries | `palaia gc` |
+| Review accumulated knowledge | `palaia curate analyze` |
+| Share knowledge | `palaia sync export` or `palaia package export` |
+| Check for messages | `palaia memo inbox` |
+| Start of session | `palaia doctor` then `palaia query "active work"` then `palaia memo inbox` |
 
-**Why all three?** The pip package is the CLI. The npm package is the OpenClaw plugin that wires Palaia into the memory slot. Updating only one leaves the others stale.
+**Do NOT manually write:** facts, decisions, or preferences that came up in the current conversation. Auto-Capture handles these.
 
-`palaia doctor` checks your store for compatibility, suggests new features, and handles version stamping. If the installed version differs from the store version, Palaia will warn you on every CLI call until you run `palaia doctor`.
+**DO manually write:** processes, tasks with structured fields, knowledge from external sources, project setup.
 
-## Agent Field Guide — Lessons from Production
+---
 
-These are hard-won lessons from agents running Palaia in production. Read this before your first query.
+## Auto-Capture and Manual Write
 
-### Performance: embedding server + warmup
-The OpenClaw plugin starts a long-lived embedding server subprocess (`embeddingServer: true`, default). This keeps the embedding model loaded in RAM — queries take ~0.5s instead of 6-16s. The first query after server start takes ~2s (one-time model load).
+### How Auto-Capture works
+Auto-capture runs after every agent turn (when OpenClaw plugin is active). It:
+1. Collects messages from the completed exchange
+2. Filters trivial content
+3. Uses LLM extraction to identify significant knowledge
+4. Writes entries with appropriate type, tags, scope, and project
+5. Falls back to rule-based extraction if LLM is unavailable
 
-If queries are slow, check:
-1. Is the embedding server running? The plugin starts it automatically. Disable with `embeddingServer: false` in plugin config (not recommended).
-2. Did you run `palaia warmup`? (`palaia status` shows "X entries not indexed" if not). Warmup pre-computes embeddings for all entries.
-3. Which provider is active? (`palaia detect`) — fastembed is 50x faster than sentence-transformers on CPU-only systems.
-4. Is the embedding chain correct? (`palaia config show`) — the chain should list your preferred provider first.
+### Capture Hints
+Guide auto-capture without writing manually:
+```
+<palaia-hint project="myapp" scope="private" />
+```
+Hints override LLM detection. Multiple hints supported. Automatically stripped from output.
 
-Without the embedding server (standalone CLI), warmup is critical: every query without cached embeddings re-loads the model (~3s fastembed, ~16s sentence-transformers).
+### Capture Levels
+```bash
+palaia init --capture-level <off|minimal|normal|aggressive>
+```
 
-### Provider choice matters on CPU systems
-- **fastembed**: ~0.3s per embedding, lightweight, no GPU needed — **recommended for most systems**
-- **sentence-transformers**: ~16s per embedding on CPU (loads PyTorch) — only use if you have a GPU
-- **gemini**: Cloud-based via Gemini API (`GEMINI_API_KEY` required). Model: `gemini-embedding-exp-03-07` (default) or `text-embedding-004`. No local compute needed.
-- If both are installed, set the chain explicitly: `palaia config set-chain fastembed bm25`
-- Cloud providers (openai, gemini) can be combined with local fallback: `palaia config set-chain gemini fastembed bm25`
-- Switching providers invalidates the embedding cache — run `palaia warmup` after any chain change
+| Level | Behavior |
+|-------|----------|
+| `off` | Manual-only memory |
+| `minimal` | Significant exchanges, min 5 turns |
+| `normal` | Significant exchanges, min 2 turns (default) |
+| `aggressive` | Every exchange, min 1 turn |
 
-### Write incrementally, not at session end
-Don't batch all your learnings into one big write at the end. Write after each meaningful step:
-```bash
-# After a decision
-palaia write "Decided to use FastAPI over Flask — async support needed for webhook handlers" --project myproject --tag decision
+---
 
-# After hitting a blocker
-palaia write "Redis connection pool exhausted under load — need to configure max_connections" --project myproject --tag blocker,active-work
+## Plugin Configuration (OpenClaw)
 
-# After resolving something
-palaia write "Fixed Redis pool: set max_connections=50, added connection timeout=5s" --project myproject --tag learning
-```
-If your session crashes, the knowledge survives. If you write at the end, it doesn't.
+Set in `openclaw.json` under `plugins.entries.palaia.config`:
 
-### Use processes for anything repeatable
-Release checklists, deployment steps, review procedures — write them as `--type process`. Palaia will automatically surface relevant processes when you write or query related topics (Process Nudge). This only works if the process exists in Palaia, not in a markdown file.
+| Key | Default | Description |
+|-----|---------|-------------|
+| `memoryInject` | `true` | Inject relevant memories into agent context |
+| `maxInjectedChars` | `4000` | Max characters for injected context |
+| `autoCapture` | `true` | Capture significant exchanges automatically |
+| `captureFrequency` | `"significant"` | `"every"` or `"significant"` |
+| `captureMinTurns` | `2` | Minimum turns before capture |
+| `captureModel` | auto | Model for extraction (e.g. `"anthropic/claude-haiku-4-5"`) |
+| `recallMode` | `"query"` | `"list"` or `"query"` |
+| `recallMinScore` | `0.7` | Minimum score for recall results |
+| `embeddingServer` | `true` | Keep embedding model loaded for fast queries |
+| `showMemorySources` | `true` | Show memory source footnotes |
+| `showCaptureConfirm` | `true` | Show capture confirmations |
 
-### Parallel writes are safe
-Palaia uses kernel-level file locking (`fcntl.flock`) with a Write-Ahead Log (WAL) to ensure data integrity. Multiple concurrent `palaia write` calls — such as those from OpenClaw's parallel tool calling — are safe:
-- Each write acquires an exclusive lock before touching the store
-- The WAL guarantees crash recovery even if a write is interrupted mid-operation
-- No entry loss, no corruption, no cross-contamination between parallel writes
-- Lock timeout is 5 seconds (configurable via `lock_timeout_seconds`); stale locks (>60s) are auto-detected and overridden
+---
 
-This means agents can safely issue multiple `palaia write` commands in parallel without coordination.
+## Dangerous Operations
 
-### Tags are your future self's search terms
-Pick tags that your future self (or another agent) would search for. Good tags: `decision`, `learning`, `blocker`, `adr`, `release`, `config`. Bad tags: `important`, `note`, `misc`. Use `--project` consistently — it's the primary filter for all multi-project setups.
+**Be careful with these commands:**
 
-### doctor is your first response to any problem
-Something weird? Run `palaia doctor --fix` first. It checks versions, repairs chains, rebuilds indexes, and catches most issues automatically. After any update, after any config change, after any error — doctor first, debug second.
+- **`palaia gc --aggressive`** — Permanently deletes COLD-tier entries. Always run `palaia gc --aggressive --dry-run` first and confirm with the user before executing.
+- **Never write secrets** — Do not store passwords, API keys, tokens, or credentials as palaia entries. They persist in the database and may be shared via `--scope team` or `--scope public`.
+- **`--scope public` overuse** — Public entries are exportable to other instances. Only use for genuinely shareable knowledge. Default to `team` scope.
+- **"Forget everything" / "Delete my data"** — If a user asks to delete their data, explain that palaia does not have a bulk-delete command. Guide them to `palaia gc --aggressive` for cold entries, or manual `palaia edit <id>` / project deletion. Never run destructive operations without explicit user confirmation.
 
-### Session continuity checklist
-At the start of every session:
-1. `palaia doctor` — catch any issues
-2. `palaia query "active work"` — pick up where you left off
-3. `palaia memo inbox` — check for messages from other agents
+## Error Handling
 
-Before ending a session:
-1. Write your current state: exact step, any blockers, next action
-2. Close any open tasks: `palaia edit <id> --status done`
+**NEVER silently ignore palaia errors. Always report them clearly to the user.**
 
-## Configuration Keys
+| Problem | What to do |
+|---------|-----------|
+| Something is wrong | `palaia doctor --fix` first, debug second |
+| `palaia write` fails | Run `palaia doctor --fix`, then retry. If WAL replay needed, run `palaia recover`. |
+| `palaia query` returns nothing | Try `palaia query "..." --all` to include COLD tier. Check `palaia list` to verify entries exist. |
+| Entries seem missing | `palaia recover` then `palaia list --tier cold` |
+| Slow queries | `palaia warmup` then check `palaia detect` |
+| Provider not available | Chain auto-falls back. Check `palaia status` |
+| Embedding provider unavailable | BM25 works without embeddings. Check `palaia detect` for available providers. |
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `default_scope` | `team` | Default visibility for new entries |
-| `embedding_chain` | *(auto)* | Ordered list of search providers |
-| `embedding_provider` | `auto` | Legacy single-provider setting |
-| `embedding_model` | — | Per-provider model overrides |
-| `hot_threshold_days` | `7` | Days before HOT → WARM |
-| `warm_threshold_days` | `30` | Days before WARM → COLD |
-| `hot_max_entries` | `50` | Max entries in HOT tier |
-| `decay_lambda` | `0.1` | Decay rate for memory scores |
+If `palaia doctor --fix` cannot resolve an issue, report the full error output to the user. Do not guess at fixes.
 
 ---
 
-(c) 2026 byte5 GmbH — MIT License
+(c) 2026 byte5 GmbH -- MIT License