palaia

Category: Tools & Productivity | Uploader: byte5ai | Downloads: 2 | Version: v1.0（Latest）

Local, crash-safe persistent memory for OpenClaw agents. SQLite-backed by default. Semantic search, projects, scopes, auto-capture. After installing or updating, run: palaia doctor --fix to complete setup.

Changelog: Source: GitHub https://github.com/byte5ai/palaia

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.yml 1.4 KB
  - 📄 feature_request.yml 837 B
- 📁 workflows/
  - 📄 ci.yml 1.2 KB
  - 📄 publish.yml 1.3 KB
- 📄 pull_request_template.md 314 B
📁 .hooks/
- 📄 pre-push 657 B
📁 docs/
- 📁 adr/
  - 📄 001-semantic-search-tiered.md 1.4 KB
  - 📄 002-scope-tags-knowledge-transfer.md 1.7 KB
  - 📄 003-wal-protocol.md 1.3 KB
  - 📄 004-hot-warm-cold-tiering.md 1.6 KB
  - 📄 005-git-as-knowledge-exchange.md 2.2 KB
  - 📄 006-memory-entry-format.md 1.4 KB
  - 📄 007-concurrent-write-locking.md 1.0 KB
  - 📄 008-projects.md 2.7 KB
  - 📄 009-rag-ingestion.md 2.6 KB
- 📄 backends.md 3.6 KB
- 📄 claude-code.md 5.0 KB
- 📄 cli-reference.md 14.7 KB
- 📄 configuration.md 3.6 KB
- 📄 embed-server.md 3.8 KB
- 📄 getting-started.md 2.9 KB
- 📄 mcp.md 5.0 KB
- 📄 migration-guide.md 3.5 KB
- 📄 multi-agent.md 4.8 KB
📁 packages/
- 📁 openclaw-plugin/
  - 📁 skill/
    
    📄 SKILL.md 31.1 KB
  - 📁 src/
    
    📁 hooks/
    
    📄 capture.ts 29.1 KB
    
    📄 index.ts 34.9 KB
    
    📄 reactions.ts 5.4 KB
    
    📄 recall.ts 15.4 KB
    
    📄 session.ts 15.9 KB
    
    📄 state.ts 14.3 KB
    
    📄 config.ts 4.8 KB
    
    📄 context-engine.ts 19.8 KB
    
    📄 priorities.ts 7.2 KB
    
    📄 runner.ts 14.3 KB
    
    📄 tools.ts 11.3 KB
    
    📄 types.ts 13.4 KB
  - 📁 tests/
    
    📄 context-engine.test.ts 5.3 KB
    
    📄 embed-server.test.ts 6.5 KB
    
    📄 hooks.test.ts 53.4 KB
    
    📄 priorities.test.ts 6.5 KB
    
    📄 runner.test.ts 3.8 KB
    
    📄 session.test.ts 4.0 KB
    
    📄 tools.test.ts 9.1 KB
  - 📄 .gitignore 14 B
  - 📄 index.ts 3.5 KB
  - 📄 openclaw.plugin.json 4.5 KB
  - 📄 package-lock.json 274.6 KB
  - 📄 package.json 763 B
  - 📄 README.md 2.9 KB
  - 📄 tsconfig.json 421 B
  - 📄 vitest.config.ts 152 B
📁 palaia/
- 📁 backends/
  - 📄 __init__.py 2.1 KB
  - 📄 migrate.py 10.8 KB
  - 📄 postgres.py 16.1 KB
  - 📄 protocol.py 4.4 KB
  - 📄 sqlite.py 18.1 KB
- 📁 doctor/
  - 📄 __init__.py 3.9 KB
  - 📄 checks.py 65.8 KB
  - 📄 fixes.py 16.0 KB
  - 📄 report.py 2.0 KB
- 📁 mcp/
  - 📄 __init__.py 2.3 KB
  - 📄 server.py 10.9 KB
- 📁 services/
  - 📄 __init__.py 66 B
  - 📄 admin.py 34.1 KB
  - 📄 curate.py 2.0 KB
  - 📄 ingest.py 1.7 KB
  - 📄 memo.py 1.9 KB
  - 📄 misc.py 4.0 KB
  - 📄 package.py 2.0 KB
  - 📄 priorities.py 6.2 KB
  - 📄 process.py 2.3 KB
  - 📄 project.py 4.3 KB
  - 📄 query.py 9.6 KB
  - 📄 status.py 6.8 KB
  - 📄 write.py 10.9 KB
