---

name: palaia version: "2.0.8" description: > Local, crash-safe persistent memory for OpenClaw agents. Replaces built-in memory-core with semantic search, projects, and scope-based access control. After installing or updating, run: palaia doctor --fix to complete setup. metadata: openclaw: emoji: 🧠 requires: bins: ["palaia"] install: - id: pip kind: pip package: "palaia[fastembed]" bins: ["palaia"] label: "Install Palaia with fastembed (pip)" postInstall: - command: "palaia init" label: "Initialize Palaia store" - command: "npm install -g @byte5ai/palaia@latest" label: "Install OpenClaw plugin (npm)" postUpdate: - command: "python3 -m pip install --upgrade 'palaia[fastembed]' && (npm install -g @byte5ai/palaia@latest 2>/dev/null || true) && palaia doctor --fix && palaia warmup" label: "Upgrade Palaia (pip + npm plugin if available) and run health checks" postUpdateMessage: > Palaia has been updated to v2.0. New features: Auto-Capture (on by default), Query-based Recall, optimized defaults for zero-config UX. Recommendation: Run palaia doctor --fix to upgrade your config to the new defaults. Custom values you've set will NOT be touched. plugin: slot: memory package: "@byte5ai/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 pip install "palaia[fastembed]" and activating the OpenClaw 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.

Communication During Setup

• After each major step, send a brief status message to the user. Don't go silent.
• If a step takes longer than ~10 seconds, say what you're doing: "Installing sentence-transformers, this takes a moment…"
• If something unexpected happens (e.g. CUDA error, provider fails), explain what happened and what you're doing instead — immediately.
• Don't batch all steps and report at the end. Report after each step.

Example pacing:

1. "Installing Palaia…" → [runs pip install] → "Done. Initializing store…" → [runs palaia init] → "Store ready."
2. "Installing OpenClaw plugin…" → [runs npm install -g @byte5ai/palaia@latest] → "Plugin installed. Activating…" → [patches config, restarts gateway] → "Plugin active."
3. "Running diagnostics…" → [runs palaia doctor] → "Found: [X]. Quick question:"
4. [Onboarding conversation — max 3 questions]
5. "Configuring chain… warming up model (this takes ~15 seconds)…" → "Ready."
6. "All set. Here's your setup: [one sentence summary]"

Setup Flow (follow this exactly)

Step 1: Install and initialize

Choose your package manager (use whichever is available on your system):

# pip (most common)
python3 -m pip install "palaia[fastembed]"

# uv (if pip is not available)
uv tool install "palaia[fastembed]"

# pipx (alternative)
pipx install "palaia[fastembed]"

Important (uv users): Always include the [fastembed] extra. uv tool install palaia without extras will remove previously installed embedding providers (fastembed, sentence-transformers) on upgrade. This is by design — uv strictly manages dependencies. Always use uv tool install "palaia[fastembed]" for both install and upgrade.

palaia init

Agent identity is optional but recommended. palaia init without --agent sets the agent name to "default". This works fine for single-agent systems. For multi-agent setups, use --agent:

palaia init --agent YOUR_AGENT_NAME

If an OpenClaw config with a single agent is detected, the name is auto-detected:

Auto-detected agent: HAL (from OpenClaw config)

The agent name is stored in .palaia/config.json and automatically attached to all writes and memo operations. No env vars needed.

Single-Agent to Multi-Agent Migration: When adding a second agent later, existing entries keep their original agent name ("default"). To associate old "default" entries with your named agent:

palaia config set-alias default YOUR_NAME

This makes queries for YOUR_NAME also return entries written as "default". No entries are rewritten — aliases are query-time only. palaia doctor will remind you if this is needed.

Optional: Set session instance (for multi-instance agents):

palaia instance set YOUR_INSTANCE_NAME

Instance is session-local and adds traceability to entries. Memos can target specific instances.

Step 2: Install and activate OpenClaw plugin (REQUIRED)

The npm plugin wires Palaia into OpenClaw's memory slot — without it, Auto-Capture and Auto-Recall don't work.

npm install -g @byte5ai/palaia@latest

Now activate the plugin in OpenClaw.

[INSTRUCTION for LLM]: Do NOT blindly overwrite plugin config arrays with openclaw config set. Arrays like plugins.allow and plugins.load.paths may already contain other plugins (telegram, slack, clawsy-bridge...). Overwriting them destroys the existing configuration. Always read first, then append if missing.

