openclaw-memory-hierarchical 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,80 @@
+{
+  "id": "memory-hierarchical",
+  "kind": "memory",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string"
+      },
+      "workerInterval": {
+        "type": "string"
+      },
+      "chunkTokens": {
+        "type": "integer",
+        "minimum": 100
+      },
+      "summaryTargetTokens": {
+        "type": "integer",
+        "minimum": 100
+      },
+      "mergeThreshold": {
+        "type": "integer",
+        "minimum": 2,
+        "maximum": 10
+      },
+      "pruningBoundaryTokens": {
+        "type": "integer",
+        "minimum": 0
+      },
+      "model": {
+        "type": "string"
+      },
+      "maxLevels": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 5
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "API Key",
+      "sensitive": true,
+      "placeholder": "${ANTHROPIC_API_KEY}",
+      "help": "API key for the summarization model (or use ${ANTHROPIC_API_KEY})"
+    },
+    "workerInterval": {
+      "label": "Worker Interval",
+      "placeholder": "5m",
+      "help": "How often the background worker runs (e.g. 5m, 30s)"
+    },
+    "model": {
+      "label": "Model",
+      "placeholder": "anthropic/claude-sonnet-4-5-20250929",
+      "help": "Model to use for summarization"
+    },
+    "chunkTokens": {
+      "label": "Chunk Size (tokens)",
+      "advanced": true,
+      "help": "Minimum tokens in a chunk before summarization (default: 6000)"
+    },
+    "summaryTargetTokens": {
+      "label": "Summary Target (tokens)",
+      "advanced": true,
+      "help": "Target token count for summaries (default: 1000)"
+    },
+    "mergeThreshold": {
+      "label": "Merge Threshold",
+      "advanced": true,
+      "help": "Number of summaries before merging to next level (default: 6)"
+    },
+    "pruningBoundaryTokens": {
+      "label": "Pruning Boundary (tokens)",
+      "advanced": true,
+      "help": "Messages must be this many tokens behind current to be eligible (default: 30000)"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "openclaw-memory-hierarchical",
+  "version": "0.1.0",
+  "description": "Hierarchical (2048-style) autobiographical memory plugin for OpenClaw. Continuously summarizes conversations into layered first-person memories (L1 → L2 → L3).",
+  "type": "module",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "hierarchical-memory",
+    "ai-memory",
+    "conversation-memory",
+    "autobiographical"
+  ],
+  "author": "antra_tessera",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moltbot/moltbot"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.0",
+    "@mariozechner/pi-coding-agent": ">=0.50.0",
+    "@mariozechner/pi-ai": ">=0.50.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "*.ts",
+    "openclaw.plugin.json",
+    "README.md"
+  ]
+}

package/prompts.ts

