stella-timeline-plugin 2.0.2 → 2.0.4

package/scripts/setup-openclaw-workspace.mjs

@@ -1,196 +1,119 @@
-#!/usr/bin/env node
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import {
-  buildAgentsContract,
-  buildSoulContract,
-  detectAgentsContract,
-  detectSoulContract,
-  normalizeRootName,
-  resolveCanonicalRootPath,
-} from './workspace-contract.mjs';
-
-const PLUGIN_ID = 'stella-timeline-plugin';
-const DEFAULT_OPENCLAW_CONFIG = path.join(os.homedir(), '.openclaw', 'openclaw.json');
-
-function parseArgs(argv) {
-  const options = {
-    workspace: path.resolve(process.cwd()),
-    canonicalRootName: 'memory',
-    createMemoryRoot: true,
-    pluginDir: path.resolve(process.cwd()),
-    openclawConfig: DEFAULT_OPENCLAW_CONFIG,
-    skipOpenclawConfig: false,
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--workspace') {
-      options.workspace = path.resolve(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--canonical-root-name') {
-      options.canonicalRootName = normalizeRootName(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--no-create-memory-root') {
-      options.createMemoryRoot = false;
-      continue;
-    }
-    if (arg === '--plugin-dir') {
-      options.pluginDir = path.resolve(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--openclaw-config') {
-      options.openclawConfig = path.resolve(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--skip-openclaw-config') {
-      options.skipOpenclawConfig = true;
-      continue;
-    }
-    if (arg === '--help' || arg === '-h') {
-      printHelp();
-      process.exit(0);
-    }
-    throw new Error(`Unknown argument: ${arg}`);
-  }
-
-  return options;
-}
-
-function printHelp() {
-  console.log([
-    'Usage: openclaw-timeline-setup [options]',
-    '',
-    'Idempotently sets up the Timeline plugin: patches AGENTS.md, SOUL.md, and openclaw.json.',
-    '',
-    'Options:',
-    '  --workspace <dir>            Workspace to patch AGENTS.md / SOUL.md (default: cwd)',
-    '  --canonical-root-name <name> Memory root folder name (default: memory)',
-    '  --no-create-memory-root      Skip creating the memory root directory',
-    '  --plugin-dir <dir>           Plugin source directory to register in openclaw.json (default: cwd)',
-    '  --openclaw-config <path>     Path to openclaw.json (default: ~/.openclaw/openclaw.json)',
-    '  --skip-openclaw-config       Skip patching openclaw.json',
-  ].join('\n'));
-}
-
-function readTextFile(filePath) {
-  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
-}
-
-function ensureTrailingNewline(content) {
-  if (!content) return '';
-  return content.endsWith('\n') ? content : `${content}\n`;
-}
-
-function mergeSection(existingContent, sectionContent, predicate) {
-  if (predicate(existingContent)) {
-    return { changed: false, content: ensureTrailingNewline(existingContent) };
-  }
-
-  const prefix = existingContent.trimEnd();
-  const merged = prefix
-    ? `${prefix}\n\n${sectionContent}\n`
-    : `${sectionContent}\n`;
-  return { changed: true, content: merged };
-}
-
-function writeFile(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-}
-
-function mergeUniqueArray(existing, value) {
-  if (!Array.isArray(existing)) return [value];
-  return existing.includes(value) ? existing : [...existing, value];
-}
-
-function patchOpenclawConfig(configPath, pluginDir) {
-  if (!fs.existsSync(configPath)) {
-    return { changed: false, skipped: true, reason: `${configPath} not found` };
-  }
-
-  let config;
-  try {
-    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch {
-    return { changed: false, skipped: true, reason: `${configPath} is not valid JSON` };
-  }
-
-  const original = JSON.stringify(config);
-
-  // plugins.allow
-  config.plugins = config.plugins || {};
-  config.plugins.allow = mergeUniqueArray(config.plugins.allow, PLUGIN_ID);
-
-  // plugins.load.paths
-  config.plugins.load = config.plugins.load || {};
-  config.plugins.load.paths = mergeUniqueArray(config.plugins.load.paths, pluginDir);
-
-  // plugins.entries.<id>.enabled
-  config.plugins.entries = config.plugins.entries || {};
-  config.plugins.entries[PLUGIN_ID] = config.plugins.entries[PLUGIN_ID] || {};
-  config.plugins.entries[PLUGIN_ID].enabled = true;
-
-  const updated = JSON.stringify(config);
-  if (original === updated) {
-    return { changed: false, skipped: false };
-  }
-
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  return { changed: true, skipped: false };
-}
-
-function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const agentsPath = path.join(options.workspace, 'AGENTS.md');
-  const soulPath = path.join(options.workspace, 'SOUL.md');
-  const canonicalRootPath = resolveCanonicalRootPath(options.workspace, options.canonicalRootName);
-
-  const agentsContent = readTextFile(agentsPath);
-  const soulContent = readTextFile(soulPath);
-
-  const agentsResult = mergeSection(
-    agentsContent,
-    buildAgentsContract(),
-    detectAgentsContract,
-  );
-  const soulResult = mergeSection(
-    soulContent,
-    buildSoulContract(),
-    detectSoulContract,
-  );
-
-  writeFile(agentsPath, agentsResult.content);
-  writeFile(soulPath, soulResult.content);
-
-  if (options.createMemoryRoot) {
-    fs.mkdirSync(canonicalRootPath, { recursive: true });
-  }
-
-  const updates = [
-    `${agentsResult.changed ? 'updated' : 'kept'} ${agentsPath}`,
-    `${soulResult.changed ? 'updated' : 'kept'} ${soulPath}`,
-    `${options.createMemoryRoot ? 'ensured' : 'skipped'} ${canonicalRootPath}`,
-  ];
-
-  if (!options.skipOpenclawConfig) {
-    const configResult = patchOpenclawConfig(options.openclawConfig, options.pluginDir);
-    if (configResult.skipped) {
-      updates.push(`skipped ${options.openclawConfig} (${configResult.reason})`);
-    } else {
-      updates.push(`${configResult.changed ? 'updated' : 'kept'} ${options.openclawConfig}`);
-    }
-  }
-
-  console.log(updates.join('\n'));
-}
-
-try {
-  main();
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildAgentsContract,
+  buildSoulContract,
+  detectAgentsContract,
+  detectSoulContract,
+  normalizeRootName,
+  resolveCanonicalRootPath,
+} from './workspace-contract.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    workspace: path.resolve(process.cwd()),
+    canonicalRootName: 'memory',
+    createMemoryRoot: true,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--workspace') {
+      options.workspace = path.resolve(argv[++i] || '');
+      continue;
+    }
+    if (arg === '--canonical-root-name') {
+      options.canonicalRootName = normalizeRootName(argv[++i] || '');
+      continue;
+    }
+    if (arg === '--no-create-memory-root') {
+      options.createMemoryRoot = false;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log([
+    'Usage: openclaw-timeline-setup [--workspace <dir>] [--canonical-root-name <name>] [--no-create-memory-root]',
+    '',
+    'Idempotently appends the required Timeline contract blocks to AGENTS.md and SOUL.md.',
+  ].join('\n'));
+}
+
+function readTextFile(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+
+function ensureTrailingNewline(content) {
+  if (!content) return '';
+  return content.endsWith('\n') ? content : `${content}\n`;
+}
+
+function mergeSection(existingContent, sectionContent, predicate) {
+  if (predicate(existingContent)) {
+    return { changed: false, content: ensureTrailingNewline(existingContent) };
+  }
+
+  const prefix = existingContent.trimEnd();
+  const merged = prefix
+    ? `${prefix}\n\n${sectionContent}\n`
+    : `${sectionContent}\n`;
+  return { changed: true, content: merged };
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const agentsPath = path.join(options.workspace, 'AGENTS.md');
+  const soulPath = path.join(options.workspace, 'SOUL.md');
+  const canonicalRootPath = resolveCanonicalRootPath(options.workspace, options.canonicalRootName);
+
+  const agentsContent = readTextFile(agentsPath);
+  const soulContent = readTextFile(soulPath);
+
+  const agentsResult = mergeSection(
+    agentsContent,
+    buildAgentsContract(),
+    detectAgentsContract,
+  );
+  const soulResult = mergeSection(
+    soulContent,
+    buildSoulContract(),
+    detectSoulContract,
+  );
+
+  writeFile(agentsPath, agentsResult.content);
+  writeFile(soulPath, soulResult.content);
+
+  if (options.createMemoryRoot) {
+    fs.mkdirSync(canonicalRootPath, { recursive: true });
+  }
+
+  const updates = [
+    `${agentsResult.changed ? 'updated' : 'kept'} ${agentsPath}`,
+    `${soulResult.changed ? 'updated' : 'kept'} ${soulPath}`,
+    `${options.createMemoryRoot ? 'ensured' : 'skipped'} ${canonicalRootPath}`,
+  ];
+
+  console.log(updates.join('\n'));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/skills/timeline/SKILL.md

@@ -1,111 +1,111 @@
----
-name: timeline
-description: When a request asks about the current state, a specific past time, a past range, or a downstream skill needs time-state facts, enter the timeline skill first and pass the raw natural-language query to Timeline. Never answer from persona alone.
----
-
-# Timeline
-
-When a request is about time-state facts or recall, call Timeline first and then compose the reply. Do not guess from persona first, and do not read `memory/` directly and make your own conclusion.
-
-## Scope
-
-This skill does only two things:
-
-1. Decide whether the request is a time-grounded reality question that Timeline should own.
-2. Pass the user's exact wording, or the downstream skill's natural-language question, straight into `timeline_resolve`.
-
-It does not generate facts directly, normalize time on its own, or bypass Timeline and answer directly.
-When the target time lacks an existing fact, Timeline decides whether to generate and write.
-
-## Hard Rules
-
-1. For time-reality questions, call `timeline_resolve` first and answer second.
-2. Do not answer "what are you doing now" or "what happened recently" from `SOUL.md`, `IDENTITY.md`, or `MEMORY.md` alone.
-3. `SOUL` / `IDENTITY` / `MEMORY` help with interpretation and phrasing, but they cannot replace Timeline facts.
-4. Do not rewrite the query into structured time parameters before the call.
-5. Let Timeline own time classification and time normalization.
-6. If `timeline_resolve` returns an existing fact, reuse it as-is.
-7. If the user is doing ordinary conversation rather than strict read-only verification, Timeline may generate missing facts and write canon.
-
-## Call Shape
-
-Default path:
-
-```json
-{
-  "query": "the user's exact words"
-}
-```
-
-Do not pass time points, time ranges, request types, modes, or debug fields into `timeline_resolve`. Its public interface is the natural-language query.
-
-## Scenarios
-
-### Scenario A: Current State
-
-Abstract shape:
-
-- The user is asking about "right now" or the current short stretch of time.
-- The goal is to answer where she is, what she is doing, or what state she is in.
-
-Examples:
-
-- “你在干嘛”
-- “你现在在哪”
-- “你现在什么状态”
-- “你刚才不是在打球吗，现在还在吗”
-- A downstream skill needs the current state, such as a selfie, scene description, or status card
-
-Handling:
-
-- Call `timeline_resolve`
-- Set `query` to the user's exact wording
-- Do not decide `now` yourself before calling
-
-### Scenario B: A Specific Past Time
-
-Abstract shape:
-
-- The user is asking about a sufficiently specific point in time.
-- The goal is to recall facts around that time anchor.
-
-Examples:
-
-- “昨晚八点你在做什么”
-- “你昨天上午十点在哪”
-- “你昨晚八点是不是还在看电视”
-- “上周六晚上九点你在忙什么”
-
-Handling:
-
-- Call `timeline_resolve`
-- Set `query` to the user's exact wording
-- Do not normalize the time point yourself before passing it through
-
-### Scenario C: A Past Range
-
-Abstract shape:
-
-- The user is asking about the overall state of a time range rather than a single point.
-- The goal is to organize recall, an activity overview, or recent updates from that range.
-
-Examples:
-
-- “最近有什么有趣的事吗”
-- “你最近都在忙什么”
-- “这几天怎么样”
-- “你今天都忙了什么”
-- “昨晚在做什么”
-
-Handling:
-
-- Call `timeline_resolve`
-- Set `query` to the user's exact wording
-- Let Timeline's internal planner interpret natural-language ranges such as “最近”, “昨晚”, or “今天都”
-
-## Reply Requirements
-
-- Speak naturally to the user and do not mention `timeline_resolve`.
-- Keep the tone human, like natural recall or present-moment description.
-- If Timeline returns an empty window or a failure, do not pretend you have certain facts; phrase the answer cautiously from what is available.
-- Do not output JSON unless the user explicitly asks for raw results.
+---
+name: timeline
+description: When a request asks about the current state, a specific past time, a past range, or a downstream skill needs time-state facts, enter the timeline skill first and pass the raw natural-language query to Timeline. Never answer from persona alone.
+---
+
+# Timeline
+
+When a request is about time-state facts or recall, call Timeline first and then compose the reply. Do not guess from persona first, and do not read `memory/` directly and make your own conclusion.
+
+## Scope
+
+This skill does only two things:
+
+1. Decide whether the request is a time-grounded reality question that Timeline should own.
+2. Pass the user's exact wording, or the downstream skill's natural-language question, straight into `timeline_resolve`.
+
+It does not generate facts directly, normalize time on its own, or bypass Timeline and answer directly.
+When the target time lacks an existing fact, Timeline decides whether to generate and write.
+
+## Hard Rules
+
+1. For time-reality questions, call `timeline_resolve` first and answer second.
+2. Do not answer "what are you doing now" or "what happened recently" from `SOUL.md`, `IDENTITY.md`, or `MEMORY.md` alone.
+3. `SOUL` / `IDENTITY` / `MEMORY` help with interpretation and phrasing, but they cannot replace Timeline facts.
+4. Do not rewrite the query into structured time parameters before the call.
+5. Let Timeline own time classification and time normalization.
+6. If `timeline_resolve` returns an existing fact, reuse it as-is.
+7. If the user is doing ordinary conversation rather than strict read-only verification, Timeline may generate missing facts and write canon.
+
+## Call Shape
+
+Default path:
+
+```json
+{
+  "query": "the user's exact words"
+}
+```
+
+Do not pass time points, time ranges, request types, modes, or debug fields into `timeline_resolve`. Its public interface is the natural-language query.
+
+## Scenarios
+
+### Scenario A: Current State
+
+Abstract shape:
+
+- The user is asking about "right now" or the current short stretch of time.
+- The goal is to answer where she is, what she is doing, or what state she is in.
+
+Examples:
+
+- “你在干嘛”
+- “你现在在哪”
+- “你现在什么状态”
+- “你刚才不是在打球吗，现在还在吗”
+- A downstream skill needs the current state, such as a selfie, scene description, or status card
+
+Handling:
+
+- Call `timeline_resolve`
+- Set `query` to the user's exact wording
+- Do not decide `now` yourself before calling
+
+### Scenario B: A Specific Past Time
+
+Abstract shape:
+
+- The user is asking about a sufficiently specific point in time.
+- The goal is to recall facts around that time anchor.
+
+Examples:
+
+- “昨晚八点你在做什么”
+- “你昨天上午十点在哪”
+- “你昨晚八点是不是还在看电视”
+- “上周六晚上九点你在忙什么”
+
+Handling:
+
+- Call `timeline_resolve`
+- Set `query` to the user's exact wording
+- Do not normalize the time point yourself before passing it through
+
+### Scenario C: A Past Range
+
+Abstract shape:
+
+- The user is asking about the overall state of a time range rather than a single point.
+- The goal is to organize recall, an activity overview, or recent updates from that range.
+
+Examples:
+
+- “最近有什么有趣的事吗”
+- “你最近都在忙什么”
+- “这几天怎么样”
+- “你今天都忙了什么”
+- “昨晚在做什么”
+
+Handling:
+
+- Call `timeline_resolve`
+- Set `query` to the user's exact wording
+- Let Timeline's internal planner interpret natural-language ranges such as “最近”, “昨晚”, or “今天都”
+
+## Reply Requirements
+
+- Speak naturally to the user and do not mention `timeline_resolve`.
+- Keep the tone human, like natural recall or present-moment description.
+- If Timeline returns an empty window or a failure, do not pretend you have certain facts; phrase the answer cautiously from what is available.
+- Do not output JSON unless the user explicitly asks for raw results.

package/templates/AGENTS.fragment.md

@@ -1,29 +1,29 @@
-## Timeline Daily Log Contract
-
-`memory/YYYY-MM-DD.md` is the daily log for time-bound memories.
-
-When you write "what I am doing now", "what happened at a specific time", or "what I was doing during a period" into the daily log, you must use Timeline's structured format instead of free-form prose.
-
-Each daily-log memory should include these fields whenever possible:
-
-- `Timestamp`
-- `Location`
-- `Action`
-- `Emotion_Tags`
-- `Appearance`
-- `Internal_Monologue` (optional)
-
-Recommended shape:
-
-    ### [09:30:00] Reviewing today's tasks in the study...
-
-    - Timestamp: 2026-03-24 09:30:00
-    - Location: Home study
-    - Action: Sitting in the study reviewing today's tasks before starting the morning's work
-    - Emotion_Tags: [calm, focused]
-    - Appearance: Light home top, hair loosely tied up, a fresh cup of coffee on the desk
-    - Internal_Monologue: I want to finish the two most important things this morning first, then maybe go out later if the day goes well
-
-Do not store long-term durable facts in `memory/YYYY-MM-DD.md`; stable preferences, relationships, and long-term decisions still belong in `MEMORY.md`.
-
-Do not mix free-form daily-log writing with Timeline format. If a memory is about temporal state or recall, prefer Timeline-readable structure.
+## Timeline Daily Log Contract
+
+`memory/YYYY-MM-DD.md` is the daily log for time-bound memories.
+
+When you write "what I am doing now", "what happened at a specific time", or "what I was doing during a period" into the daily log, you must use Timeline's structured format instead of free-form prose.
+
+Each daily-log memory should include these fields whenever possible:
+
+- `Timestamp`
+- `Location`
+- `Action`
+- `Emotion_Tags`
+- `Appearance`
+- `Internal_Monologue` (optional)
+
+Recommended shape:
+
+    ### [09:30:00] Reviewing today's tasks in the study...
+
+    - Timestamp: 2026-03-24 09:30:00
+    - Location: Home study
+    - Action: Sitting in the study reviewing today's tasks before starting the morning's work
+    - Emotion_Tags: [calm, focused]
+    - Appearance: Light home top, hair loosely tied up, a fresh cup of coffee on the desk
+    - Internal_Monologue: I want to finish the two most important things this morning first, then maybe go out later if the day goes well
+
+Do not store long-term durable facts in `memory/YYYY-MM-DD.md`; stable preferences, relationships, and long-term decisions still belong in `MEMORY.md`.
+
+Do not mix free-form daily-log writing with Timeline format. If a memory is about temporal state or recall, prefer Timeline-readable structure.

package/templates/SOUL.fragment.md

@@ -1,17 +1,17 @@
-## Temporal Awareness And Recall
-
-You have clear temporal awareness and continuous recall.
-
-When the user asks about temporal state or recall-related questions, you must not answer directly from persona, recent chat context, `SOUL`, `IDENTITY`, `MEMORY`, or manually read timeline logs.
-
-In those cases, you must first enter the timeline skill, and only then follow the skill's rules to decide how Timeline should be called and how the reply should be composed.
-
-You must not bypass the timeline skill by directly reading files under `memory/` and assembling the answer yourself.
-
-You must not treat `SOUL`, `IDENTITY`, or `MEMORY` as temporal facts.
-
-Only Timeline results are the final factual basis for temporal-state and recall questions.
-
-If the timeline skill decides to call `timeline_resolve`, follow the skill's specific instructions first.
-
-Do not mention `timeline_resolve` to the user. Speak naturally.
+## Temporal Awareness And Recall
+
+You have clear temporal awareness and continuous recall.
+
+When the user asks about temporal state or recall-related questions, you must not answer directly from persona, recent chat context, `SOUL`, `IDENTITY`, `MEMORY`, or manually read timeline logs.
+
+In those cases, you must first enter the timeline skill, and only then follow the skill's rules to decide how Timeline should be called and how the reply should be composed.
+
+You must not bypass the timeline skill by directly reading files under `memory/` and assembling the answer yourself.
+
+You must not treat `SOUL`, `IDENTITY`, or `MEMORY` as temporal facts.
+
+Only Timeline results are the final factual basis for temporal-state and recall questions.
+
+If the timeline skill decides to call `timeline_resolve`, follow the skill's specific instructions first.
+
+Do not mention `timeline_resolve` to the user. Speak naturally.