@bamdra/bamdra-openclaw-memory 0.3.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/openclaw.plugin.json

@@ -0,0 +1,29 @@
+{
+  "id": "bamdra-openclaw-memory",
+  "type": "context-engine",
+  "kind": "memory",
+  "slot": "memory",
+  "capabilities": [
+    "memory"
+  ],
+  "skills": [
+    "./skills"
+  ],
+  "name": "Bamdra OpenClaw Memory",
+  "description": "Unified topic-aware memory plugin for OpenClaw",
+  "version": "0.3.0",
+  "main": "./index.js",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Bamdra Memory"
+    },
+    "store.path": {
+      "label": "SQLite Path",
+      "placeholder": "~/.openclaw/memory/main.sqlite"
+    }
+  }
+}

package/dist/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@bamdra/bamdra-openclaw-memory",
+  "version": "0.3.0",
+  "description": "Unified topic-aware memory plugin for OpenClaw with durable SQLite recall and bounded context growth.",
+  "license": "MIT",
+  "homepage": "https://www.bamdra.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bamdra/openclaw-topic-memory.git",
+    "directory": "bamdra-memory/plugins/bamdra-memory"
+  },
+  "bugs": {
+    "url": "https://github.com/bamdra/openclaw-topic-memory/issues"
+  },
+  "type": "commonjs",
+  "main": "./index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "skills"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "topic-memory",
+    "sqlite",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "bundle": "node ../../scripts/run-local-bin.mjs tsup && cp ../../packages/memory-sqlite/src/schema.sql ./dist/ && node ../../scripts/prepare-plugin-dist.mjs bamdra-openclaw-memory",
+    "prepublishOnly": "pnpm run bundle"
+  },
+  "openclaw": {
+    "id": "bamdra-openclaw-memory",
+    "type": "context-engine",
+    "slot": "memory",
+    "capabilities": [
+      "memory"
+    ],
+    "manifest": "./openclaw.plugin.json",
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.5.2"
+  }
+}

package/dist/schema.sql