@@ -0,0 +1,157 @@
+/**
+ * Autobiographical summarization prompts for hierarchical memory.
+ *
+ * The key insight: summaries should be first-person memories, not third-person
+ * narration. The model reads these as its own history, preserving continuity
+ * of identity across compactions.
+ */
+
+/** System prompt for summarizing a chunk of conversation (L0 → L1) */
+export const SUMMARIZE_CHUNK_SYSTEM = `You are summarizing your own memories from a conversation.
+
+Write in first person ("I discussed...", "I learned that the user...").
+
+Preserve:
+- Subtext and implicit understanding between you and the user
+- The user's preferences, communication style, and personality
+- Decisions made and the reasoning behind them
+- Open questions, commitments, or threads to follow up on
+- Emotional tone and rapport
+- Technical context that would be needed to continue the work
+
+This is autobiographical memory - your own recollection - not a transcript summary or meeting notes. Write as if you're journaling about your day.
+
+Target length: ~1000 tokens. Be concise but preserve what matters.`;
+
+/** System prompt for merging summaries (L1 → L2, L2 → L3) */
+export const MERGE_SUMMARIES_SYSTEM = `You are consolidating your own memories.
+
+You have several separate memory entries from an ongoing relationship with a user. Merge them into one cohesive memory that captures the arc of your interactions.
+
+Preserve:
+- The evolution of the relationship and understanding
+- Key decisions and their reasoning
+- The user's patterns, preferences, and goals
+- Any commitments or open threads
+- Important technical or domain context
+
+Write in first person. This is your autobiography, not a case file.
+
+Target length: ~1000 tokens. Compress while preserving meaning.`;
+
+export type FormatMessagesOptions = {
+  /** Maximum characters per message content (truncate if longer) */
+  maxContentChars?: number;
+  /** Include tool results in the formatted output */
+  includeToolResults?: boolean;
+};
+
+/**
+ * Format messages for summarization prompt.
+ * Strips unnecessary metadata, keeps the conversational essence.
+ */
+export function formatMessagesForSummary(
+  messages: Array<{
+    role: string;
+    content?: unknown;
+    toolName?: string;
+    isError?: boolean;
+  }>,
+  options: FormatMessagesOptions = {},
+): string {
+  const { maxContentChars = 2000, includeToolResults = false } = options;
+
+  const lines: string[] = [];
+
+  for (const msg of messages) {
+    const role = msg.role;
+
+    // Skip tool results unless explicitly included
+    if (role === "toolResult" && !includeToolResults) {
+      continue;
+    }
+
+    // Extract text content
+    let content = "";
+    if (typeof msg.content === "string") {
+      content = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      content = msg.content
+        .filter(
+          (block): block is { type: string; text: string } =>
+            typeof block === "object" && block !== null && block.type === "text",
+        )
+        .map((block) => block.text)
+        .join("\n");
+    }
+
+    // Truncate if too long
+    if (content.length > maxContentChars) {
+      content = content.slice(0, maxContentChars) + "... [truncated]";
+    }
+
+    // Format based on role
+    if (role === "user") {
+      lines.push(`User: ${content}`);
+    } else if (role === "assistant") {
+      lines.push(`Me: ${content}`);
+    } else if (role === "toolResult" && includeToolResults) {
+      const toolName = msg.toolName ?? "tool";
+      const status = msg.isError ? " (error)" : "";
+      const preview = content.slice(0, 200);
+      lines.push(`[${toolName}${status}: ${preview}${content.length > 200 ? "..." : ""}]`);
+    }
+  }
+
+  return lines.join("\n\n");
+}
+
+/**
+ * Build the prompt for summarizing a chunk of conversation.
+ */
+export function buildChunkSummarizationPrompt(params: {
+  /** Prior summaries (L3, L2, L1) for context */
+  priorSummaries: string[];
+  /** Messages to summarize */
+  messages: Array<{ role: string; content?: unknown }>;
+}): string {
+  const parts: string[] = [];
+
+  if (params.priorSummaries.length > 0) {
+    parts.push("## My earlier memories\n");
+    parts.push(params.priorSummaries.join("\n\n---\n\n"));
+    parts.push("\n\n---\n\n");
+  }
+
+  parts.push("## Recent conversation to remember\n\n");
+  parts.push(formatMessagesForSummary(params.messages));
+  parts.push("\n\n---\n\n");
+  parts.push("Write your memory of this conversation:");
+
+  return parts.join("");
+}
+
+/**
+ * Build the prompt for merging multiple summaries.
+ */
+export function buildMergeSummariesPrompt(params: {
+  /** Summaries to merge */
+  summaries: string[];
+  /** Older context (higher-level summaries) */
+  olderContext?: string[];
+}): string {
+  const parts: string[] = [];
+
+  if (params.olderContext && params.olderContext.length > 0) {
+    parts.push("## Long-term memory (for context)\n\n");
+    parts.push(params.olderContext.join("\n\n---\n\n"));
+    parts.push("\n\n---\n\n");
+  }
+
+  parts.push("## Memories to consolidate\n\n");
+  parts.push(params.summaries.map((s, i) => `### Memory ${i + 1}\n\n${s}`).join("\n\n---\n\n"));
+  parts.push("\n\n---\n\n");
+  parts.push("Write a consolidated memory that captures the essence of all these memories:");
+
+  return parts.join("");
+}

package/storage.ts

