openclaw-cortex-memory 0.1.0-Alpha.9 → 0.1.1

package/openclaw.plugin.json

@@ -1,12 +1,12 @@
 {
   "id": "openclaw-cortex-memory",
   "name": "Cortex Memory",
-  "version": "0.1.0-Alpha.9",
+  "version": "0.1.1",
   "description": "Long-term memory system with semantic, episodic, and procedural memory for AI Agents",
   "main": "dist/index.js",
   "author": "deki18",
   "license": "MIT",
-  "type": "memory",
+  "kind": "memory",
   "repository": {
     "type": "git",
     "url": "https://github.com/deki18/openclaw-cortex-memory"
@@ -18,6 +18,47 @@
     "channels": false,
     "memory": true
   },
+  "contracts": {
+    "tools": [
+      "search_memory",
+      "store_event",
+      "query_graph",
+      "export_graph_view",
+      "lint_memory_wiki",
+      "list_graph_conflicts",
+      "resolve_graph_conflict",
+      "get_hot_context",
+      "get_auto_context",
+      "reflect_memory",
+      "sync_memory",
+      "backfill_embeddings",
+      "delete_memory",
+      "cortex_diagnostics",
+      "diagnostics",
+      "cortex_memory_status"
+    ]
+  },
+  "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"
@@ -36,6 +77,15 @@
           "top_k": {
             "type": "integer",
             "description": "Number of results to return"
+          },
+          "fusion_mode": {
+            "type": "string",
+            "enum": ["auto", "authoritative", "candidates", "off"],
+            "description": "LLM fusion behavior for this search. auto honors config; authoritative returns only the fused answer; candidates returns fusion plus ranked candidates; off disables fusion."
+          },
+          "track_hits": {
+            "type": "boolean",
+            "description": "Whether to update anti-decay hit statistics. Set false for diagnostics or benchmarks."
           }
         },
         "required": ["query"],
@@ -52,6 +102,18 @@
             "type": "string",
             "description": "Event summary"
           },
+          "cause": {
+            "type": "string",
+            "description": "What triggered the event (task/request/problem statement)"
+          },
+          "process": {
+            "type": "string",
+            "description": "How the task was handled (steps/attempts/iterations)"
+          },
+          "result": {
+            "type": "string",
+            "description": "Final result and acceptance outcome"
+          },
           "entities": {
             "type": "array",
             "description": "Involved entities",
@@ -78,6 +140,13 @@
               ]
             }
           },
+          "entity_types": {
+            "type": "object",
+            "description": "Entity type map, key is entity name and value is type",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
           "outcome": {
             "type": "string",
             "description": "Event outcome"
@@ -101,6 +170,12 @@
                     },
                     "type": {
                       "type": "string"
+                    },
+                    "evidence_span": {
+                      "type": "string"
+                    },
+                    "confidence": {
+                      "type": "number"
                     }
                   },
                   "required": ["source", "target"],
@@ -146,6 +221,75 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "export_graph_view",
+      "description": "Export status-aware graph view and optionally write wiki graph snapshots",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "write_snapshot": {
+            "type": "boolean",
+            "description": "When true (default), write wiki/graph/view.json, timeline.jsonl and Mermaid network snapshots"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "lint_memory_wiki",
+      "description": "Run wiki memory lint checks for graph consistency, evidence coverage, page quality, and structured repair guidance",
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_graph_conflicts",
+      "description": "List pending/handled graph memory conflicts that require user confirmation",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["pending", "accepted", "rejected", "all"],
+            "description": "Filter conflict status"
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum returned conflicts"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "resolve_graph_conflict",
+      "description": "Resolve a graph conflict by accepting or rejecting the new candidate fact",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "conflict_id": {
+            "type": "string",
+            "description": "Conflict ID from list_graph_conflicts"
+          },
+          "action": {
+            "type": "string",
+            "enum": ["accept", "reject"],
+            "description": "Resolution action"
+          },
+          "note": {
+            "type": "string",
+            "description": "Optional note for audit trail"
+          }
+        },
+        "required": ["conflict_id", "action"],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "get_hot_context",
       "description": "Get hot memory context for current session",