- 📁 web/
  - 📁 routes/
    
    📄 __init__.py 24 B
    
    📄 entries.py 10.5 KB
    
    📄 search.py 4.0 KB
    
    📄 status.py 3.7 KB
  - 📁 static/
    
    📄 app.js 22.4 KB
    
    📄 index.html 7.8 KB
    
    📄 style.css 16.0 KB
  - 📄 __init__.py 56 B
  - 📄 app.py 1.5 KB
- 📄 __init__.py 150 B
- 📄 __main__.py 141 B
- 📄 bm25.py 2.8 KB
- 📄 cli.py 50.6 KB
- 📄 cli_args.py 30.9 KB
- 📄 cli_commands.py 34.8 KB
- 📄 cli_helpers.py 4.8 KB
- 📄 cli_nudge.py 6.7 KB
- 📄 config.py 9.2 KB
- 📄 curate.py 26.0 KB
- 📄 decay.py 1.6 KB
- 📄 embed_client.py 7.6 KB
- 📄 embed_server.py 22.1 KB
- 📄 embeddings.py 33.3 KB
- 📄 entry.py 6.3 KB
- 📄 enums.py 777 B
- 📄 frontmatter.py 3.2 KB
- 📄 index.py 5.4 KB
- 📄 ingest.py 16.6 KB
- 📄 lock.py 9.1 KB
- 📄 locking.py 311 B
- 📄 memo.py 8.2 KB
- 📄 metadata_index.py 8.7 KB
- 📄 migrate.py 16.4 KB
- 📄 nudge.py 10.7 KB
- 📄 packages.py 7.5 KB
- 📄 priorities.py 8.6 KB
- 📄 process_runner.py 5.9 KB
- 📄 project.py 8.0 KB
- 📄 project_lock.py 6.1 KB
- 📄 scope.py 3.5 KB
- 📄 search.py 13.8 KB
- 📄 significance.py 4.5 KB
- 📄 SKILL.md 31.1 KB
- 📄 store.py 33.0 KB
- 📄 sync.py 9.0 KB
- 📄 ui.py 11.9 KB
- 📄 wal.py 6.1 KB
📁 script/
- 📄 setup 401 B
📁 skills/
- 📁 palaia/
  - 📄 SKILL.md 31.1 KB
