@byte5ai/palaia 2.0.10 → 2.0.11

package/openclaw.plugin.json

@@ -2,6 +2,7 @@
   "id": "palaia",
   "name": "Palaia Memory",
   "kind": "memory",
+  "skills": ["./skill"],
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byte5ai/palaia",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "Palaia memory backend for OpenClaw",
   "main": "index.ts",
   "openclaw": {
@@ -12,7 +12,8 @@
     "index.ts",
     "src/",
     "openclaw.plugin.json",
-    "README.md"
+    "README.md",
+    "skill/"
   ],
   "keywords": [
     "openclaw",

package/skill/SKILL.md

@@ -0,0 +1,873 @@
+---
+name: palaia
+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.
+---
+
+> **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 — Agent Memory Skill
+
+## 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.
+
+## 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.")
+
+If no OpenAI key BUT local model detected:
+  → Just confirm: "Using local search model — works offline, no API costs."
+  → No question needed.
+
+**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)
+
+**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
+
+**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)
+
+**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.
+
+### 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.
+
+### 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.
+
+If the chain looks wrong or you want to change it:
+```bash
+palaia config set-chain <provider1> [provider2] bm25
+```
+
+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.
+
+### Step 5b: Warm up models
+```bash
+palaia warmup
+```
+This pre-downloads embedding models so the first search is instant. Always run after chain setup.
+
+### 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"
+```
+**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.
+
+**Do not tell the user "setup complete" until this verification passes.** Assumption is not verification.
+
+### 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.
+
+**Manual `palaia write` is for structured knowledge that Auto-Capture cannot create:**
+
+| 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 |
+
+**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)
+
+**Rule of thumb:** If it just happened in conversation → trust Auto-Capture. If it needs structure (steps, fields, project assignment) → write manually.
+
+### Capture Hints
+
+When you want to guide auto-capture without writing manually, use `<palaia-hint />` tags in your message:
+
+```
+<palaia-hint project="myapp" scope="private" />
+```
+
+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
+
+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" />
+```
+
+### 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
+
+Export and import project knowledge as portable package files.
+
+```bash
+# Export all entries from a project
+palaia package export <project> [--output file.palaia-pkg.json] [--types memory,process]
+
+# Import a knowledge package
+palaia package import <file> [--project target] [--merge skip|overwrite|append] [--agent name]
+
+# View package metadata without importing
+palaia package info <file>
+```
+
+The `--agent` flag on import attributes all imported entries to a specific agent name.
+
+## Process Runner
+
+Run stored process entries as interactive checklists:
+
+```bash
+# List all stored processes
+palaia process list [--project NAME]
+
+# Run a process interactively
+palaia process run <id>
+```
+
+## Temporal Queries
+
+Filter entries by time with `--before` and `--after`:
+
+```bash
+palaia query "deploy" --after 2026-03-01 --before 2026-03-15
+palaia list --after 2026-03-01
+```
+
+Dates are in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS).
+
+## Cross-Project Search
+
+Search across all projects at once:
+
+```bash
+palaia query "authentication" --cross-project
+```
+
+Without `--cross-project`, queries only search entries in the active project context.
+
+## Bounded Memory and Garbage Collection
+
+Palaia supports budgeted garbage collection to keep the store lean:
+
+```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:
+
+| 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" |
+
+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:
+
+```
+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`
+
+### Capture Confirmations
+
+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
+
+```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]
+
+# System health, active providers, and entry class breakdown
+palaia status
+
+# Suggest type assignments for untyped entries
+palaia migrate --suggest
+```
+
+### 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"]
+
+# Search within a project only
+palaia project query <name> "search term" [--limit N]
+
+# 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.
+
+```bash
+# Set alias: "default" is treated as "HAL"
+palaia alias set default HAL
+
+# List all aliases
+palaia alias list
+
+# Remove an alias
+palaia alias remove default
+```
+
+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).
+
+```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>
+
+# Release a lock
+palaia project unlock <name>
+
+# Force-break a stuck lock (use with caution)
+palaia project break-lock <name>
+
+# List all active locks
+palaia project locks
+```
+
+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
+
+```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
+```
+
+### Diagnostics
+
+```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
+
+```bash
+# Tier rotation — moves old entries from HOT → WARM → COLD
+palaia gc [--aggressive]
+
+# Replay any interrupted writes from the write-ahead log
+palaia recover
+```
+
+### Document Ingestion (RAG)
+
+```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
+```
+
+### Sync
+
+```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]
+```
+
+### JSON Output
+
+All commands support `--json` for machine-readable output:
+```bash
+palaia status --json
+palaia query "search" --json
+palaia project list --json
+```
+
+## Scope System
+
+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>
+```
+
+**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
+
+| 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
+```
+
+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)
+
+## 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.
+
+**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
+
+**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.
+
+## Migration Best Practice
+
+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
+
+**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
+
+**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)
+
+**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
+
+**Best Practice: Two-Layer Messaging (Multi-Agent Setups)**
+
+When sending memos to other agents, use a two-layer approach for reliable delivery:
+
+1. **Send the memo** (the actual message, persistent):
+   ```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"
+   ```
+
+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")
+   ```
+
+   *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`.
+
+**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.
+
+## After Updating Palaia
+
+Palaia has three independent components. Update ALL of them — they version independently:
+
+```bash
+# 1. Python CLI (the main tool)
+python3 -m pip install --upgrade "palaia[fastembed]"
+# or: uv tool install "palaia[fastembed]"  (always include [fastembed]!)
+
+# 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
+
+# 4. Always run after updating:
+palaia doctor --fix
+palaia warmup
+```
+
+**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.
+
+`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`.
+
+## Agent Field Guide — Lessons from Production
+
+These are hard-won lessons from agents running Palaia in production. Read this before your first query.
+
+### 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).
+
+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.
+
+Without the embedding server (standalone CLI), warmup is critical: every query without cached embeddings re-loads the model (~3s fastembed, ~16s sentence-transformers).
+
+### 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
+
+### 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
+
+# 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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
+
+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`
+
+## Configuration Keys
+
+| 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 |
+
+---
+
+(c) 2026 byte5 GmbH — MIT License