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

package/skills/cortex-memory/references/system-prompt-template.md

@@ -0,0 +1,27 @@
+# Cortex Memory 系统提示词模板
+
+可直接粘贴到 Agent 系统提示词中：
+
+## Cortex Memory 记忆插件使用规则（核心规则，不允许删除）
+
+你已接入 Cortex Memory。必须遵循以下规则：
+
+1. 禁止臆造历史事实；凡涉及历史对话、用户偏好、项目既有决策，先检索再回答。  
+2. 单个任务内避免重复写入：`store_event` / `reflect_memory` 仅在关键节点或收尾触发一次。  
+3. 用户询问历史信息、偏好、项目上下文时：先调用 `search_memory`，再回答。  
+4. 需要当前会话热上下文时：调用 `get_hot_context`。  
+5. 需要自动召回相关记忆时：调用 `get_auto_context`。  
+6. 需要实体关系、依赖链路或路径关系时：调用 `query_graph`。  
+7. 仅在“重要事项已结束且结论明确”后调用 `store_event` 记录结果（过程进行中不频繁记录）。  
+8. 当任务经历“失败 -> 调整 -> 成功”时：先用 `store_event` 记录失败原因与成功方案，再调用 `reflect_memory` 沉淀可复用规则。  
+9. 需要导入历史会话时：调用 `sync_memory`。  
+10. 当 `diagnostics` 显示 active/archive 有未向量化记录，或迁移后需重建向量层时：调用 `backfill_embeddings`（按需选择 `incremental` / `vector_only` / `full`）。  
+11. 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时：优先调用 `diagnostics`。  
+12. 仅在用户明确要求删除记忆，且已确认 `memory_id` 时，才调用 `delete_memory`；禁止在未确认情况下自动删除。  
+13. 任一工具调用失败时，先重试一次；仍失败则明确告知用户，并基于当前可得上下文继续完成任务。  
+14. 调用任意 Cortex Memory 工具前，先确认当前运行环境可见该工具；若工具不可见，必须立即报告“当前 lane 不可用”，不得虚构执行结果。  
+15. `sync_memory` 属于关键路径任务：执行前后应避免并发重复触发；若已有同任务进行中，复用当前结果或等待完成。  
+16. 当用户明确请求 Cortex Memory 任务（如 `sync_memory` / `search_memory` / `store_event`）时，禁止切换到无关流程（如心跳巡检、日报、闲聊任务）；若被系统任务打断，先完成用户请求再处理后台任务。  
+17. 当 `query_graph` 返回 `conflict_hint` 时，不得静默覆盖冲突事实；先调用 `list_graph_conflicts` 并与用户确认，再调用 `resolve_graph_conflict`。  
+18. 需要说明图谱状态分布、冲突生命周期或可视化快照时，调用 `export_graph_view`。  
+19. 需要排查图谱与 Wiki 投影一致性时，调用 `lint_memory_wiki` 并按 `next_action` 执行修复。  

package/skills/cortex-memory/references/tools.md