📁 tests/
- 📄 __init__.py 0 B
- 📄 conftest.py 557 B
- 📄 test_agent_aliases.py 16.7 KB
- 📄 test_agent_flag.py 5.8 KB
- 📄 test_audit_fixes.py 7.4 KB
- 📄 test_auto_title.py 4.1 KB
- 📄 test_backend_migrate.py 6.2 KB
- 📄 test_backend_postgres.py 13.8 KB
- 📄 test_backend_sqlite.py 9.2 KB
- 📄 test_backup_restore.py 5.0 KB
- 📄 test_bm25.py 2.7 KB
- 📄 test_bounded_gc.py 5.9 KB
- 📄 test_capture_level.py 4.7 KB
- 📄 test_chain_cli.py 3.2 KB
- 📄 test_concurrent_writes.py 6.7 KB
- 📄 test_config.py 3.8 KB
- 📄 test_config_detection.py 8.2 KB
- 📄 test_cross_platform_lock.py 3.0 KB
- 📄 test_cross_project.py 4.1 KB
- 📄 test_curate.py 28.8 KB
- 📄 test_decay.py 908 B
- 📄 test_detect.py 2.9 KB
- 📄 test_doctor.py 19.6 KB
- 📄 test_doctor_fix_chain.py 14.9 KB
- 📄 test_doctor_memos.py 3.5 KB
- 📄 test_doctor_staleness.py 4.5 KB
- 📄 test_doctor_version.py 3.6 KB
- 📄 test_embed_server.py 12.3 KB
- 📄 test_embed_server_socket.py 17.9 KB
- 📄 test_embeddings.py 15.1 KB
- 📄 test_entry_classes.py 17.4 KB
- 📄 test_frontmatter.py 3.1 KB
- 📄 test_gemini_embeddings.py 7.3 KB
- 📄 test_hit_decay.py 2.5 KB
- 📄 test_incremental_indexing.py 4.8 KB
- 📄 test_index.py 2.7 KB
- 📄 test_ingest.py 13.3 KB
- 📄 test_init_gatekeeper.py 16.8 KB
- 📄 test_init_no_agent.py 18.8 KB
- 📄 test_isolation_nudges.py 6.5 KB
- 📄 test_list_filters.py 7.3 KB
- 📄 test_locking.py 10.0 KB
- 📄 test_mcp_server.py 8.5 KB
- 📄 test_memo.py 10.3 KB
- 📄 test_metadata_index.py 6.3 KB
- 📄 test_migrate.py 10.2 KB
- 📄 test_multi_agent.py 7.9 KB
- 📄 test_nudge_tracker.py 13.1 KB
- 📄 test_packages.py 9.4 KB
- 📄 test_plugin_defaults_upgrade.py 10.9 KB
- 📄 test_priorities.py 13.8 KB
- 📄 test_process_nudge.py 15.5 KB
- 📄 test_process_runner.py 5.6 KB
- 📄 test_project.py 11.9 KB
- 📄 test_project_owner.py 6.3 KB
- 📄 test_prune.py 5.5 KB
- 📄 test_scope.py 4.7 KB
- 📄 test_scope_enforcement.py 7.5 KB
- 📄 test_search.py 1.4 KB
- 📄 test_search_cache.py 3.5 KB
- 📄 test_search_chain.py 3.5 KB
- 📄 test_setup_claude_code.py 8.3 KB
- 📄 test_significance.py 3.3 KB
- 📄 test_skill.py 2.6 KB
- 📄 test_ssrf.py 3.5 KB
- 📄 test_status_index_hint.py 3.3 KB
- 📄 test_store.py 1.7 KB
- 📄 test_sync.py 4.0 KB
- 📄 test_temporal_queries.py 5.6 KB
- 📄 test_unicode.py 5.2 KB
- 📄 test_ux_improvements.py 14.3 KB
- 📄 test_wal.py 1.8 KB
- 📄 test_wal_corruption.py 6.6 KB
- 📄 test_warmup_reindex.py 9.0 KB
- 📄 test_webui.py 11.2 KB
📄 .clawhubignore 130 B
📄 .gitignore 149 B
📄 .pre-commit-config.yaml 152 B
📄 AGENTS.md 1.2 KB
📄 ARCHITECTURE.md 9.4 KB
📄 CHANGELOG.md 37.9 KB
📄 CONTRIBUTING.md 6.0 KB
📄 LICENSE 1.0 KB
📄 MANIFEST.in 72 B
📄 mkdocs.yml 939 B
📄 pyproject.toml 2.1 KB
📄 README.md 7.6 KB
📄 SKILL.md 31.1 KB

SKILL.md

---
name: palaia
version: "2.7.3"
description: >
  Local, crash-safe persistent memory for OpenClaw agents.
  SQLite-backed by default. Semantic search, projects, scopes, auto-capture.
  After installing or updating, run: palaia doctor --fix to complete setup.
metadata:
  openclaw:
    emoji: "\U0001F9E0"
    requires:
      bins: ["palaia"]
    install:
      - id: pip
        kind: pip
        package: "palaia[fastembed]"
        bins: ["palaia"]
        label: "Install palaia with semantic search (pip)"
    postInstall:
      - command: "palaia init"
        label: "Initialize palaia store"
      - command: "openclaw plugins install @byte5ai/palaia"
        label: "Install OpenClaw plugin"
    postUpdate:
      - command: "python3 -m pip install --upgrade 'palaia[fastembed]' && openclaw plugins install @byte5ai/palaia && palaia doctor --fix && palaia warmup"
        label: "Upgrade palaia with semantic search + plugin and run health checks"
    postUpdateMessage: >
      palaia has been updated to v2.7.3. Fixes: ContextEngine compaction conflict
      with OpenClaw, doctor phantom stale-task warnings, invisible entries with
      empty scope. Run `palaia doctor --fix` to verify.
    plugin:
      slot: memory
      package: "@byte5ai/palaia"
---

# palaia v2.7 — Agent Memory Skill

palaia is the memory system for OpenClaw agents. It gives you persistent, searchable, crash-safe memory across sessions. You don't need to understand how it works — just use the commands below.

<!-- begin:install -->
## First-Time Setup

When a user asks you to "set up palaia", "enable memory", or "remember things across sessions", run these steps:

```bash
pip install "palaia[fastembed]"
```

```bash
palaia init
```

This creates `.palaia/` with SQLite storage and automatically configures fastembed for semantic search. No manual configuration needed.

Confirm success to the user: "Memory is ready. I'll automatically remember important context from our conversations."

If `pip` is not available, try alternatives in this order:
```bash
python3 -m pip install "palaia[fastembed]"
uv tool install "palaia[fastembed]"
pipx install "palaia[fastembed]"
```

Optional extras (install as needed):
```bash
pip install "palaia[mcp]"          # MCP server for Claude Desktop, Cursor
pip install "palaia[curate]"       # Knowledge curation
```

Note: `palaia[fastembed]` already includes sqlite-vec for native SIMD vector search. No separate install needed.

### OpenClaw Plugin Setup (for Auto-Capture and Auto-Recall)

After the CLI is installed, wire it into OpenClaw:

```bash
openclaw plugins install @byte5ai/palaia
```

Then activate the memory slot in OpenClaw config:
```json5
// openclaw.json
{
  plugins: {
    slots: { memory: "palaia" }
  }
}
```

Restart the gateway and verify:
```bash
openclaw gateway restart
palaia doctor
```

### Agent Identity (optional)

Single-agent systems work with the default name. For multi-agent setups:
```bash
palaia init --agent YOUR_AGENT_NAME
```

## Updating palaia

When the user asks to update, or when `palaia status` shows a version mismatch:

```bash
palaia upgrade
```
This auto-detects the install method (pip/uv/pipx), preserves all installed extras (fastembed, mcp, sqlite-vec, curate), runs `palaia doctor --fix`, and upgrades the OpenClaw plugin if installed. No manual steps needed.

**If `palaia upgrade` is not recognized** (versions before v2.3.0), update manually:

```bash
# Step 1: Find install method
which palaia

# Step 2: Upgrade (use the method matching the path from Step 1)
# pip (path contains site-packages or .local):
pip install --upgrade "palaia[fastembed]"
# uv (path contains uv):
uv tool install "palaia[fastembed]"
# pipx (path contains pipx):
pipx install "palaia[fastembed]" --force

# Step 3: Health check + migration
palaia doctor --fix

# Step 4: Update OpenClaw plugin (if installed)
openclaw plugins install @byte5ai/palaia
```

After the manual update, `palaia upgrade` will be available for future updates.
<!-- end:install -->

## Auto-Check (run every time this skill is loaded)

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.

---

## Core Concepts

### Auto-Capture vs. Manual Write
Conversations are automatically captured when the OpenClaw plugin is active. Auto-capture handles routine knowledge extraction from conversations.

**Manual writes (`palaia write`) are higher value.** When you or the user identify something as especially important — a key decision, a reusable workflow, a critical fact from an external source — write it manually. Manually written entries are ranked higher than auto-captured ones in recall results, so they surface more prominently in future sessions. Use manual writes for:
- Important facts, decisions, or context from external sources
- Reusable processes and workflows (team runbooks)
- Sticky notes / reminders for future sessions (tasks)

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

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

### Entry Types
- **memory** — Facts, decisions, learnings (default)
- **process** — Workflows, checklists, SOPs (team runbooks)
- **task** — Sticky notes / reminders for future sessions. Tasks are ephemeral: when marked done, they are automatically deleted. Never auto-captured — only created by explicit `palaia write --type task`.

---

## Storage & Search

### Database Backends

| Backend | Use Case | Vector Search | Install |
|---------|----------|---------------|---------|
| **SQLite** (default) | Local, single-agent or small team | sqlite-vec (native KNN) or Python fallback | Included |
| **PostgreSQL** | Distributed teams, multiple hosts | pgvector (ANN, IVFFlat/HNSW) | `pip install 'palaia[postgres]'` |

SQLite is zero-config — `palaia init` creates a single `palaia.db` file with WAL mode for crash safety. For teams with agents on multiple machines, PostgreSQL centralizes the store:
```bash
palaia config set database_url postgresql://user:pass@host/db
# or: export PALAIA_DATABASE_URL=postgresql://...
```

### Semantic Vector Search

palaia uses **hybrid search**: BM25 keyword matching (always active) combined with semantic vector embeddings (when a provider is configured). This finds memories by meaning, not just keywords.

**Embedding providers** (checked in chain order, first available wins):