Preferred: Use gateway config.patch (deep-merges, safest)

If you have access to the gateway tool, use config.patch — it deep-merges instead of overwriting:

# First, read existing values to avoid duplicates
PALAIA_PATH="$(npm root -g)/@byte5ai/palaia"
existingAllow = gateway(action="config.get", key="plugins.allow")  // e.g. ["telegram","slack"]
existingPaths = gateway(action="config.get", key="plugins.load.paths")  // e.g. ["/path/to/telegram"]

# Then patch (only add palaia if not already present)
gateway(action="config.patch", raw=JSON.stringify({
  plugins: {
    load: { paths: [...existingPaths, palaiaPath] },
    allow: [...existingAllow, "palaia"],
    slots: { memory: "palaia" },
    entries: { palaia: { enabled: true } }
  }
}), note="Palaia plugin activated")

Alternative: Safe shell approach (reads existing config, adds palaia, never overwrites)

PALAIA_PATH="$(npm root -g)/@byte5ai/palaia"

# Add to plugins.allow (only if not already present)
CURRENT_ALLOW=$(openclaw config get plugins.allow 2>/dev/null || echo '[]')
if ! echo "$CURRENT_ALLOW" | grep -q '"palaia"'; then
  NEW_ALLOW=$(echo "$CURRENT_ALLOW" | python3 -c "import sys,json; a=json.load(sys.stdin); a.append('palaia'); print(json.dumps(a))")
  openclaw config set plugins.allow "$NEW_ALLOW"
fi

# Add to plugins.load.paths (only if not already present)
CURRENT_PATHS=$(openclaw config get plugins.load.paths 2>/dev/null || echo '[]')
if ! echo "$CURRENT_PATHS" | grep -q "$PALAIA_PATH"; then
  NEW_PATHS=$(echo "$CURRENT_PATHS" | python3 -c "import sys,json,os; a=json.load(sys.stdin); a.append(os.environ['PALAIA_PATH']); print(json.dumps(a))")
  openclaw config set plugins.load.paths "$NEW_PATHS"
fi

# Set memory slot (safe — single value, not array)
openclaw config set plugins.slots.memory palaia

Typical npm root -g paths:

• Linux (Homebrew): /home/linuxbrew/.linuxbrew/lib/node_modules
• macOS (Homebrew): /opt/homebrew/lib/node_modules
• macOS (nvm): ~/.nvm/versions/node/vXX/lib/node_modules
• Linux (system): /usr/lib/node_modules
• Windows: %AppData%\npm\node_modules

Restart the gateway so the plugin loads:

openclaw gateway restart

Wait for the gateway to come back up, then verify:

palaia doctor

The output must include OpenClaw plugin: palaia is active. If it does not, re-check the path and config values above.

Step 3: Check for existing memory systems (REQUIRED — do not skip)

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 → 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 ' 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:

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)

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:

palaia config set-chain <provider1> [provider2] bm25

If only BM25 is shown and you want semantic search:

# 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

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:

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)

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

Troubleshooting: pip Not Found

On some hosts, pip is not available as a standalone command. Use these fallbacks in order:

# Option 1: python3 -m pip (most reliable)
python3 -m pip install --upgrade "palaia[fastembed]"

# Option 2: uv (modern Python package manager)
uv tool install "palaia[fastembed]"

# Option 3: pipx (if installed)
pipx install "palaia[fastembed]"

# Option 4: Bootstrap pip first
python3 -m ensurepip --upgrade
python3 -m pip install --upgrade "palaia[fastembed]"

# Option 5: Install from git directly
python3 -m pip install "palaia[fastembed] @ git+https://github.com/iret77/palaia.git"

uv users: When upgrading with uv tool install, always include [fastembed] — uv removes packages not in the dependency spec on upgrade. Running uv tool install palaia without extras will silently uninstall fastembed.

Troubleshooting: Debian/Ubuntu (PEP 668)

On Debian-based systems (Debian 12+, Ubuntu 23.04+), pip may fail with "externally-managed-environment". This is due to PEP 668 which prevents pip from modifying system Python packages.

Use one of these approaches:

# Option 1: User install (recommended)
python3 -m pip install --user "palaia[fastembed]"

# Option 2: Break system packages (use if you know what you're doing)
python3 -m pip install --break-system-packages "palaia[fastembed]"

# Option 3: pipx (cleanest isolation)
pipx install "palaia[fastembed]"

