@byte5ai/palaia 1.1.0

package/README.md

@@ -0,0 +1,137 @@
+# @byte5ai/palaia
+
+**Palaia memory backend for OpenClaw.**
+
+Replace OpenClaw's built-in `memory-core` with Palaia — local, cloud-free, WAL-backed agent memory with tier routing and semantic search.
+
+## Installation
+
+```bash
+# Install Palaia (Python CLI)
+pip install palaia
+
+# Install the OpenClaw plugin
+openclaw plugins install @byte5ai/palaia
+```
+
+## Configuration
+
+Activate the plugin by setting the memory slot in your OpenClaw config:
+
+```json5
+// openclaw.config.json5
+{
+  plugins: {
+    slots: { memory: "palaia" }
+  }
+}
+```
+
+Restart the gateway after changing config:
+
+```bash
+openclaw gateway restart
+```
+
+### Plugin Options
+
+All options are optional — sensible defaults are used:
+
+```json5
+{
+  plugins: {
+    config: {
+      palaia: {
+        binaryPath: "/path/to/palaia",  // default: auto-detect
+        workspace: "/path/to/workspace", // default: agent workspace
+        tier: "hot",                      // default: "hot" (hot|warm|all)
+        maxResults: 10,                   // default: 10
+        timeoutMs: 3000,                  // default: 3000
+        memoryInject: false,              // default: false (inject HOT into context)
+        maxInjectedChars: 4000,           // default: 4000
+      }
+    }
+  }
+}
+```
+
+## Agent Tools
+
+### `memory_search` (always available)
+
+Semantically search Palaia memory:
+
+```
+memory_search({ query: "deployment process", maxResults: 5, tier: "all" })
+```
+
+### `memory_get` (always available)
+
+Read a specific memory entry:
+
+```
+memory_get({ path: "abc-123-uuid", from: 1, lines: 50 })
+```
+
+### `memory_write` (optional, opt-in)
+
+Write new memory entries. Enable per-agent:
+
+```json5
+{
+  agents: {
+    list: [{
+      id: "main",
+      tools: { allow: ["memory_write"] }
+    }]
+  }
+}
+```
+
+Then agents can write:
+
+```
+memory_write({ content: "Important finding", scope: "team", tags: ["project-x"] })
+```
+
+## Features
+
+- **Zero breaking changes** — Drop-in replacement for `memory-core`
+- **WAL-backed writes** — Crash-safe, recovers on startup
+- **Tier routing** — HOT → WARM → COLD with automatic decay
+- **Scope isolation** — private, team, shared:X, public
+- **BM25 search** — Fast local search, no external API needed
+- **HOT memory injection** — Opt-in: inject active memory into agent context
+- **Auto binary detection** — Finds `palaia` in PATH, pipx, or venv
+
+## Architecture
+
+```
+OpenClaw Agent
+  └─ @byte5ai/palaia (plugin)
+       └─ palaia CLI (subprocess, --json)
+            └─ .palaia/ (local storage)
+                 ├─ hot/    (active memory)
+                 ├─ warm/   (recent, less active)
+                 ├─ cold/   (archived)
+                 ├─ wal/    (write-ahead log)
+                 └─ index/  (search index)
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/iret77/palaia.git
+cd palaia/packages/openclaw-plugin
+
+# Install deps
+npm install
+
+# Run tests
+npx vitest run
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @byte5ai/palaia — Palaia Memory Backend for OpenClaw
+ *
+ * Plugin entry point. Loaded by OpenClaw via jiti (no build step needed).
+ *
+ * Registers:
+ * - memory_search: Semantic search over Palaia memory
+ * - memory_get: Read a specific memory entry
+ * - memory_write: Write new entries (optional, opt-in)
+ * - before_prompt_build: HOT memory injection (opt-in)
+ * - palaia-recovery: WAL replay on startup
+ *
+ * Activation:
+ *   plugins: { slots: { memory: "palaia" } }
+ */
+
+import { resolveConfig, type PalaiaPluginConfig } from "./src/config.js";
+import { registerTools } from "./src/tools.js";
+import { registerHooks } from "./src/hooks.js";
+
+export default function palaiaPlugin(api: any) {
+  const rawConfig = api.getConfig?.("palaia") as
+    | Partial<PalaiaPluginConfig>
+    | undefined;
+  const config = resolveConfig(rawConfig);
+
+  // If workspace not set, use agent workspace from context
+  if (!config.workspace && api.workspace) {
+    config.workspace = api.workspace;
+  }
+
+  // Register agent tools (memory_search, memory_get, memory_write)
+  registerTools(api, config);
+
+  // Register lifecycle hooks (before_prompt_build, recovery service)
+  registerHooks(api, config);
+}

package/openclaw.plugin.json

@@ -0,0 +1,51 @@
+{
+  "id": "palaia",
+  "name": "Palaia Memory",
+  "kind": "memory",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "binaryPath": {
+        "type": "string",
+        "description": "Path to palaia binary (default: auto-detect)"
+      },
+      "workspace": {
+        "type": "string",
+        "description": "Palaia workspace path (default: agent workspace)"
+      },
+      "tier": {
+        "type": "string",
+        "enum": ["hot", "warm", "all"],
+        "default": "hot"
+      },
+      "maxResults": {
+        "type": "number",
+        "default": 10
+      },
+      "timeoutMs": {
+        "type": "number",
+        "default": 3000
+      },
+      "memoryInject": {
+        "type": "boolean",
+        "default": false,
+        "description": "Inject HOT memory into agent context on prompt build"
+      },
+      "maxInjectedChars": {
+        "type": "number",
+        "default": 4000,
+        "description": "Max characters for injected memory context"
+      }
+    }
+  },
+  "uiHints": {
+    "binaryPath": {
+      "label": "Palaia Binary Path",
+      "placeholder": "auto-detect"
+    },
+    "workspace": {
+      "label": "Workspace Path",
+      "placeholder": "agent workspace"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@byte5ai/palaia",
+  "version": "1.1.0",
+  "description": "Palaia memory backend for OpenClaw",
+  "main": "index.ts",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "palaia",
+    "memory",
+    "agent-memory"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iret77/palaia.git",
+    "directory": "packages/openclaw-plugin"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.1.0"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "^0.32.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,37 @@
+/**
+ * Plugin configuration schema and defaults for @byte5ai/palaia.
+ */
+
+export interface PalaiaPluginConfig {
+  /** Path to palaia binary (default: auto-detect) */
+  binaryPath?: string;
+  /** Palaia workspace path (default: agent workspace) */
+  workspace?: string;
+  /** Default tier filter: "hot" | "warm" | "all" */
+  tier: string;
+  /** Default max results for queries */
+  maxResults: number;
+  /** Timeout for CLI calls in milliseconds */
+  timeoutMs: number;
+  /** Inject HOT memory into agent context on prompt build */
+  memoryInject: boolean;
+  /** Max characters for injected memory context */
+  maxInjectedChars: number;
+}
+
+export const DEFAULT_CONFIG: PalaiaPluginConfig = {
+  tier: "hot",
+  maxResults: 10,
+  timeoutMs: 3000,
+  memoryInject: false,
+  maxInjectedChars: 4000,
+};
+
+/**
+ * Merge user config with defaults. Unknown keys are ignored.
+ */
+export function resolveConfig(
+  userConfig: Partial<PalaiaPluginConfig> | undefined
+): PalaiaPluginConfig {
+  return { ...DEFAULT_CONFIG, ...userConfig };
+}

package/src/hooks.ts

@@ -0,0 +1,98 @@
+/**
+ * Lifecycle hooks for the Palaia OpenClaw plugin.
+ *
+ * - before_prompt_build: Injects HOT memory into agent context (opt-in).
+ * - palaia-recovery service: Replays WAL on startup.
+ */
+
+import { runJson, recover, type RunnerOpts } from "./runner.js";
+import type { PalaiaPluginConfig } from "./config.js";
+
+/** Shape returned by `palaia query --json` */
+interface QueryResult {
+  results: Array<{
+    id: string;
+    body?: string;
+    content?: string;
+    score: number;
+    tier: string;
+    scope: string;
+    title?: string;
+  }>;
+}
+
+/**
+ * Build RunnerOpts from plugin config.
+ */
+function buildRunnerOpts(config: PalaiaPluginConfig): RunnerOpts {
+  return {
+    binaryPath: config.binaryPath,
+    workspace: config.workspace,
+    timeoutMs: config.timeoutMs,
+  };
+}
+
+/**
+ * Register lifecycle hooks on the plugin API.
+ */
+export function registerHooks(api: any, config: PalaiaPluginConfig): void {
+  const opts = buildRunnerOpts(config);
+
+  // ── before_prompt_build ────────────────────────────────────────
+  // Injects top HOT entries into agent system context.
+  // Only active when config.memoryInject === true (default: false).
+  if (config.memoryInject) {
+    api.on("before_prompt_build", async (event: any, ctx: any) => {
+      try {
+        const maxChars = config.maxInjectedChars || 4000;
+        const limit = Math.min(config.maxResults || 10, 20);
+
+        const result = await runJson<QueryResult>(
+          ["list", "--tier", "hot", "--limit", String(limit)],
+          opts
+        );
+
+        if (!result || !Array.isArray(result.results) || result.results.length === 0) {
+          // Fallback: try query with empty string for recent entries
+          return;
+        }
+
+        const entries = result.results;
+        let text = "## Active Memory (Palaia)\n\n";
+        let chars = text.length;
+
+        for (const entry of entries) {
+          const body = entry.content || entry.body || "";
+          const title = entry.title || "(untitled)";
+          const line = `**${title}** [${entry.scope}]\n${body}\n\n`;
+
+          if (chars + line.length > maxChars) break;
+          text += line;
+          chars += line.length;
+        }
+
+        if (ctx.prependSystemContext) {
+          ctx.prependSystemContext(text);
+        }
+      } catch (error) {
+        // Non-fatal: if memory injection fails, agent continues without it
+        console.warn(`[palaia] Memory injection failed: ${error}`);
+      }
+    });
+  }
+
+  // ── Startup Recovery Service ───────────────────────────────────
+  // Replays pending WAL entries on plugin startup.
+  api.registerService({
+    id: "palaia-recovery",
+    start: async () => {
+      const result = await recover(opts);
+      if (result.replayed > 0) {
+        console.log(`[palaia] WAL recovery: replayed ${result.replayed} entries`);
+      }
+      if (result.errors > 0) {
+        console.warn(`[palaia] WAL recovery completed with ${result.errors} error(s)`);
+      }
+    },
+  });
+}

package/src/runner.ts

@@ -0,0 +1,218 @@
+/**
+ * Palaia CLI subprocess runner.
+ *
+ * Executes palaia CLI commands, parses JSON output, handles binary detection
+ * and timeouts. This is the bridge between the OpenClaw plugin and the
+ * palaia Python CLI.
+ */
+
+import { execFile } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface RunnerOpts {
+  /** Working directory for palaia (sets PALAIA_ROOT context) */
+  workspace?: string;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+  /** Override binary path */
+  binaryPath?: string;
+}
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Cached binary path after first detection */
+let cachedBinary: string | null = null;
+
+/**
+ * Detect the palaia binary location.
+ *
+ * Search order:
+ * 1. Explicit binaryPath from config
+ * 2. `palaia` in PATH
+ * 3. `~/.local/bin/palaia` (pipx default)
+ * 4. `python3 -m palaia` as fallback
+ * 5. Error with clear message
+ */
+export async function detectBinary(
+  explicitPath?: string
+): Promise<string> {
+  if (explicitPath) {
+    try {
+      await access(explicitPath, constants.X_OK);
+      return explicitPath;
+    } catch {
+      throw new Error(
+        `Configured palaia binary not found or not executable: ${explicitPath}`
+      );
+    }
+  }
+
+  if (cachedBinary) return cachedBinary;
+
+  // Try `palaia` in PATH
+  try {
+    const result = await execCommand("palaia", ["--version"], {
+      timeoutMs: 5000,
+    });
+    if (result.exitCode === 0) {
+      cachedBinary = "palaia";
+      return "palaia";
+    }
+  } catch {
+    // Not in PATH
+  }
+
+  // Try ~/.local/bin/palaia (pipx default)
+  const pipxPath = join(homedir(), ".local", "bin", "palaia");
+  try {
+    await access(pipxPath, constants.X_OK);
+    cachedBinary = pipxPath;
+    return pipxPath;
+  } catch {
+    // Not installed via pipx
+  }
+
+  // Try python3 -m palaia
+  try {
+    const result = await execCommand("python3", ["-m", "palaia", "--version"], {
+      timeoutMs: 5000,
+    });
+    if (result.exitCode === 0) {
+      cachedBinary = "python3";
+      return "python3"; // Will need `-m palaia` prefix
+    }
+  } catch {
+    // Not available
+  }
+
+  throw new Error(
+    "Palaia binary not found. Install with: pip install palaia\n" +
+      "Or set binaryPath in plugin config."
+  );
+}
+
+/**
+ * Check if the detected binary requires `python3 -m palaia` invocation.
+ */
+function isPythonModule(binary: string): boolean {
+  return binary === "python3" || binary.endsWith("/python3");
+}
+
+/**
+ * Execute a raw command and return result.
+ */
+function execCommand(
+  cmd: string,
+  args: string[],
+  opts: { timeoutMs?: number; cwd?: string } = {}
+): Promise<RunResult> {
+  return new Promise((resolve, reject) => {
+    const timeout = opts.timeoutMs || 10000;
+    const child = execFile(
+      cmd,
+      args,
+      {
+        timeout,
+        maxBuffer: 1024 * 1024, // 1MB
+        cwd: opts.cwd,
+        env: { ...process.env },
+      },
+      (error, stdout, stderr) => {
+        if (error && (error as any).killed) {
+          reject(
+            new Error(`Palaia command timed out after ${timeout}ms: ${cmd} ${args.join(" ")}`)
+          );
+          return;
+        }
+        resolve({
+          stdout: stdout?.toString() || "",
+          stderr: stderr?.toString() || "",
+          exitCode: error ? (error as any).code || 1 : 0,
+        });
+      }
+    );
+  });
+}
+
+/**
+ * Run a palaia CLI command and return raw output.
+ */
+export async function run(
+  args: string[],
+  opts: RunnerOpts = {}
+): Promise<string> {
+  const binary = await detectBinary(opts.binaryPath);
+  const timeoutMs = opts.timeoutMs || 3000;
+
+  let cmd: string;
+  let cmdArgs: string[];
+
+  if (isPythonModule(binary)) {
+    cmd = binary;
+    cmdArgs = ["-m", "palaia", ...args];
+  } else {
+    cmd = binary;
+    cmdArgs = [...args];
+  }
+
+  const result = await execCommand(cmd, cmdArgs, {
+    timeoutMs,
+    cwd: opts.workspace,
+  });
+
+  if (result.exitCode !== 0) {
+    const errMsg = result.stderr.trim() || result.stdout.trim();
+    throw new Error(`Palaia CLI error (exit ${result.exitCode}): ${errMsg}`);
+  }
+
+  return result.stdout;
+}
+
+/**
+ * Run a palaia CLI command and parse JSON output.
+ */
+export async function runJson<T = unknown>(
+  args: string[],
+  opts: RunnerOpts = {}
+): Promise<T> {
+  const stdout = await run([...args, "--json"], opts);
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    throw new Error(
+      `Failed to parse palaia JSON output: ${stdout.slice(0, 200)}`
+    );
+  }
+}
+
+/**
+ * Run WAL recovery on startup.
+ */
+export async function recover(opts: RunnerOpts = {}): Promise<{
+  replayed: number;
+  errors: number;
+}> {
+  try {
+    return await runJson<{ replayed: number; errors: number }>(
+      ["recover"],
+      { ...opts, timeoutMs: opts.timeoutMs || 10000 }
+    );
+  } catch (error) {
+    // Recovery failure is non-fatal — log and continue
+    console.warn(`[palaia] WAL recovery warning: ${error}`);
+    return { replayed: 0, errors: 1 };
+  }
+}
+
+/**
+ * Reset cached binary (for testing).
+ */
+export function resetCache(): void {
+  cachedBinary = null;
+}

package/src/tools.ts

@@ -0,0 +1,220 @@
+/**
+ * Agent tools: memory_search, memory_get, memory_write.
+ *
+ * These tools are the core of the Palaia OpenClaw integration.
+ * They shell out to the palaia CLI with --json and return results
+ * in the format OpenClaw agents expect.
+ */
+
+import { Type } from "@sinclair/typebox";
+import { runJson, type RunnerOpts } from "./runner.js";
+import type { PalaiaPluginConfig } from "./config.js";
+
+/** Shape returned by `palaia query --json` */
+interface QueryResult {
+  results: Array<{
+    id: string;
+    content?: string;
+    body?: string;
+    score: number;
+    tier: string;
+    scope: string;
+    title?: string;
+    tags?: string[];
+    path?: string;
+    decay_score?: number;
+  }>;
+}
+
+/** Shape returned by `palaia get --json` */
+interface GetResult {
+  id: string;
+  content: string;
+  meta: {
+    scope: string;
+    tier: string;
+    title?: string;
+    tags?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/** Shape returned by `palaia write --json` */
+interface WriteResult {
+  id: string;
+  tier: string;
+  scope: string;
+  deduplicated: boolean;
+}
+
+/**
+ * Build RunnerOpts from plugin config.
+ */
+function buildRunnerOpts(config: PalaiaPluginConfig): RunnerOpts {
+  return {
+    binaryPath: config.binaryPath,
+    workspace: config.workspace,
+    timeoutMs: config.timeoutMs,
+  };
+}
+
+/**
+ * Register all Palaia agent tools on the given plugin API.
+ */
+export function registerTools(api: any, config: PalaiaPluginConfig): void {
+  const opts = buildRunnerOpts(config);
+
+  // ── memory_search ──────────────────────────────────────────────
+  api.registerTool({
+    name: "memory_search",
+    description:
+      "Semantically search Palaia memory for relevant notes and context.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+      maxResults: Type.Optional(
+        Type.Number({ description: "Max results (default: 5)", default: 5 })
+      ),
+      tier: Type.Optional(
+        Type.String({
+          description: "hot|warm|all (default: hot+warm)",
+        })
+      ),
+      scope: Type.Optional(
+        Type.String({
+          description: "Filter by scope: private|team|shared:X|public",
+        })
+      ),
+    }),
+    async execute(
+      _id: string,
+      params: {
+        query: string;
+        maxResults?: number;
+        tier?: string;
+        scope?: string;
+      }
+    ) {
+      const limit = params.maxResults || config.maxResults || 5;
+      const args: string[] = ["query", params.query, "--limit", String(limit)];
+
+      // --all flag includes cold tier
+      if (params.tier === "all" || config.tier === "all") {
+        args.push("--all");
+      }
+
+      const result = await runJson<QueryResult>(args, opts);
+
+      // Format as memory_search compatible output
+      const snippets = (result.results || []).map((r) => {
+        const body = r.content || r.body || "";
+        const path = r.path || `${r.tier}/${r.id}.md`;
+        return {
+          text: body,
+          path,
+          score: r.score,
+          tier: r.tier,
+          scope: r.scope,
+        };
+      });
+
+      // Build text output compatible with memory-core format
+      const textParts = snippets.map(
+        (s) =>
+          `${s.text}\n— Source: ${s.path} (score: ${s.score}, tier: ${s.tier})`
+      );
+      const text =
+        textParts.length > 0
+          ? textParts.join("\n\n")
+          : "No results found.";
+
+      return {
+        content: [{ type: "text" as const, text }],
+      };
+    },
+  });
+
+  // ── memory_get ─────────────────────────────────────────────────
+  api.registerTool({
+    name: "memory_get",
+    description: "Read a specific Palaia memory entry by path or id.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Memory path or UUID" }),
+      from: Type.Optional(
+        Type.Number({ description: "Start from line number (1-indexed)" })
+      ),
+      lines: Type.Optional(
+        Type.Number({ description: "Number of lines to return" })
+      ),
+    }),
+    async execute(
+      _id: string,
+      params: { path: string; from?: number; lines?: number }
+    ) {
+      const args: string[] = ["get", params.path];
+      if (params.from != null) {
+        args.push("--from", String(params.from));
+      }
+      if (params.lines != null) {
+        args.push("--lines", String(params.lines));
+      }
+
+      const result = await runJson<GetResult>(args, opts);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: result.content,
+          },
+        ],
+      };
+    },
+  });
+
+  // ── memory_write (optional, opt-in) ───────────────────────────
+  api.registerTool(
+    {
+      name: "memory_write",
+      description:
+        "Write a new memory entry to Palaia. WAL-backed, crash-safe.",
+      parameters: Type.Object({
+        content: Type.String({ description: "Memory content to write" }),
+        scope: Type.Optional(
+          Type.String({
+            description: "Scope: private|team|shared:X|public (default: team)",
+            default: "team",
+          })
+        ),
+        tags: Type.Optional(
+          Type.Array(Type.String(), {
+            description: "Tags for categorization",
+          })
+        ),
+      }),
+      async execute(
+        _id: string,
+        params: { content: string; scope?: string; tags?: string[] }
+      ) {
+        const args: string[] = ["write", params.content];
+        if (params.scope) {
+          args.push("--scope", params.scope);
+        }
+        if (params.tags && params.tags.length > 0) {
+          args.push("--tags", params.tags.join(","));
+        }
+
+        const result = await runJson<WriteResult>(args, opts);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Memory written: ${result.id} (tier: ${result.tier}, scope: ${result.scope})`,
+            },
+          ],
+        };
+      },
+    },
+    { optional: true }
+  );
+}