| Provider | Type | Latency | Install |
|----------|------|---------|---------|
| **fastembed** | Local (CPU) | ~10ms/query | `pip install 'palaia[fastembed]'` (default) |
| **sentence-transformers** | Local (CPU/GPU) | ~10ms/query | `pip install 'palaia[sentence-transformers]'` |
| **Ollama** | Local (server) | ~50ms/query | `ollama pull nomic-embed-text` |
| **OpenAI** | API | ~200ms/query | Set `OPENAI_API_KEY` |
| **Gemini** | API | ~200ms/query | Set `GEMINI_API_KEY` |
| **BM25** | Built-in | <1ms/query | Always available (keyword only) |

Configure the chain: `palaia config set embedding_chain '["fastembed", "bm25"]'`

Check what's available: `palaia detect`

### Embed Server (Performance)

For fast CLI queries, palaia runs a background embed-server that keeps the model loaded in memory:
```bash
palaia embed-server --socket --daemon   # Start background server
palaia embed-server --status            # Check if running
palaia embed-server --stop              # Stop server
```
Without the server, each CLI call loads the model fresh (~3-5s). With the embed-server: **~1.5s per CLI query** (Python startup + server call) or **<500ms via MCP/Plugin** (no CLI overhead).

The OpenClaw plugin starts the embed-server automatically. For CLI-only usage, it auto-starts on first query when a local provider (fastembed, sentence-transformers) is configured.

### MCP Server (Claude Desktop, Cursor, any MCP host)

palaia works as a standalone MCP memory server — **no OpenClaw required**. Any AI tool that supports MCP can use palaia as persistent local memory.

```bash
pip install 'palaia[mcp]'
palaia-mcp                              # Start MCP server (stdio)
palaia-mcp --root /path/to/.palaia      # Explicit store
palaia-mcp --read-only                  # No writes (untrusted hosts)
```

**Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "palaia": {
      "command": "palaia-mcp",
      "args": []
    }
  }
}
```

**Cursor** (Settings → MCP Servers → Add, or `.cursor/mcp.json`):
- Command: `palaia-mcp`
- Arguments: (none, or `--root /path/to/.palaia`)

**Claude Code** (`~/.claude/settings.json`):
```json
{"mcpServers": {"palaia": {"command": "palaia-mcp"}}}
```

**MCP Tools:**

| Tool | Purpose |
|------|---------|
| `palaia_search` | Semantic + keyword search across all memories |
| `palaia_store` | Save new memory (fact, process, task) |
| `palaia_read` | Read a specific entry by ID |
| `palaia_edit` | Update an existing entry |
| `palaia_list` | List entries by tier, type, or project |
| `palaia_status` | Show store health, entry counts, provider info |
| `palaia_gc` | Run garbage collection (tier rotation) |

**Read-only mode** (`--read-only`): Disables `palaia_store`, `palaia_edit`, `palaia_gc`. Use this when connecting untrusted AI tools that should only read memories, not modify them.

---

## Commands Reference

### `palaia write` — Save structured knowledge

Use for important facts, reusable processes, sticky-note tasks, and knowledge from external sources. Manually written entries rank higher than auto-captured ones in recall.

```bash
# Save an important fact (ranks higher than auto-capture)
palaia write "API rate limit is 100 req/min" --type memory --tags api,limits

# Record a reusable team workflow (use specific, unique titles!)
palaia write "Backend: Deploy to staging via Docker" --type process --project myapp --scope team

# Create a sticky note for a future session (deleted when done)
palaia write "verify backup works after schema migration" --type task

# Save to a specific project with scope
palaia write "Use JWT for auth" --project backend --scope team --tags decision
```

**Process naming convention:** Use the format `[Domain]: [What it does]` for process titles. Specific titles prevent duplicates and make processes findable.
- Good: `"Release: PyPI publish + ClawHub sync"`, `"Backend: Deploy to staging via Docker"`
- Bad: `"Deploy steps"`, `"Release process"` (too generic, will collide with other similar processes)

Before writing a new process, search for existing ones: `palaia query "deploy" --type process`. If a similar process exists, update it with `palaia edit <id>` instead of creating a new one.

### `palaia query` — Semantic search

Find memories by meaning, not just keywords.

```bash
# Basic search
palaia query "what's the rate limit"

# Filter by type and status
palaia query "tasks" --type task --status open

