openclaw-cortex-memory 0.1.0-Alpha.3 → 0.1.0-Alpha.30

package/dist/openclaw.plugin.json

@@ -1,12 +1,12 @@
 {
   "id": "openclaw-cortex-memory",
   "name": "Cortex Memory",
-  "version": "0.1.0-Alpha.1",
+  "version": "0.1.0-Alpha.30",
   "description": "Long-term memory system with semantic, episodic, and procedural memory for AI Agents",
   "main": "dist/index.js",
-  "author": "OpenClaw Community",
+  "author": "deki18",
   "license": "MIT",
-  "type": "memory",
+  "kind": "memory",
   "repository": {
     "type": "git",
     "url": "https://github.com/deki18/openclaw-cortex-memory"
@@ -18,6 +18,27 @@
     "channels": false,
     "memory": true
   },
+  "runtimeRequirements": {
+    "requiresCredentials": true,
+    "requiresNetwork": true,
+    "credentialSources": {
+      "env": [
+        "EMBEDDING_API_KEY",
+        "LLM_API_KEY",
+        "RERANKER_API_KEY"
+      ],
+      "pluginConfig": [
+        "embedding.apiKey",
+        "llm.apiKey",
+        "reranker.apiKey"
+      ]
+    },
+    "externalEndpoints": {
+      "embedding": "OpenAI-compatible /embeddings endpoint",
+      "llm": "OpenAI-compatible /chat/completions endpoint",
+      "reranker": "Reranker /rerank endpoint"
+    }
+  },
   "hooks": [
     "message_received",
     "session_end"
@@ -56,6 +77,32 @@
             "type": "array",
             "description": "Involved entities",
             "items": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "type": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "entity_types": {
+            "type": "object",
+            "description": "Entity type map, key is entity name and value is type",
+            "additionalProperties": {
               "type": "string"
             }
           },
@@ -67,7 +114,33 @@
             "type": "array",
             "description": "Entity relationships",
             "items": {
-              "type": "string"
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "source": {
+                      "type": "string"
+                    },
+                    "target": {
+                      "type": "string"
+                    },
+                    "type": {
+                      "type": "string"
+                    },
+                    "evidence_span": {
+                      "type": "string"
+                    },
+                    "confidence": {
+                      "type": "number"
+                    }
+                  },
+                  "required": ["source", "target"],
+                  "additionalProperties": false
+                }
+              ]
             }
           }
         },
@@ -84,6 +157,23 @@
           "entity": {
             "type": "string",
             "description": "Entity name"
+          },
+          "rel": {
+            "type": "string",
+            "description": "Optional relation type filter"
+          },
+          "dir": {
+            "type": "string",
+            "description": "Relation direction filter",
+            "enum": ["incoming", "outgoing", "both"]
+          },
+          "path_to": {
+            "type": "string",
+            "description": "Find path from entity to this target entity"
+          },
+          "max_depth": {
+            "type": "integer",
+            "description": "Path query max depth (2~4)"
           }
         },
         "required": ["entity"],
@@ -140,6 +230,39 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "backfill_embeddings",
+      "description": "Backfill missing embeddings for active/archive records",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "layer": {
+            "type": "string",
+            "enum": ["active", "archive", "all"],
+            "description": "Target layer to backfill"
+          },
+          "batch_size": {
+            "type": "integer",
+            "description": "Batch size per processing window"
+          },
+          "max_retries": {
+            "type": "integer",
+            "description": "Max retry count for failed records"
+          },
+          "retry_failed_only": {
+            "type": "boolean",
+            "description": "Only retry failed records"
+          },
+          "rebuild_mode": {
+            "type": "string",
+            "enum": ["incremental", "vector_only", "full"],
+            "description": "Rebuild mode"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "delete_memory",
       "description": "Delete a memory by ID",
@@ -174,17 +297,6 @@
         "description": "Enable or disable Cortex Memory plugin",
         "default": true
       },
-      "apiUrl": {
-        "type": "string",
-        "description": "URL of the memory service API",
-        "default": "http://127.0.0.1:8765"
-      },
-      "engineMode": {
-        "type": "string",
-        "description": "Memory engine mode",
-        "enum": ["ts"],
-        "default": "ts"
-      },
       "dbPath": {
         "type": "string",
         "description": "Path to the memory database directory"
@@ -199,6 +311,17 @@
         "description": "Automatically trigger reflection periodically",
         "default": false
       },