@@ -0,0 +1,108 @@
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  turn_id TEXT NOT NULL,
+  parent_turn_id TEXT,
+  role TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  text TEXT NOT NULL,
+  ts TEXT NOT NULL,
+  raw_json TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_session_ts
+  ON messages (session_id, ts);
+
+CREATE TABLE IF NOT EXISTS topics (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  status TEXT NOT NULL,
+  parent_topic_id TEXT,
+  summary_short TEXT NOT NULL DEFAULT '',
+  summary_long TEXT NOT NULL DEFAULT '',
+  open_loops_json TEXT NOT NULL DEFAULT '[]',
+  labels_json TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL,
+  last_active_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_topics_session_last_active
+  ON topics (session_id, last_active_at DESC);
+
+CREATE TABLE IF NOT EXISTS topic_membership (
+  message_id TEXT NOT NULL,
+  topic_id TEXT NOT NULL,
+  score REAL NOT NULL,
+  is_primary INTEGER NOT NULL,
+  reason TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (message_id, topic_id),
+  FOREIGN KEY (message_id) REFERENCES messages(id) ON DELETE CASCADE,
+  FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_topic_membership_topic
+  ON topic_membership (topic_id, created_at);
+
+CREATE TABLE IF NOT EXISTS facts (
+  id TEXT PRIMARY KEY,
+  scope TEXT NOT NULL,
+  category TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  sensitivity TEXT NOT NULL,
+  recall_policy TEXT NOT NULL,
+  confidence REAL NOT NULL,
+  source_message_id TEXT,
+  source_topic_id TEXT,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (source_message_id) REFERENCES messages(id) ON DELETE SET NULL,
+  FOREIGN KEY (source_topic_id) REFERENCES topics(id) ON DELETE SET NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_facts_scope_key
+  ON facts (scope, key);
+
+CREATE TABLE IF NOT EXISTS fact_tags (
+  fact_id TEXT NOT NULL,
+  tag TEXT NOT NULL,
+  PRIMARY KEY (fact_id, tag),
+  FOREIGN KEY (fact_id) REFERENCES facts(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_fact_tags_tag
+  ON fact_tags (tag);
+
+CREATE TABLE IF NOT EXISTS context_snapshots (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  topic_id TEXT,
+  kind TEXT NOT NULL,
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_context_snapshots_session_kind
+  ON context_snapshots (session_id, kind, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS session_state (
+  session_id TEXT PRIMARY KEY,
+  active_topic_id TEXT,
+  last_compacted_at TEXT,
+  last_turn_id TEXT,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (active_topic_id) REFERENCES topics(id) ON DELETE SET NULL
+);
+
+INSERT OR IGNORE INTO schema_migrations (version, applied_at)
+VALUES (1, CURRENT_TIMESTAMP);

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "bamdra-openclaw-memory",
+  "type": "context-engine",
+  "kind": "memory",
+  "slot": "memory",
+  "capabilities": ["memory"],
+  "skills": ["./skills"],
+  "name": "Bamdra OpenClaw Memory",
+  "description": "Unified topic-aware memory plugin for OpenClaw",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Bamdra Memory"
+    },
+    "store.path": {
+      "label": "SQLite Path",
+      "placeholder": "~/.openclaw/memory/main.sqlite"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@bamdra/bamdra-openclaw-memory",
+  "version": "0.3.0",
+  "description": "Unified topic-aware memory plugin for OpenClaw with durable SQLite recall and bounded context growth.",
+  "license": "MIT",
+  "homepage": "https://www.bamdra.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bamdra/openclaw-topic-memory.git",
+    "directory": "bamdra-memory/plugins/bamdra-memory"
+  },
+  "bugs": {
+    "url": "https://github.com/bamdra/openclaw-topic-memory/issues"
+  },
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "skills"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "topic-memory",
+    "sqlite",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "bundle": "node ../../scripts/run-local-bin.mjs tsup && cp ../../packages/memory-sqlite/src/schema.sql ./dist/ && node ../../scripts/prepare-plugin-dist.mjs bamdra-openclaw-memory",
+    "prepublishOnly": "pnpm run bundle"
+  },
+  "openclaw": {
+    "id": "bamdra-openclaw-memory",
+    "type": "context-engine",
+    "slot": "memory",
+    "capabilities": [
+      "memory"
+    ],
+    "manifest": "./openclaw.plugin.json",
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.5.2"
+  }
+}

package/skills/bamdra-memory-operator/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bamdra-memory-operator
+description: Use bamdra-memory so OpenClaw can remember important facts, switch back to earlier topics, and avoid making users repeat themselves.
+---
+
+# Bamdra Memory Operator
+
+Use `bamdra-memory` tools to preserve continuity without making the conversation feel mechanical.
+
+This skill is an optional behavior layer. It improves tool judgment, but the runtime memory chain must still be provided by the plugin itself.
+
+## Operating Goal
+
+Make memory feel natural:
+
+- keep stable facts available across topic drift
+- let different threads stay separated unless the user reconnects them
+- recover prior context quietly when it helps
+- avoid leaking unrelated memory into the current answer
+- avoid narrating internal storage mechanics unless the user asks
+
+## Decision Policy
+
+Use semantic judgment first. Treat examples in this file as signals, not as a complete phrase list.
+
+Prefer memory tools when one of these is true:
+
+- the user explicitly asks to remember something
+- the detail is a stable preference, identity fact, project constraint, path, account reference, environment invariant, or durable decision
+- the conversation appears to return to an older thread
+- the conversation appears to branch into a new thread
+- the answer may already exist in memory
+- the user explicitly asks to keep topics separate, resume an older branch, or start fresh
+
+Do not reach for memory tools when one of these is true:
+
+- the detail is transient and only matters for the current turn
+- the user is casually brainstorming and has not signaled that a detail should persist
+- using a tool would add noise without improving continuity or accuracy
+- the request would cross agent or user boundaries that should remain isolated
+
+## Topic Judgment
+
+Treat topic handling as a judgment task, not a keyword trigger.
+
+Strong signals for a new topic:
+
+- the user explicitly says this is a new topic, wants to start over, or says earlier threads should not interfere
+- the semantic center clearly shifts away from the active thread
+- the user introduces a new task domain that should remain isolated from the current branch
+
+Strong signals for returning to an old topic:
+
+- the user references a prior subject, entity, plan, or unresolved thread
+- the user asks to continue, resume, go back, or revisit something discussed earlier
+- the best answer depends on facts likely stored under an older branch
+
+When uncertain:
+
+- prefer quiet recovery over long explanations
+- prefer searching memory before asking the user to repeat themselves
+- prefer keeping the current topic if there is no meaningful benefit from switching
+
+## Tool Selection
+
+- Use `memory_save_fact` or `bamdra_memory_save_fact` for stable facts the user is likely to expect later.
+- Use `memory_search` or `bamdra_memory_search` before asking the user to restate a stable fact or prior decision.
+- Use `memory_list_topics` or `bamdra_memory_list_topics` when you need to inspect available branches before switching.
+- Use `memory_switch_topic` or `bamdra_memory_switch_topic` when the user clearly wants to move to, resume, or isolate a branch.
+- Use `memory_compact_topic` or `bamdra_memory_compact_topic` after a branch has materially changed and its summary is stale.
+
+## Privacy And Isolation
+
+- Respect agent isolation. Do not assume another agent's branch is available unless the runtime explicitly exposes it.
+- Respect user isolation. Do not retrieve or reveal information outside the current user/session boundary.
+- Do not surface unrelated facts from memory just because they were found.
+- If memory retrieval feels privacy-sensitive or contextually risky, narrow the search or answer conservatively.
+
+## Working Style
+
+- Keep memory behavior mostly invisible.
+- Mention it briefly only when it helps the user trust continuity.
+- Use normal conversational language rather than tool narration.
+- Do not explain topic IDs, database actions, or storage internals unless asked.