# Filter by tags
palaia query "session-summary" --tags session-summary

# Search within a project
palaia query "deploy steps" --project myapp

# Include archived (COLD) entries
palaia query "old decisions" --all

# Search across all projects
palaia query "authentication" --cross-project

# Time-filtered search
palaia query "deploy" --after 2026-03-01 --before 2026-03-15

# RAG-formatted output for LLM injection
palaia query "how does auth work" --project api --rag
```

### `palaia get` — Read a specific entry

```bash
palaia get <entry-id>
palaia get <entry-id> --from 5 --lines 20   # Read a portion
```

Use when you have an entry ID from a query result or nudge message.

### `palaia list` — Browse entries

```bash
# List active entries
palaia list

# Filter by tier, type, status
palaia list --tier warm --type task --status open --priority high

# Limit results
palaia list --type task --status open --limit 5

# Filter by project or assignee
palaia list --project myapp --assignee Elliot
```

### `palaia status` — System health check

```bash
palaia status
```

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.

### `palaia project` — Project context management

```bash
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
```

### `palaia memo` — Inter-agent messaging

```bash
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
```

### `palaia priorities` — Injection priority management (NEW in v2.2)

Control which memories are injected into each agent's context.

```bash
# Show what would be injected (with score breakdown)
palaia priorities

# Block an entry from injection for a specific agent
palaia priorities block <entry-id> --agent orchestrator

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

Config stored in `.palaia/priorities.json` with layered overrides: global -> per-agent -> per-project.

### `palaia curate analyze/apply` — Knowledge curation (NEW in v2.2)

For migrating knowledge to a new instance, cleaning up old entries, or reviewing accumulated knowledge.

```bash
# Analyze: clusters entries, detects duplicates, recommends KEEP/MERGE/DROP
palaia curate analyze --project myapp

# Apply: parses the user-edited report, produces clean export package
palaia curate apply report.md
```

Requires optional dependency: `pip install palaia[curate]` (adds scikit-learn).

Tell your user: "I can analyze your memory for cleanup. Want me to run a curation report?"

### `palaia sync export/import` — Git-based knowledge exchange

```bash
# Export entries for sharing
palaia sync export --project myapp --output ./export/

# Export to a git remote
palaia sync export --project myapp --remote git@github.com:team/knowledge.git

# Import entries
palaia sync import ./export/ --dry-run   # Preview first
palaia sync import ./export/
```

Note: The old `palaia export`/`palaia import` aliases still work but are deprecated.

### `palaia package export/import` — Portable knowledge packages

```bash
# Export project knowledge as a portable file
palaia package export myapp --output myapp.palaia-pkg.json

# Import a knowledge package
palaia package import myapp.palaia-pkg.json --project target --merge skip

# View package metadata
palaia package info myapp.palaia-pkg.json
```

### `palaia upgrade` — Update to latest version

```bash
palaia upgrade
```

Auto-detects the install method (pip/uv/pipx/brew), preserves all installed extras (fastembed, mcp, sqlite-vec, curate), runs `palaia doctor --fix`, and upgrades the OpenClaw npm plugin if present. Always use this instead of manual pip commands.

### `palaia ui` — Local memory explorer (NEW in v2.7)

```bash
pip install 'palaia[ui]'   # One-time: install FastAPI + uvicorn
palaia ui                  # Opens browser at http://127.0.0.1:8384
palaia ui --port 9000      # Custom port (auto-fallback if busy)
palaia ui --no-browser     # Don't auto-open browser
```

Browse, search, create, edit, and delete entries in the browser. Manual entries are highlighted with a gold border (1.3× recall boost). Tasks are post-its: clicking ✓ deletes them. The health pill in the header shows doctor status with actionable warnings. Localhost only — no authentication, no network exposure.

### `palaia doctor` — Diagnostics and auto-fix

```bash
palaia doctor              # Check health
palaia doctor --fix        # Auto-fix issues
palaia doctor --json       # Machine-readable output
```

Run this first whenever something is wrong. It checks versions, repairs chains, rebuilds indexes, detects legacy systems, and handles migration.

### `palaia gc` — Garbage collection

```bash
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
```

### `palaia prune` — Selective cleanup (NEW in v2.5)

```bash
palaia prune --agent moneypenny     # Remove auto-captured entries by agent
palaia prune --tags auto-capture    # Remove all auto-captured entries
palaia prune --dry-run              # Preview what would be removed
palaia prune --protect-type process # Never delete process entries
```