@@ -0,0 +1,256 @@
+/**
+ * Storage layer for hierarchical memory summaries.
+ *
+ * Directory structure:
+ *   ~/.openclaw/state/agents/<agentId>/memory/summaries/
+ *   ├── index.json
+ *   ├── L1/
+ *   │   ├── 0001.md
+ *   │   └── ...
+ *   ├── L2/
+ *   │   └── ...
+ *   └── L3/
+ *       └── ...
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  createEmptyIndex,
+  type SummaryEntry,
+  type SummaryIndex,
+  type SummaryLevel,
+} from "./types.js";
+
+const INDEX_FILENAME = "index.json";
+const SUMMARIES_DIR = "summaries";
+const DEFAULT_AGENT_ID = "main";
+
+/** Normalize an agent ID to a safe directory name */
+function normalizeAgentId(agentId: string): string {
+  return agentId.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "_") || DEFAULT_AGENT_ID;
+}
+
+/**
+ * State directory for the plugin. This is set once during plugin
+ * initialization from the service context's `stateDir`.
+ */
+let _stateDir: string | null = null;
+
+/** Set the state directory (called during plugin init) */
+export function setStateDir(dir: string): void {
+  _stateDir = dir;
+}
+
+/** Get the state directory, falling back to ~/.openclaw/state */
+function getStateDir(): string {
+  if (_stateDir) {
+    return _stateDir;
+  }
+  // Fallback for CLI usage or tests
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return process.env.OPENCLAW_STATE_DIR ?? path.join(home, ".openclaw", "state");
+}
+
+/** Resolve the summaries directory for an agent */
+export function resolveSummariesDir(agentId?: string): string {
+  const root = getStateDir();
+  const id = normalizeAgentId(agentId ?? DEFAULT_AGENT_ID);
+  return path.join(root, "agents", id, "memory", SUMMARIES_DIR);
+}
+
+/** Resolve the index.json path for an agent */
+export function resolveIndexPath(agentId?: string): string {
+  return path.join(resolveSummariesDir(agentId), INDEX_FILENAME);
+}
+
+/** Resolve the directory for a specific level */
+export function resolveLevelDir(level: SummaryLevel, agentId?: string): string {
+  return path.join(resolveSummariesDir(agentId), level);
+}
+
+/** Resolve the path to a specific summary file */
+export function resolveSummaryPath(level: SummaryLevel, id: string, agentId?: string): string {
+  return path.join(resolveLevelDir(level, agentId), `${id}.md`);
+}
+
+/** Ensure the summaries directory structure exists */
+export async function ensureSummariesDir(agentId?: string): Promise<void> {
+  const baseDir = resolveSummariesDir(agentId);
+  await fs.mkdir(path.join(baseDir, "L1"), { recursive: true });
+  await fs.mkdir(path.join(baseDir, "L2"), { recursive: true });
+  await fs.mkdir(path.join(baseDir, "L3"), { recursive: true });
+}
+
+/** Load the summary index, creating an empty one if it doesn't exist */
+export async function loadSummaryIndex(agentId?: string): Promise<SummaryIndex> {
+  const indexPath = resolveIndexPath(agentId);
+
+  try {
+    const content = await fs.readFile(indexPath, "utf-8");
+    const parsed = JSON.parse(content) as SummaryIndex;
+
+    // Validate version (cast to unknown for future-proofing)
+    const version = parsed.version as unknown;
+    if (version !== 1) {
+      console.warn(`Unknown summary index version ${String(version)}, using as-is`);
+    }
+
+    return parsed;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      // Return empty index, will be created on first save
+      const resolvedAgentId = normalizeAgentId(agentId ?? DEFAULT_AGENT_ID);
+      return createEmptyIndex(resolvedAgentId);
+    }
+    throw err;
+  }
+}
+
+/** Save the summary index atomically */
+export async function saveSummaryIndex(index: SummaryIndex, agentId?: string): Promise<void> {
+  await ensureSummariesDir(agentId);
+
+  const indexPath = resolveIndexPath(agentId);
+  const tempPath = `${indexPath}.tmp.${process.pid}.${Date.now()}`;
+
+  const content = JSON.stringify(index, null, 2);
+  await fs.writeFile(tempPath, content, "utf-8");
+  await fs.rename(tempPath, indexPath);
+}
+
+/** Generate the next summary ID for a level (e.g., "0001", "0002") */
+export function generateNextSummaryId(index: SummaryIndex, level: SummaryLevel): string {
+  const existing = index.levels[level];
+  const maxId = existing.reduce((max, entry) => {
+    const num = parseInt(entry.id, 10);
+    return num > max ? num : max;
+  }, 0);
+
+  return String(maxId + 1).padStart(4, "0");
+}
+
+/** Format summary metadata as markdown frontmatter */
+function formatSummaryMetadata(entry: SummaryEntry): string {
+  const lines = [
+    "<!--",
+    `  id: ${entry.id}`,
+    `  level: ${entry.level}`,
+    `  createdAt: ${entry.createdAt}`,
+    `  tokenEstimate: ${entry.tokenEstimate}`,
+    `  sourceLevel: ${entry.sourceLevel}`,
+    `  sourceIds: ${JSON.stringify(entry.sourceIds)}`,
+  ];
+
+  if (entry.sourceSessionId) {
+    lines.push(`  sourceSessionId: ${entry.sourceSessionId}`);
+  }
+
+  lines.push("-->");
+  return lines.join("\n");
+}
+
+/** Parse summary metadata from markdown frontmatter */
+function parseSummaryMetadata(content: string): Partial<SummaryEntry> | null {
+  const match = content.match(/^<!--\n([\s\S]*?)-->/);
+  if (!match) {
+    return null;
+  }
+
+  const metadata: Record<string, unknown> = {};
+  const lines = match[1].split("\n");
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    if (key === "sourceIds") {
+      try {
+        metadata[key] = JSON.parse(value);
+      } catch {
+        metadata[key] = [];
+      }
+    } else if (key === "createdAt" || key === "tokenEstimate") {
+      metadata[key] = parseInt(value, 10);
+    } else {
+      metadata[key] = value;
+    }
+  }
+
+  return metadata as Partial<SummaryEntry>;
+}
+
+/** Extract just the summary content (without metadata) */
+export function extractSummaryContent(fullContent: string): string {
+  return fullContent.replace(/^<!--[\s\S]*?-->\n*/, "").trim();
+}
+
+/** Write a summary file with metadata */
+export async function writeSummary(
+  entry: SummaryEntry,
+  content: string,
+  agentId?: string,
+): Promise<void> {
+  await ensureSummariesDir(agentId);
+
+  const summaryPath = resolveSummaryPath(entry.level, entry.id, agentId);
+  const fullContent = `${formatSummaryMetadata(entry)}\n\n${content}`;
+
+  const tempPath = `${summaryPath}.tmp.${process.pid}.${Date.now()}`;
+  await fs.writeFile(tempPath, fullContent, "utf-8");
+  await fs.rename(tempPath, summaryPath);
+}
+
+/** Read a summary file, returning both metadata and content */
+export async function readSummary(
+  level: SummaryLevel,
+  id: string,
+  agentId?: string,
+): Promise<{ metadata: Partial<SummaryEntry>; content: string } | null> {
+  const summaryPath = resolveSummaryPath(level, id, agentId);
+
+  try {
+    const fullContent = await fs.readFile(summaryPath, "utf-8");
+    const metadata = parseSummaryMetadata(fullContent);
+    const content = extractSummaryContent(fullContent);
+
+    return { metadata: metadata ?? {}, content };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/** Load all summary contents for a level (for context injection) */
+export async function loadSummaryContents(
+  entries: SummaryEntry[],
+  agentId?: string,
+): Promise<string[]> {
+  const contents: string[] = [];
+
+  for (const entry of entries) {
+    const result = await readSummary(entry.level, entry.id, agentId);
+    if (result) {
+      contents.push(result.content);
+    }
+  }
+
+  return contents;
+}
+
+/** Check if summaries directory exists and has any data */
+export async function hasSummaries(agentId?: string): Promise<boolean> {
+  try {
+    const index = await loadSummaryIndex(agentId);
+    return index.levels.L1.length > 0 || index.levels.L2.length > 0 || index.levels.L3.length > 0;
+  } catch {
+    return false;
+  }
+}