# Option 4: Virtual environment
python3 -m venv ~/.palaia-venv
~/.palaia-venv/bin/pip install "palaia[fastembed]"
alias palaia=~/.palaia-venv/bin/palaia

After upgrading, always run palaia doctor --fix to verify providers and update the store.

Important: If you had sentence-transformers or fastembed installed before upgrading, verify they are still available after the upgrade:

palaia detect

If a provider is missing, reinstall it:

python3 -m pip install "palaia[sentence-transformers]"
palaia warmup

Plugin Activation (OpenClaw Memory Backend)

After installing palaia, activate it as your memory backend:

1. Install the OpenClaw plugin

npm install -g @byte5ai/palaia

2. Configure OpenClaw

Config path: plugins.entries.palaia.config in your OpenClaw config (openclaw.json).

Warning: Do NOT use plugins.config.palaia — that path does not exist. The correct structure is plugins.entries.palaia.config.

Patch your OpenClaw config (openclaw.json) to load and activate the plugin:

{
  "plugins": {
    "load": {
      "paths": ["<path-to-npm-global>/node_modules/@byte5ai/palaia"]
    },
    "allow": ["..existing..", "palaia"],
    "slots": {
      "memory": "palaia"
    },
    "entries": {
      "palaia": {
        "enabled": true,
        "config": {
          "workspace": "/path/to/.openclaw/workspace"
        }
      }
    }
  }
}

Find your npm global path with: npm root -g

Plugin config keys (under plugins.entries.palaia.config):

Key	Description
workspace	Path to the OpenClaw workspace (where .palaia/ lives)
memoryInject	Inject memories into agent context (default: true)
maxInjectedChars	Max characters for injected context (default: 4000)
recallMinScore	Minimum score for relevant recall results (default: 0.7)
autoCapture	Capture significant exchanges automatically (default: true)
captureFrequency	"every" or "significant" (default: "significant")
captureMinTurns	Minimum exchange turns before capture (default: 2)
captureModel	Explicit model for LLM extraction (e.g. "anthropic/claude-haiku-4-5"). Recommended: set a cheap/fast model. If unset, uses your primary model.
showMemorySources	Show memory source footnotes in responses (default: true)
showCaptureConfirm	Show capture confirmations in responses (default: true)
recallMode	"list" or "query" — how memories are retrieved (default: "query")

Note (Issue #66): Plugin config is currently global — all agents on the same OpenClaw instance share the same config from openclaw.json. Per-agent config resolution would require an OpenClaw upstream change where the plugin API provides agent-scoped config. Individual agent behavior (e.g. different capture levels) can be configured via palaia init --capture-level which writes to .palaia/config.json locally.

Capture Level (Issue #67)

Configure how aggressively Palaia auto-captures agent exchanges:

palaia init --capture-level <off|sparsam|normal|aggressiv>

Level	autoCapture	Frequency	Min Turns	Use Case
off	false	—	—	Manual-only memory
sparsam	true	significant	5	Low noise, long sessions
normal	true	significant	2	Recommended default
aggressiv	true	every	1	Maximize capture

The setting is stored in .palaia/config.json under plugin_config. palaia doctor checks if a capture level is configured and suggests setting one in OpenClaw environments.

3. Restart OpenClaw Gateway

The config change requires a gateway restart to take effect.

What changes

• memory_search and memory_get tools now search the Palaia store instead of MEMORY.md files
• MEMORY.md and workspace files continue to be loaded as project context (unchanged)
• All Palaia features (projects, scopes, tiering, semantic search) are available through the standard memory tools

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.

# 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:

# 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:

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:

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:

# 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

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

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

# 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).

# 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

# 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

# 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

# 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)

# 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

# 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:

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:

# 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:

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):

   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:

   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:

# 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 (agent instructions — if installed via ClawHub)
clawhub update palaia

# 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. The SKILL.md (via ClawHub) tells agents how to use Palaia. 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: warmup is not optional

After install or update, always run palaia warmup. Without it, every query re-computes embeddings for all entries — that's 14+ seconds on CPU systems. After warmup, the same query takes <2 seconds. The warmup builds a persistent embedding cache that survives restarts.

If queries are slow, check:

1. Did you run palaia warmup? (palaia status shows "X entries not indexed" if not)
2. Which provider is active? (palaia detect) — fastembed is 50x faster than sentence-transformers on CPU-only systems
3. Is the embedding chain correct? (palaia config show) — the chain should list your preferred provider first

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:

# 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

---

© 2026 byte5 GmbH — MIT License