@@ -196,6 +340,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",
@@ -212,7 +389,7 @@
       }
     },
     {
-      "name": "diagnostics",
+      "name": "cortex_diagnostics",
       "description": "Check memory system status",
       "parameters": {
         "type": "object",
@@ -220,6 +397,17 @@
         "required": [],
         "additionalProperties": false
       }
+    },
+    {
+      "name": "diagnostics",
+      "description": "Legacy alias for cortex_diagnostics",
+      "optional": true,
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
     }
   ],
   "configSchema": {
@@ -230,20 +418,9 @@
         "description": "Enable or disable Cortex Memory plugin",
         "default": true
       },
-      "apiUrl": {
-        "type": "string",
-        "description": "URL of the memory service API",
-        "default": "http://localhost:8765"
-      },
-      "engineMode": {
-        "type": "string",
-        "description": "Memory engine mode",
-        "enum": ["ts"],
-        "default": "ts"
-      },
       "dbPath": {
         "type": "string",
-        "description": "Path to the memory database directory"
+        "description": "Path to the memory database directory (default: <openclaw_base>/workspace/memory/openclaw-cortex-memory)"
       },
       "autoSync": {
         "type": "boolean",
@@ -260,6 +437,35 @@
         "description": "Auto reflection scan interval in minutes",
         "default": 30
       },
+      "graphQualityMode": {
+        "type": "string",
+        "description": "Graph extraction quality gate mode",
+        "enum": ["off", "warn", "strict"],
+        "default": "warn"
+      },
+      "wikiProjection": {
+        "type": "object",
+        "description": "Feature flags for wiki projection runtime",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable wiki projection pipeline",
+            "default": false
+          },
+          "mode": {
+            "type": "string",
+            "description": "Wiki projection mode",
+            "enum": ["off", "incremental", "rebuild"],
+            "default": "off"
+          },
+          "maxBatch": {
+            "type": "integer",
+            "description": "Max events/pages processed per projection batch",
+            "default": 100
+          }
+        },
+        "additionalProperties": false
+      },
       "embedding": {
         "type": "object",
         "description": "Embedding model configuration",
@@ -299,7 +505,7 @@
             "default": 4
           }
         },
-        "required": ["provider", "model", "apiKey", "baseURL"],
+        "required": ["provider", "model"],
         "additionalProperties": false
       },
       "llm": {
@@ -327,7 +533,7 @@
             "description": "LLM API base URL (camelCase alias)"
           }
         },
-        "required": ["provider", "model", "apiKey", "baseURL"],
+        "required": ["provider", "model"],
         "additionalProperties": false
       },
       "reranker": {
@@ -355,7 +561,7 @@
             "description": "Reranker API base URL (camelCase alias)"
           }
         },
-        "required": ["provider", "model", "apiKey", "baseURL"],
+        "required": ["model"],
         "additionalProperties": false
       },
       "fallbackToBuiltin": {
@@ -381,6 +587,124 @@
             "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": 200000
+          },
+          "archiveSourceTextMaxChars": {
+            "type": "integer",
+            "description": "Maximum chars for archive source_text payload",
+            "default": 500000
+          }
+        },
+        "additionalProperties": false
+      },
+      "syncPolicy": {
+        "type": "object",
+        "description": "Sync ingestion controls",
+        "properties": {
+          "includeLocalActiveInput": {
+            "type": "boolean",
+            "description": "Whether sync_memory reads local memory/sessions/active/sessions.jsonl as source input",
+            "default": false
+          },
+          "graphQualityMode": {
+            "type": "string",
+            "description": "Graph quality gate mode for sync_memory/history import writes",
+            "enum": ["off", "warn", "strict"],
+            "default": "strict"
           }
         },
         "additionalProperties": false
@@ -440,6 +764,61 @@
           }
         },
         "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": 240 },
+              "lightweightSearch": { "type": "boolean", "default": true }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
       }
     },
     "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-cortex-memory",