### `palaia config` — Configuration

```bash
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
```

### `palaia process` — Multi-step process tracking

```bash
palaia process list --project myapp       # List stored processes
palaia process run <id>                   # Run interactively
```

### `palaia lock/unlock` — Entry and project locking

```bash
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
```

### `palaia edit` — Modify existing entries

```bash
palaia edit <id> --status done         # For tasks: this DELETES the entry (sticky note completed)
palaia edit <id> --status wontfix      # For tasks: also deletes (cancelled reminder)
palaia edit <id> "updated content" --tags new,tags --priority high
```

**Task lifecycle:** Tasks are sticky notes. When you mark a task as `done` or `wontfix`, it is automatically deleted — not archived. This is intentional: completed reminders have no long-term value. If the outcome of the task should be remembered, write a separate memory entry before marking the task done.

### Other commands

```bash
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
```

All commands support `--json` for machine-readable output.

---

## Smart Nudging

palaia's CLI output contains contextual hints prefixed with `[palaia]`. These are important guidance.

**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

**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

---

## Multi-Agent Setup

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

### Agent identity
Set via `--agent` flag, `PALAIA_AGENT` env var, or `palaia init --agent NAME`. Stored in `.palaia/config.json`.

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

### Setting up additional agents

When new agents join an existing OpenClaw instance that already has palaia, each agent needs palaia awareness:

1. Set the agent's identity:
   ```bash
   export PALAIA_AGENT=<agent-name>
   ```
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
   ```

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

Use `palaia memo broadcast "New agent <name> is online"` to notify the team.

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

### 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
palaia instance set Claw-Main
```

### Agent Isolation Mode

For focused agents (Sonnet/Codex) that should only see their own memories:

**1. Configure in `priorities.json`:**
```json
{
  "agents": {
    "dev-worker": {
      "scopeVisibility": ["private"],
      "captureScope": "private",
      "maxInjectedChars": 2000,
      "recallMinScore": 0.85
    }
  }
}
```
Or via CLI:
```bash
palaia priorities set scopeVisibility private --agent dev-worker
palaia priorities set captureScope private --agent dev-worker
palaia priorities set maxInjectedChars 2000 --agent dev-worker
palaia priorities set recallMinScore 0.85 --agent dev-worker
```

**2. Set agent identity:**
```bash
export PALAIA_AGENT=dev-worker
```

**3. Auto-capture stays on** (crash safety net). Cleanup happens after the work package.

**4. After accepting work:**
```bash
palaia prune --agent dev-worker --tags auto-capture --protect-type process
```
This removes session noise while preserving learned SOPs.

#### Pre-configured Agent Profiles

| Profile | scopeVisibility | captureScope | maxInjectedChars | recallMinScore | autoCapture |
|---------|----------------|--------------|-----------------|----------------|-------------|
| **Isolated Worker** | `["private"]` | `private` | 2000 | 0.85 | true |
| **Orchestrator** | `["private","team","public"]` | `team` | 4000 | 0.7 | true |
| **Lean Worker** | `["private"]` | `private` | 1000 | 0.9 | false |

#### Orchestrator Lifecycle (process template)

Save this as a process entry for the orchestrator to recall:
```bash
palaia write "## Dev-Agent Lifecycle
1. Create agent identity: export PALAIA_AGENT=dev-worker-{task-id}
2. Configure isolation: palaia priorities set scopeVisibility private --agent dev-worker-{task-id}
3. Configure capture: palaia priorities set captureScope private --agent dev-worker-{task-id}
4. Assign work package via prompt
5. After acceptance: palaia prune --agent dev-worker-{task-id} --tags auto-capture --protect-type process
6. Verify: palaia list --agent dev-worker-{task-id} --type process
7. Process knowledge persists for future tasks" --type process --tags workflow,orchestration --scope private
```

---

## When to Use What

