@tpsdev-ai/openclaw-flair 0.25.4 → 0.27.0

package/README.md

@@ -10,7 +10,7 @@ Uses Flair's native Harper vector embeddings — no OpenAI API key required.
 - **Persistent storage** via `memory_store` → Ed25519-authenticated writes
 - **Memory retrieval** via `memory_get` → fetch by ID
 - **Auto-bootstrap** — injects relevant memories into context at session start
-- **Auto-capture** — automatically stores important information from conversations
+- **Auto-capture** — automatically stores important information from conversations, live, on every turn — works in both discrete runs and long-lived persistent gateway sessions (#798)
 - **Multi-agent** — `agentId: "auto"` resolves per-session for shared gateways
 - **Durability levels** — permanent, persistent, standard, ephemeral
 - **Memory versioning** — `supersedes` field creates version chains
@@ -70,6 +70,16 @@ In your OpenClaw config (`openclaw.json`):
 | `autoCapture` | boolean | `true` | Auto-capture important info from conversations |
 | `autoRecall` | boolean | `true` | Inject relevant memories at session start |
 | `maxRecallResults` | number | `5` | Max results for `memory_search` |
+| `autoCaptureMaxPerSession` | number | `3` | Cap on trigger-based auto-captures per session (see below) |
+
+### Auto-capture
+
+Auto-capture scans conversation text for a small set of conservative trigger phrases (e.g. "remember this", "we decided", "my name is") and writes a matching excerpt to Flair. It runs on two hooks:
+
+- **`agent_end`** — scans the full conversation once, at the true end of a discrete run. Also detects entities/relationships from the same pass.
+- **`llm_input`/`llm_output`** — scans the live prompt/response on every model call. This is what makes auto-capture work in a long-lived, persistent gateway session, where `agent_end` never fires because the "run" never ends (#798).
+
+Both hooks share one capture budget per agent session (`autoCaptureMaxPerSession`, default 3) and dedup by content hash, so a phrase captured live during a run isn't captured again when `agent_end` rescans that same run's history at the end. For a persistent session that never fires `agent_end`, the budget is never reset — it's a cap for the session's whole lifetime, not per calendar day. Raise `autoCaptureMaxPerSession` if a long-lived deployment needs more than 3 auto-captures over its life.
 
 ## Tool naming
 

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 export declare function isValidAgentId(agentId: string | null | undefined): boolean;
 export declare function assertValidAgentId(agentId: string | null | undefined): asserts agentId is string;
+interface CaptureState {
+    count: number;
+    hashes: Set<string>;
+}
+export declare function evaluateAutoCapture(text: string, state: Pick<CaptureState, "count" | "hashes">, maxPerSession?: number): {
+    excerpt: string;
+    hash: string;
+} | null;
 declare const _default: {
     kind: "memory";
     register(api: OpenClawPluginApi): void;

package/dist/index.js

@@ -17,6 +17,7 @@ export function assertValidAgentId(agentId) {
 const DEFAULT_URL = "http://127.0.0.1:19926";
 const DEFAULT_MAX_RECALL = 5;
 const DEFAULT_MAX_BOOTSTRAP_TOKENS = 4000;
+const DEFAULT_AUTO_CAPTURE_MAX_PER_SESSION = 3;
 const WORKSPACE_SOUL_FILES = {
     "SOUL.md": "soul",
     "IDENTITY.md": "identity",
@@ -71,6 +72,24 @@ function shouldCapture(text) {
 function excerptForCapture(text, maxChars = 500) {
     return text.length > maxChars ? `${text.slice(0, maxChars)}…` : text;
 }
+function createCaptureState() {
+    return { count: 0, hashes: new Set() };
+}
+export function evaluateAutoCapture(text, state, maxPerSession = DEFAULT_AUTO_CAPTURE_MAX_PER_SESSION) {
+    if (!shouldCapture(text))
+        return null;
+    if (state.count >= maxPerSession)
+        return null;
+    const excerpt = excerptForCapture(text);
+    const hash = hashContent(excerpt);
+    if (state.hashes.has(hash))
+        return null;
+    return { excerpt, hash };
+}
+function recordCapture(state, hash) {
+    state.count++;
+    state.hashes.add(hash);
+}
 const PERSON_PATTERNS = [
     /\b([A-Z][a-z]{2,})\s+(?:said|asked|mentioned|decided|approved|rejected|thinks|wants|needs|prefers)\b/g,
     /\b(?:ask|ping|tell|check with|talk to)\s+(?:@)?([A-Z][a-z]{2,})\b/g,
@@ -305,6 +324,34 @@ export default {
             const maxRecall = cfg.maxRecallResults ?? DEFAULT_MAX_RECALL;
             const autoCapture = cfg.autoCapture ?? false;
             const autoRecall = cfg.autoRecall ?? true;
+            const autoCaptureMaxPerSession = Math.max(1, cfg.autoCaptureMaxPerSession ?? DEFAULT_AUTO_CAPTURE_MAX_PER_SESSION);
+            const captureStatePool = new Map();
+            function getCaptureState(agentId) {
+                let state = captureStatePool.get(agentId);
+                if (!state) {
+                    state = createCaptureState();
+                    captureStatePool.set(agentId, state);
+                }
+                return state;
+            }
+            function resetCaptureState(agentId) {
+                captureStatePool.delete(agentId);
+            }
+            async function tryAutoCapture(client, agentId, text) {
+                const state = getCaptureState(agentId);
+                const decision = evaluateAutoCapture(text, state, autoCaptureMaxPerSession);
+                if (!decision)
+                    return false;
+                const entities = detectEntities(text);
+                const subject = entities.length > 0 ? entities[0].name.toLowerCase() : undefined;
+                await client.memory.write(decision.excerpt, {
+                    type: "session",
+                    tags: ["auto-captured"],
+                    subject,
+                });
+                recordCapture(state, decision.hash);
+                return true;
+            }
             let currentAgentId = isAutoMode ? (fallbackAgentId ?? undefined) : cfg.agentId;
             const configuredAgentId = cfg.agentId && cfg.agentId !== "auto" ? cfg.agentId : null;
             api.on("before_agent_start", async (event, ctx) => {
@@ -488,9 +535,12 @@ export default {
                 });
             }
             if (autoCapture) {
-                api.on("agent_end", async (event) => {
+                api.on("agent_end", async (event, ctx) => {
+                    const agentId = ctx?.agentId || currentAgentId || fallbackAgentId || undefined;
+                    if (!agentId)
+                        return;
                     try {
-                        const client = getCurrentClient();
+                        const client = getClient(agentId);
                         const messages = (event.messages ?? []);
                         let stored = 0;
                         const allEntities = new Map();
@@ -501,17 +551,8 @@ export default {
                             const text = typeof msg.content === "string" ? msg.content : "";
                             if (!text || text.length < MIN_CAPTURE_LENGTH)
                                 continue;
-                            if (shouldCapture(text) && stored < 3) {
-                                const excerpt = excerptForCapture(text);
-                                const entities = detectEntities(text);
-                                const subject = entities.length > 0 ? entities[0].name.toLowerCase() : undefined;
-                                await client.memory.write(excerpt, {
-                                    type: "session",
-                                    tags: ["auto-captured"],
-                                    subject,
-                                });
+                            if (await tryAutoCapture(client, agentId, text))
                                 stored++;
-                            }
                             for (const entity of detectEntities(text)) {
                                 const key = entity.name.toLowerCase();
                                 const existing = allEntities.get(key);
@@ -548,6 +589,44 @@ export default {
                     catch (err) {
                         api.logger.warn(`openclaw-flair: auto-capture failed: ${err.message}`);
                     }
+                    finally {
+                        resetCaptureState(agentId);
+                    }
+                });
+                api.on("llm_input", async (event, ctx) => {
+                    const agentId = ctx?.agentId || currentAgentId || fallbackAgentId || undefined;
+                    if (!agentId)
+                        return;
+                    const text = typeof event?.prompt === "string" ? event.prompt : "";
+                    if (!text)
+                        return;
+                    try {
+                        const client = getClient(agentId);
+                        const captured = await tryAutoCapture(client, agentId, text);
+                        if (captured)
+                            api.logger.info("openclaw-flair: auto-captured 1 memory from live turn (llm_input)");
+                    }
+                    catch (err) {
+                        api.logger.warn(`openclaw-flair: live auto-capture (llm_input) failed: ${err.message}`);
+                    }
+                });
+                api.on("llm_output", async (event, ctx) => {
+                    const agentId = ctx?.agentId || currentAgentId || fallbackAgentId || undefined;
+                    if (!agentId)
+                        return;
+                    const texts = Array.isArray(event?.assistantTexts) ? event.assistantTexts : [];
+                    const text = texts.filter((t) => typeof t === "string").join("\n");
+                    if (!text)
+                        return;
+                    try {
+                        const client = getClient(agentId);
+                        const captured = await tryAutoCapture(client, agentId, text);
+                        if (captured)
+                            api.logger.info("openclaw-flair: auto-captured 1 memory from live turn (llm_output)");
+                    }
+                    catch (err) {
+                        api.logger.warn(`openclaw-flair: live auto-capture (llm_output) failed: ${err.message}`);
+                    }
                 });
             }
             if (typeof api.registerContextEngine === "function") {

package/openclaw.plugin.json

@@ -29,6 +29,11 @@
     "autoRecall": {
       "label": "Auto-Recall",
       "help": "Automatically inject relevant memories into context at session start"
+    },
+    "autoCaptureMaxPerSession": {
+      "label": "Auto-Capture Max Per Session",
+      "help": "Cap on trigger-based auto-captures per session (default 3). For a long-lived persistent session, this is the cap for the session's whole lifetime, not per calendar day.",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -41,7 +46,8 @@
       "autoCapture": { "type": "boolean" },
       "autoRecall": { "type": "boolean" },
       "maxRecallResults": { "type": "number", "minimum": 1, "maximum": 20 },
-      "maxBootstrapTokens": { "type": "number", "minimum": 500, "maximum": 8000 }
+      "maxBootstrapTokens": { "type": "number", "minimum": 500, "maximum": 8000 },
+      "autoCaptureMaxPerSession": { "type": "number", "minimum": 1, "maximum": 50 }
     },
     "required": []
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/openclaw-flair",
-  "version": "0.25.4",
+  "version": "0.27.0",
   "description": "OpenClaw memory plugin for Flair — agent identity and semantic memory",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,7 +58,7 @@
   },
   "dependencies": {
     "@sinclair/typebox": "0.34.48",
-    "@tpsdev-ai/flair-client": "0.25.4"
+    "@tpsdev-ai/flair-client": "0.27.0"
   },
   "devDependencies": {
     "typescript": "5.9.3"