-  "version": "0.1.0-Alpha.9",
+  "version": "0.1.1",
   "description": "Long-term memory system for OpenClaw AI Agent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,8 +14,19 @@
     "test:compat": "node scripts/compat-regression.js",
     "test:model": "node scripts/model-regression.js",
     "test:graph": "node scripts/graph-eval.js",
+    "test:graph-quality": "node scripts/graph-quality-eval.js",
+    "test:graph-quality-zh": "node scripts/graph-quality-eval.js --gold eval/graph_quality_gold.zh.jsonl --pred eval/graph_quality_predictions.zh.sample.jsonl --thresholds eval/graph_quality_thresholds.json",
+    "test:m1-ingest-regression": "node scripts/m1-ingest-regression.js",
+    "test:m2-quality-dedup": "node scripts/m2-quality-dedup-regression.js",
+    "test:m3-graph-quality-conflicts": "node scripts/m3-graph-quality-conflicts-regression.js",
+    "test:m5-cross-store": "node scripts/m5-cross-store-regression.js",
+    "test:wiki-projection": "node scripts/wiki-projection-regression.js",
+    "test:wiki-lint": "node scripts/wiki-lint-regression.js",
+    "test:read-search": "node scripts/read-search-regression.js",
+    "test:extended-blocking": "npm run test:m1-ingest-regression && npm run test:m2-quality-dedup && npm run test:m3-graph-quality-conflicts && npm run test:m5-cross-store && npm run test:wiki-projection && npm run test:wiki-lint",
+    "test:ci-core": "npm run test:m1-ingest-regression && npm run test:m2-quality-dedup && npm run test:m3-graph-quality-conflicts && npm run test:m5-cross-store && npm run test:wiki-projection && npm run test:wiki-lint && npm run test:graph && npm run test:lengthnorm && npm run test:read-search",
     "test:lengthnorm": "node scripts/lengthnorm-regression.js",
-    "test:all": "npm run test:compat && npm run test:model && npm run test:graph && npm run test:lengthnorm",
+    "test:all": "npm run test:compat && npm run test:model && npm run test:graph && npm run test:graph-quality && npm run test:graph-quality-zh && npm run test:lengthnorm && npm run test:read-search",
     "release:check": "node scripts/release-pipeline.js",
     "dev": "tsc --watch",
     "prepack": "npm run build",
@@ -38,10 +49,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
+    "clawhub": "^0.9.0",
     "typescript": "^5.7.2"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.8"
+    "openclaw": ">=2026.4.5"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -50,15 +62,49 @@
     "dist/",
     "scripts/cli.js",
     "scripts/uninstall.js",
+    "scripts/repair-memory.js",
+    "schema/",
     "openclaw.plugin.json",
-    "SKILL.md"
+    "SIGNATURE.md",
+    "SKILL.md",
+    "skills/cortex-memory/"
   ],
   "openclaw": {
     "plugin": true,
     "requiresPython": false,
     "cli": "cortex-memory",
+    "requires": {
+      "credentials": true,
+      "network": true,
+      "env": [
+        "EMBEDDING_API_KEY",
+        "LLM_API_KEY",
+        "RERANKER_API_KEY"
+      ],
+      "config": [
+        "embedding.apiKey",
+        "llm.apiKey",
+        "reranker.apiKey",
+        "embedding.baseURL",
+        "llm.baseURL",
+        "reranker.baseURL"
+      ],
+      "externalEndpoints": [
+        "embedding API endpoint (OpenAI-compatible /embeddings)",
+        "LLM API endpoint (OpenAI-compatible /chat/completions)",
+        "reranker API endpoint (/rerank)"
+      ]
+    },
+    "build": {
+      "openclawVersion": "2026.4.5",
+      "pluginSdkVersion": "2026.4.5"
+    },
+    "install": {
+      "minHostVersion": ">=2026.4.5"
+    },
     "compat": {
-      "pluginApi": ">=2026.3.22"
+      "pluginApi": ">=2026.4.5",
+      "minGatewayVersion": "2026.4.5"
     },
     "extensions": [
       "./dist/index.js"