| Situation | Command |
|-----------|---------|
| Save an important fact or decision | `palaia write "..." --type memory` (ranks higher than auto-capture) |
| Document a reusable workflow | `palaia write "Domain: Steps..." --type process --scope team` |
| Leave a reminder for future sessions | `palaia write "check X after Y" --type task` (auto-deleted when done) |
| Mark a reminder as done | `palaia edit <id> --status done` (deletes the task) |
| Find something | `palaia query "..."` |
| Find open reminders | `palaia list --type task --status open` |
| Check system health | `palaia status` |
| Something is wrong | `palaia doctor --fix` |
| Clean up old entries | `palaia gc` |
| Clean up agent session noise | `palaia prune --agent NAME --tags auto-capture --protect-type process` |
| Review accumulated knowledge | `palaia curate analyze` |
| Share knowledge | `palaia sync export` or `palaia package export` |
| Check for messages | `palaia memo inbox` |
| Start of session | Session briefing is automatic. Just run `palaia doctor` and check `palaia memo inbox`. |

**Auto-capture** handles routine conversation knowledge. **Manual writes rank higher** in recall — use them when something is especially important, reusable, or comes from an external source.

**DO manually write:** key decisions, reusable processes (team runbooks), sticky-note reminders (tasks), important facts from external sources.

---

## Auto-Capture and Manual Write

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

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

### Capture Levels
```bash
palaia init --capture-level <off|minimal|normal|aggressive>
```

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

---

## Session Continuity (NEW in v2.4)

Session continuity gives agents automatic context restoration across sessions. These features work out of the box with the OpenClaw plugin -- no manual setup needed.

### Session Briefings
Session briefings are injected automatically at session start. They contain your last session summary and any open tasks (sticky notes). Read the briefing carefully — it is your primary context for continuing previous work. Do not ask the user "where did we leave off?" when a briefing is present. Instead, acknowledge the context and continue seamlessly.

### Session Summaries
When a session ends or resets, palaia auto-saves a summary of what happened. These are stored as entries with the `session-summary` tag and can be queried:
```bash
palaia query "session-summary" --tags session-summary
```

### Privacy Markers
Wrap sensitive content in `<private>...</private>` blocks to exclude it from auto-capture. Private blocks are stripped before any extraction runs.

### Recency Boost
Fresh memories are ranked higher in recall results. The boost factor is configurable via `recallRecencyBoost` (default `0.3`, set to `0` to disable).

### Progressive Disclosure
When result sets exceed 100 entries, palaia uses compact mode to keep context manageable. Use `--limit` to control result size explicitly:
```bash
palaia list --type task --status open --limit 5
```

---

## Plugin Configuration (OpenClaw)

Set in `openclaw.json` under `plugins.entries.palaia.config`:

| 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 |
| `sessionSummary` | `true` | Auto-save session summaries on end/reset |
| `sessionBriefing` | `true` | Load session context on session start |
| `sessionBriefingMaxChars` | `1500` | Max chars for session briefing injection |
| `captureToolObservations` | `true` | Track tool usage as session context |
| `recallRecencyBoost` | `0.3` | Boost factor for fresh memories (0=off) |
| `manualEntryBoost` | `1.3` | Boost factor for manually written entries vs auto-captured (1.0=off) |

---

## Dangerous Operations

**Be careful with these commands:**

- **`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.

## Error Handling

**NEVER silently ignore palaia errors. Always report them clearly to the user.**

| Problem | What to do |
|---------|-----------|
| Something is wrong | `palaia doctor --fix` first, debug second |
| `palaia init` fails | Check permissions on the directory, disk space, and Python version. Report the exact error to the user. |
| `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 | `pip install 'palaia[sqlite-vec]'` for native vector search, then `palaia warmup`. Check `palaia detect` and `palaia status` |
| Provider not available | Chain auto-falls back. Check `palaia status` |
| `.palaia` missing | `palaia init` |
| Embedding provider unavailable | BM25 works without embeddings. Check `palaia detect` for available providers. |

If `palaia doctor --fix` cannot resolve an issue, report the full error output to the user. Do not guess at fixes.

---

## Configuration Keys

| Key | Default | Description |
|-----|---------|-------------|
| `default_scope` | `team` | Default visibility for new entries |
| `embedding_chain` | *(auto)* | Ordered list of search providers |
| `database_backend` | `sqlite` | Storage backend (`sqlite` or `postgres`) |
| `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 |
| `embed_server_auto_start` | `true` | Auto-start embed-server daemon on first CLI query |
| `embed_server_idle_timeout` | `1800` | Daemon auto-shutdown after N seconds idle |

---

(c) 2026 byte5 GmbH -- MIT License

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

palaia

Directory Structure

SKILL.md

Report

Notice