+      "autoReflectIntervalMinutes": {
+        "type": "integer",
+        "description": "Auto reflection scan interval in minutes",
+        "default": 30
+      },
+      "graphQualityMode": {
+        "type": "string",
+        "description": "Graph extraction quality gate mode",
+        "enum": ["off", "warn", "strict"],
+        "default": "warn"
+      },
       "embedding": {
         "type": "object",
         "description": "Embedding model configuration",
@@ -226,8 +349,19 @@
           "dimensions": {
             "type": "integer",
             "description": "Embedding dimensions"
+          },
+          "timeoutMs": {
+            "type": "integer",
+            "description": "Embedding request timeout in milliseconds",
+            "default": 20000
+          },
+          "maxRetries": {
+            "type": "integer",
+            "description": "Maximum retry attempts for embedding requests",
+            "default": 4
           }
         },
+        "required": ["provider", "model"],
         "additionalProperties": false
       },
       "llm": {
@@ -255,6 +389,7 @@
             "description": "LLM API base URL (camelCase alias)"
           }
         },
+        "required": ["provider", "model"],
         "additionalProperties": false
       },
       "reranker": {
@@ -282,12 +417,246 @@
             "description": "Reranker API base URL (camelCase alias)"
           }
         },
+        "required": ["model"],
         "additionalProperties": false
       },
       "fallbackToBuiltin": {
         "type": "boolean",
         "description": "Fallback to OpenClaw builtin memory when Cortex Memory fails",
         "default": true
+      },
+      "readFusion": {
+        "type": "object",
+        "description": "Post-rerank LLM fusion for multi-route retrieval results",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable LLM fusion after rerank",
+            "default": true
+          },
+          "maxCandidates": {
+            "type": "integer",
+            "description": "Maximum reranked candidates used for fusion",
+            "default": 10
+          },
+          "authoritative": {
+            "type": "boolean",
+            "description": "Return only fused authoritative memory package to agent",
+            "default": true
+          },
+          "channelWeights": {
+            "type": "object",
+            "description": "Channel score multiplier overrides",
+            "properties": {
+              "rules": { "type": "number" },
+              "archive": { "type": "number" },
+              "vector": { "type": "number" },
+              "graph": { "type": "number" }
+            },
+            "additionalProperties": false
+          },
+          "channelTopK": {
+            "type": "object",
+            "description": "Per-channel pre-merge candidate quotas",
+            "properties": {
+              "rules": { "type": "integer" },
+              "archive": { "type": "integer" },
+              "vector": { "type": "integer" },
+              "graph": { "type": "integer" }
+            },
+            "additionalProperties": false
+          },
+          "minLexicalHits": {
+            "type": "integer",
+            "description": "Ensure lexical-hit coverage in final ranked set"
+          },
+          "minSemanticHits": {
+            "type": "integer",
+            "description": "Ensure semantic-hit coverage in final ranked set"
+          },
+          "lengthNorm": {
+            "type": "object",
+            "description": "Length normalization settings for semantic score",
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "pivotChars": { "type": "integer", "default": 1200 },
+              "strength": { "type": "number", "default": 0.75 },
+              "minFactor": { "type": "number", "default": 0.45 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      "vectorChunking": {
+        "type": "object",
+        "description": "Vector chunking controls for active/archive full-text chunk embeddings",
+        "properties": {
+          "chunkSize": {
+            "type": "integer",
+            "description": "Chunk size in characters",
+            "default": 600
+          },
+          "chunkOverlap": {
+            "type": "integer",
+            "description": "Chunk overlap in characters",
+            "default": 100
+          },
+          "evidenceMaxChunks": {
+            "type": "integer",
+            "description": "Maximum evidence chunks per archive event",
+            "default": 2
+          }
+        },
+        "additionalProperties": false
+      },
+      "writePolicy": {
+        "type": "object",
+        "description": "Write-path quality thresholds and limits",
+        "properties": {
+          "archiveMinConfidence": {
+            "type": "number",
+            "description": "Minimum confidence for archiving events",
+            "default": 0.35
+          },
+          "archiveMinQualityScore": {
+            "type": "number",
+            "description": "Minimum quality score for archive events",
+            "default": 0.4
+          },
+          "activeMinQualityScore": {
+            "type": "number",
+            "description": "Minimum quality score for active records",
+            "default": 0.45
+          },
+          "activeDedupTailLines": {
+            "type": "integer",
+            "description": "Active-layer dedup tail line window",
+            "default": 200
+          },
+          "activeTextMaxChars": {
+            "type": "integer",
+            "description": "Maximum chars for active text payload",
+            "default": 4000
+          },
+          "archiveSourceTextMaxChars": {
+            "type": "integer",
+            "description": "Maximum chars for archive source_text payload",
+            "default": 8000
+          }
+        },
+        "additionalProperties": false
+      },
+      "memoryDecay": {
+        "type": "object",
+        "description": "Time-decay controls for retrieval ranking by event_type",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable event-type half-life decay in retrieval ranking",
+            "default": true
+          },
+          "minFloor": {
+            "type": "number",
+            "description": "Minimum decay factor floor in [0,1]",
+            "default": 0.15
+          },
+          "defaultHalfLifeDays": {
+            "type": "number",
+            "description": "Default half-life in days for unconfigured event types",
+            "default": 90
+          },
+          "halfLifeByEventType": {
+            "type": "object",
+            "description": "Half-life days overrides by event_type",
+            "additionalProperties": {
+              "type": "number"
+            }
+          },
+          "antiDecay": {
+            "type": "object",
+            "description": "Hit-frequency anti-decay controls",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Enable anti-decay boost for frequently hit memories",
+                "default": true
+              },
+              "maxBoost": {
+                "type": "number",
+                "description": "Maximum multiplicative anti-decay boost (>=1)",
+                "default": 1.6
+              },
+              "hitWeight": {
+                "type": "number",
+                "description": "Hit count to boost conversion weight",
+                "default": 0.08
+              },
+              "recentWindowDays": {
+                "type": "number",
+                "description": "Recent hit window in days for freshness contribution",
+                "default": 30
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      "readTuning": {
+        "type": "object",
+        "description": "Read-path ranking and recency tuning",
+        "properties": {
+          "scoring": {
+            "type": "object",
+            "properties": {
+              "lexicalWeight": { "type": "number", "default": 0.2 },
+              "bm25Scale": { "type": "number", "default": 2 },
+              "semanticWeight": { "type": "number", "default": 0.3 },
+              "recencyWeight": { "type": "number", "default": 0.1 },
+              "qualityWeight": { "type": "number", "default": 0.15 },
+              "typeMatchWeight": { "type": "number", "default": 0.15 },
+              "graphMatchWeight": { "type": "number", "default": 0.1 }
+            },
+            "additionalProperties": false
+          },
+          "rrf": {
+            "type": "object",
+            "properties": {
+              "k": { "type": "integer", "default": 60 },
+              "weight": { "type": "number", "default": 1.5 }
+            },
+            "additionalProperties": false
+          },
+          "recency": {
+            "type": "object",
+            "properties": {
+              "buckets": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "maxAgeHours": { "type": "number" },
+                    "score": { "type": "number" },
+                    "bonus": { "type": "number" }
+                  },
+                  "required": ["maxAgeHours", "score", "bonus"],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          },
+          "autoContext": {
+            "type": "object",
+            "properties": {
+              "queryMaxChars": { "type": "integer", "default": 80 },
+              "lightweightSearch": { "type": "boolean", "default": true }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
       }
     },
     "additionalProperties": false

package/dist/src/dedup/three_stage_deduplicator.d.ts

@@ -0,0 +1,25 @@
+interface LoggerLike {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+}
+interface DedupInput {
+    id: string;
+    summary: string;
+    embedding?: number[];
+}
+interface DedupResult {
+    duplicate: boolean;
+    stage?: "simhash" | "minhash" | "vector";
+    matchedId?: string;
+}
+interface DeduplicatorOptions {
+    memoryRoot: string;
+    logger: LoggerLike;
+}
+export declare function createThreeStageDeduplicator(options: DeduplicatorOptions): {
+    check(input: DedupInput): DedupResult;
+    append(input: DedupInput): void;
+};
+export {};
+//# sourceMappingURL=three_stage_deduplicator.d.ts.map

package/dist/src/dedup/three_stage_deduplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three_stage_deduplicator.d.ts","sourceRoot":"","sources":["../../../src/dedup/three_stage_deduplicator.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACrD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACrD;AAeD,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,UAAU,WAAW;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,mBAAmB;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;CACpB;AAgJD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAC1E,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAC;IACtC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACjC,CAsDA"}