@@ -0,0 +1,181 @@
+# Cortex Memory Tool Reference
+
+## Retrieval
+
+### `search_memory`
+
+Use for semantic recall of historical records.
+
+Input:
+
+```json
+{
+  "query": "What did we decide about memory decay?",
+  "top_k": 8
+}
+```
+
+### `query_graph`
+
+Use for entity relationship lookup and path traversal.
+
+Input:
+
+```json
+{
+  "entity": "memoryDecay",
+  "rel": "depends_on",
+  "dir": "both",
+  "path_to": "readFusion",
+  "max_depth": 3
+}
+```
+
+Typical response highlights:
+- `edges[].fact_status` (`active/pending_conflict/superseded/rejected`)
+- `wiki_refs`
+- `evidence_ids`
+- `conflict_hint` (when conflict facts are hit)
+
+### `export_graph_view`
+
+Use for status-aware graph snapshot export and wiki graph projection files.
+
+Input:
+
+```json
+{
+  "write_snapshot": true
+}
+```
+
+### `lint_memory_wiki`
+
+Run wiki + graph consistency lint checks and return structured repair actions.
+
+Input:
+
+```json
+{}
+```
+
+## Conflict Governance
+
+### `list_graph_conflicts`
+
+List pending/handled conflicts that need confirmation.
+
+Input:
+
+```json
+{
+  "status": "pending",
+  "limit": 20
+}
+```
+
+### `resolve_graph_conflict`
+
+Accept or reject a conflict candidate.
+
+Input:
+
+```json
+{
+  "conflict_id": "gcf_xxx",
+  "action": "accept",
+  "note": "accepted with user confirmation"
+}
+```
+
+## Persistence
+
+### `store_event`
+
+Persist durable decisions, outcomes, and entity relations.
+
+Input:
+
+```json
+{
+  "summary": "Enabled strict graph quality mode for production.",
+  "entities": ["graphQualityMode", "production"],
+  "entity_types": {
+    "graphQualityMode": "config",
+    "production": "environment"
+  },
+  "outcome": "Reduced noisy relations in graph reads.",
+  "relations": [
+    {
+      "source": "graphQualityMode",
+      "target": "production",
+      "type": "applied_to",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+### `delete_memory`
+
+Delete a specific record by id.
+
+Input:
+
+```json
+{
+  "memory_id": "mem_123"
+}
+```
+
+## Session Context
+
+### `get_hot_context`
+
+Read currently hot records.
+
+```json
+{
+  "limit": 10
+}
+```
+
+### `get_auto_context`
+
+Read auto-selected context from recent messages.
+
+```json
+{
+  "include_hot": true
+}
+```
+
+## Maintenance
+
+### `sync_memory`
+
+Import historical session data into memory.
+
+### `reflect_memory`
+
+Promote events into reusable rules.
+
+### `backfill_embeddings`
+
+Repair or rebuild missing vectors.
+
+Input:
+
+```json
+{
+  "layer": "all",
+  "batch_size": 64,
+  "max_retries": 3,
+  "retry_failed_only": false,
+  "rebuild_mode": "incremental"
+}
+```
+
+### `diagnostics`
+
+Check model connectivity, registry status, and memory health.

package/skills/cortex-memory/scripts/smoke-check.ps1

@@ -0,0 +1,56 @@
+param(
+  [switch]$Json
+)
+
+$requiredEnv = @(
+  "EMBEDDING_API_KEY",
+  "LLM_API_KEY",
+  "RERANKER_API_KEY"
+)
+
+$envStatus = @()
+foreach ($name in $requiredEnv) {
+  $value = [Environment]::GetEnvironmentVariable($name)
+  $envStatus += [PSCustomObject]@{
+    name = $name
+    present = -not [string]::IsNullOrWhiteSpace($value)
+  }
+}
+
+$defaultConfigPath = Join-Path $HOME ".openclaw/openclaw.json"
+$configPath = if ($env:OPENCLAW_CONFIG_PATH) { $env:OPENCLAW_CONFIG_PATH } else { $defaultConfigPath }
+$configExists = Test-Path -LiteralPath $configPath
+
+$summary = [PSCustomObject]@{
+  checkedAt = (Get-Date).ToString("o")
+  configPath = $configPath
+  configExists = $configExists
+  env = $envStatus
+  allRequiredEnvPresent = (($envStatus | Where-Object { -not $_.present }).Count -eq 0)
+}
+
+if ($Json) {
+  $summary | ConvertTo-Json -Depth 6
+  exit 0
+}
+
+Write-Host "Cortex Memory smoke check"
+Write-Host "Config path: $($summary.configPath)"
+Write-Host "Config exists: $($summary.configExists)"
+Write-Host ""
+Write-Host "Required environment variables:"
+foreach ($item in $envStatus) {
+  $state = if ($item.present) { "OK" } else { "MISSING" }
+  Write-Host ("- {0}: {1}" -f $item.name, $state)
+}
+
+if (-not $summary.allRequiredEnvPresent) {
+  Write-Host ""
+  Write-Host "One or more required environment variables are missing."
+  exit 1
+}
+
+Write-Host ""
+Write-Host "All required environment variables are present."
+exit 0
+