@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/MEMORY_BRAIN.md

@@ -1,104 +1,104 @@
-# Memory Brain
-
-Memory Brain is SCALE's project-scoped long-term memory layer. It is separate from Memory Fabric:
-
-- Memory Fabric builds a compact context pack for the current task.
-- Memory Brain stores reviewed project knowledge with evidence, confidence, scope, and contradiction checks.
-
-The first version is local-first and uses SQLite:
-
-```text
-.scale/memory/brain.sqlite
-.scale/memory/brain-manifest.json
-```
-
-## Commands
-
-```bash
-scale memory ingest --from evidence --task-id <task-id>
-scale memory ingest --from candidate --candidate-id <candidate-id>
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory query "OAuth callback state design"
-scale memory contradictions
-scale memory dream
-scale memory promote <memory-node-id-or-candidate-id>
-scale memory export --output .scale/memory/export.jsonl
-scale memory import .scale/memory/export.jsonl
-```
-
-## Node Contract
-
-```ts
-interface MemoryNode {
-  id: string
-  type: 'fact' | 'decision' | 'incident' | 'relation' | 'contradiction'
-  title: string
-  summary: string
-  entities: string[]
-  source: 'runtime-evidence' | 'task-artifact' | 'docs' | 'git' | 'manual'
-  evidencePaths: string[]
-  confidence: number
-  scope: 'project' | 'workspace' | 'global-candidate'
-  status: 'candidate' | 'active' | 'stale' | 'rejected'
-  createdAt: string
-  updatedAt: string
-  lastVerifiedAt?: string
-}
-```
-
-## Evidence Rule
-
-Active memory must have at least one evidence path. SCALE blocks promotion when this is not true.
-
-Runtime evidence and learning candidates are ingested as `candidate` records first. `scale memory promote` is the explicit boundary where reviewed memory becomes active.
-
-Failure replay records can also be ingested as `incident` candidates:
-
-```bash
-scale eval run --suite workflow-baseline
-scale eval failures --since 30d
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory promote <memory-node-id>
-```
-
-This connects Eval Harness failures to long-term memory without automatically rewriting project standards. A failure becomes active memory only after promotion and only if the replay artifact is present as evidence.
-
-## Scope Rule
-
-Project memory stays project-scoped by default. `global-candidate` is allowed for export and review, but it cannot be activated inside a project brain. This prevents one project's temporary truth from becoming a global rule.
-
-## Contradiction Rule
-
-`scale memory contradictions` reports conflicts instead of resolving them automatically. Examples:
-
-- one memory says a provider is enabled, another says it is disabled
-- one memory says a route exists, another says it is missing
-- one memory says an operation is allowed, another says it is blocked
-
-The command exits non-zero when active contradictions exist.
-
-## Dream Maintenance
-
-`scale memory dream` is a maintenance pass. It reports:
-
-- promotion candidates
-- stale active memories
-- duplicate groups
-- contradictions
-- suggested docs to update
-- active memories missing evidence
-
-It does not auto-promote standards, rewrite docs, or delete memories.
-
-## Resource Lifecycle
-
-Memory Brain files under `.scale/memory/` are local runtime state by default. Commit only curated exports, documented decisions, or task artifacts that were intentionally reviewed.
-
-Recommended flow:
-
-```text
-runtime evidence -> memory settle -> memory ingest -> memory promote -> docs/standards update when stable
-eval failure replay -> memory ingest --from failure -> memory promote -> workflow rule update when stable
-```
-
-This keeps memory useful without turning every session observation into permanent project truth.
+# Memory Brain
+
+Memory Brain is SCALE's project-scoped long-term memory layer. It is separate from Memory Fabric:
+
+- Memory Fabric builds a compact context pack for the current task.
+- Memory Brain stores reviewed project knowledge with evidence, confidence, scope, and contradiction checks.
+
+The first version is local-first and uses SQLite:
+
+```text
+.scale/memory/brain.sqlite
+.scale/memory/brain-manifest.json
+```
+
+## Commands
+
+```bash
+scale memory ingest --from evidence --task-id <task-id>
+scale memory ingest --from candidate --candidate-id <candidate-id>
+scale memory ingest --from failure --failure-id <failure-replay-id>
+scale memory query "OAuth callback state design"
+scale memory contradictions
+scale memory dream
+scale memory promote <memory-node-id-or-candidate-id>
+scale memory export --output .scale/memory/export.jsonl
+scale memory import .scale/memory/export.jsonl
+```
+
+## Node Contract
+
+```ts
+interface MemoryNode {
+  id: string
+  type: 'fact' | 'decision' | 'incident' | 'relation' | 'contradiction'
+  title: string
+  summary: string
+  entities: string[]
+  source: 'runtime-evidence' | 'task-artifact' | 'docs' | 'git' | 'manual'
+  evidencePaths: string[]
+  confidence: number
+  scope: 'project' | 'workspace' | 'global-candidate'
+  status: 'candidate' | 'active' | 'stale' | 'rejected'
+  createdAt: string
+  updatedAt: string
+  lastVerifiedAt?: string
+}
+```
+
+## Evidence Rule
+
+Active memory must have at least one evidence path. SCALE blocks promotion when this is not true.
+
+Runtime evidence and learning candidates are ingested as `candidate` records first. `scale memory promote` is the explicit boundary where reviewed memory becomes active.
+
+Failure replay records can also be ingested as `incident` candidates:
+
+```bash
+scale eval run --suite workflow-baseline
+scale eval failures --since 30d
+scale memory ingest --from failure --failure-id <failure-replay-id>
+scale memory promote <memory-node-id>
+```
+
+This connects Eval Harness failures to long-term memory without automatically rewriting project standards. A failure becomes active memory only after promotion and only if the replay artifact is present as evidence.
+
+## Scope Rule
+
+Project memory stays project-scoped by default. `global-candidate` is allowed for export and review, but it cannot be activated inside a project brain. This prevents one project's temporary truth from becoming a global rule.
+
+## Contradiction Rule
+
+`scale memory contradictions` reports conflicts instead of resolving them automatically. Examples:
+
+- one memory says a provider is enabled, another says it is disabled
+- one memory says a route exists, another says it is missing
+- one memory says an operation is allowed, another says it is blocked
+
+The command exits non-zero when active contradictions exist.
+
+## Dream Maintenance
+
+`scale memory dream` is a maintenance pass. It reports:
+
+- promotion candidates
+- stale active memories
+- duplicate groups
+- contradictions
+- suggested docs to update
+- active memories missing evidence
+
+It does not auto-promote standards, rewrite docs, or delete memories.
+
+## Resource Lifecycle
+
+Memory Brain files under `.scale/memory/` are local runtime state by default. Commit only curated exports, documented decisions, or task artifacts that were intentionally reviewed.
+
+Recommended flow:
+
+```text
+runtime evidence -> memory settle -> memory ingest -> memory promote -> docs/standards update when stable
+eval failure replay -> memory ingest --from failure -> memory promote -> workflow rule update when stable
+```
+
+This keeps memory useful without turning every session observation into permanent project truth.

package/docs/MEMORY_FABRIC.md

@@ -1,134 +1,134 @@
-# Memory Fabric
-
-Memory Fabric 是 SCALE 用来降低长会话 token 消耗、提升 Agent 记忆质量的上下文压缩层。它不会把所有历史文档都塞回提示词，而是按任务范围生成一个可审计的 context pack。
-
-它聚合四类信息：
-
-- Runtime Evidence：真实运行过的命令、工具、浏览器、skill、MCP 和人工验证证据。
-- Session Events：当前会话的阶段、工具使用和证据写入事件。
-- Knowledge Recall：从项目知识库召回已验证经验、规则和历史教训。
-- Project Graph：检测 `graphify-out/GRAPH_REPORT.md` 或 `.scale/graph/manifest.json`，只引用图谱状态和摘要，不把大型图谱全文塞进上下文。
-
-## 基本命令
-
-生成上下文包：
-
-```bash
-scale memory pack \
-  --task-id 2026-05-18-runtime-evidence \
-  --session-id 2026-05-18-runtime-evidence \
-  --task "继续实现 runtime evidence 与最终交付检查" \
-  --level M \
-  --files src/runtime,src/api/cli.ts \
-  --budget 4000
-```
-
-输出 JSON，便于其他 Agent、CLI 或评审工具读取：
-
-```bash
-scale memory pack \
-  --task "修复 OAuth callback state 过期处理" \
-  --level M \
-  --budget 4000 \
-  --json
-```
-
-检查上下文预算：
-
-```bash
-scale memory doctor \
-  --task "跨模块权限重构" \
-  --level L \
-  --budget 3000
-```
-
-把完成任务后的运行证据沉淀成学习候选：
-
-```bash
-scale memory settle \
-  --task-id 2026-05-18-runtime-evidence \
-  --session-id 2026-05-18-runtime-evidence \
-  --task "继续实现 runtime evidence 与最终交付检查" \
-  --level M \
-  --budget 4000
-```
-
-`settle` 会写入：
-
-```text
-.scale/memory/learning-candidates/<candidate-id>.json
-.scale/memory/learning-candidates/<candidate-id>.md
-```
-
-这些文件是本地运行时学习候选，默认不应该直接提交到 Git。它们的作用是让人类或评审 Agent 判断“这条经验是否值得进入长期知识库、工程规范或模块文档”。
-
-## 预算策略
-
-Memory Fabric 使用估算 token 预算控制上下文规模。优先级从高到低：
-
-1. Runtime Evidence：失败证据和通过证据优先保留。
-2. Session Events：最近会话事件优先保留。
-3. Knowledge Recall：按任务描述和文件范围召回 Top K 知识。
-4. Project Graph：只保留图谱报告路径和短摘要。
-
-当预算不足时，低优先级 section 会被标记为 omitted，并写入原因。这样 Agent 能知道哪些上下文被刻意裁剪，而不是误以为项目没有相关信息。
-
-## 与知识库和自我进化的关系
-
-Memory Fabric 不替代知识库。它是知识库、运行证据和图谱之间的读取层：
-
-- Runtime Evidence 记录“这次实际做过什么”。
-- Knowledge Base 记录“长期可复用的经验和规则”。
-- Graphify 或项目图谱记录“模块之间的结构关系”。
-- Memory Fabric 在每次任务开始、恢复、评审或发版前，生成本次最相关的上下文包。
-
-任务完成后，应该把真正稳定的经验沉淀到知识库或长期维护文档中；`.scale/events/` 和 `.scale/evidence/` 仍然是本地运行时产物，不应默认提交到 Git。
-
-新的推荐闭环是：
-
-```text
-runtime evidence -> memory pack -> memory settle -> 人审 -> knowledge/docs/rules
-```
-
-也就是说，Memory Fabric 先把证据和上下文压缩成候选，不会自动把一次会话里的判断升级成长期规则。存在失败证据时，候选会标记为 `resolve-failures-first`，避免把未闭环问题沉淀成“经验”。
-
-## 推荐使用场景
-
-- 长会话恢复前：先生成 context pack，避免重复读大量文档。
-- 多 Agent 协作前：把 context pack 交给审查 Agent 或测试 Agent。
-- 发版前：用 runtime evidence 和 session events 检查是否存在未闭环失败。
-- 任务结束后：用 `memory settle` 生成学习候选，再决定是否进入知识库、模块文档或工程规范。
-- 大型项目治理：结合 service matrix、resource governance 和 engineering standards，生成任务相关而不是全仓库噪声上下文。
-
-## 当前边界
-
-- 当前版本不内置向量数据库；如果项目配置了 SQLite knowledge base，会使用现有召回接口。
-- 当前版本只检测 Graphify 产物是否存在并生成摘要，不主动运行 Graphify。
-- HTML 可视化报告适合后续加在 context pack 之上；Memory Fabric 的核心产物先保持 JSON/Markdown，方便 diff、测试和 CLI 集成。
-
-## Memory Provider Router
-
-SCALE now treats strong memory systems as providers instead of rebuilding them inside the workflow engine.
-
-Default provider order:
-
-```text
-agentmemory -> gbrain -> scale-local
-```
-
-Commands:
-
-```bash
-scale memory provider init
-scale memory provider status --json
-scale memory provider recall "OAuth callback Redis state" --json
-```
-
-Provider rules:
-
-- `agentmemory` and `gbrain` are external providers and start disabled until endpoint, privacy, retention, and delete boundaries are reviewed.
-- External providers are read-only by default. Writes require an explicit provider policy change.
-- `scale-local` remains the fallback provider through Memory Brain and only promotes reviewed, evidence-backed memory.
-- `memory pack` automatically includes a `provider-memory` section when provider recall returns relevant active memories.
-
-This keeps agents flexible: they can ask the router for memory before planning, verification, review, or release, while SCALE still records which provider was used and why fallback was required.
+# Memory Fabric
+
+Memory Fabric 是 SCALE 用来降低长会话 token 消耗、提升 Agent 记忆质量的上下文压缩层。它不会把所有历史文档都塞回提示词，而是按任务范围生成一个可审计的 context pack。
+
+它聚合四类信息：
+
+- Runtime Evidence：真实运行过的命令、工具、浏览器、skill、MCP 和人工验证证据。
+- Session Events：当前会话的阶段、工具使用和证据写入事件。
+- Knowledge Recall：从项目知识库召回已验证经验、规则和历史教训。
+- Project Graph：检测 `graphify-out/GRAPH_REPORT.md` 或 `.scale/graph/manifest.json`，只引用图谱状态和摘要，不把大型图谱全文塞进上下文。
+
+## 基本命令
+
+生成上下文包：
+
+```bash
+scale memory pack \
+  --task-id 2026-05-18-runtime-evidence \
+  --session-id 2026-05-18-runtime-evidence \
+  --task "继续实现 runtime evidence 与最终交付检查" \
+  --level M \
+  --files src/runtime,src/api/cli.ts \
+  --budget 4000
+```
+
+输出 JSON，便于其他 Agent、CLI 或评审工具读取：
+
+```bash
+scale memory pack \
+  --task "修复 OAuth callback state 过期处理" \
+  --level M \
+  --budget 4000 \
+  --json
+```
+
+检查上下文预算：
+
+```bash
+scale memory doctor \
+  --task "跨模块权限重构" \
+  --level L \
+  --budget 3000
+```
+
+把完成任务后的运行证据沉淀成学习候选：
+
+```bash
+scale memory settle \
+  --task-id 2026-05-18-runtime-evidence \
+  --session-id 2026-05-18-runtime-evidence \
+  --task "继续实现 runtime evidence 与最终交付检查" \
+  --level M \
+  --budget 4000
+```
+
+`settle` 会写入：
+
+```text
+.scale/memory/learning-candidates/<candidate-id>.json
+.scale/memory/learning-candidates/<candidate-id>.md
+```
+
+这些文件是本地运行时学习候选，默认不应该直接提交到 Git。它们的作用是让人类或评审 Agent 判断“这条经验是否值得进入长期知识库、工程规范或模块文档”。
+
+## 预算策略
+
+Memory Fabric 使用估算 token 预算控制上下文规模。优先级从高到低：
+
+1. Runtime Evidence：失败证据和通过证据优先保留。
+2. Session Events：最近会话事件优先保留。
+3. Knowledge Recall：按任务描述和文件范围召回 Top K 知识。
+4. Project Graph：只保留图谱报告路径和短摘要。
+
+当预算不足时，低优先级 section 会被标记为 omitted，并写入原因。这样 Agent 能知道哪些上下文被刻意裁剪，而不是误以为项目没有相关信息。
+
+## 与知识库和自我进化的关系
+
+Memory Fabric 不替代知识库。它是知识库、运行证据和图谱之间的读取层：
+
+- Runtime Evidence 记录“这次实际做过什么”。
+- Knowledge Base 记录“长期可复用的经验和规则”。
+- Graphify 或项目图谱记录“模块之间的结构关系”。
+- Memory Fabric 在每次任务开始、恢复、评审或发版前，生成本次最相关的上下文包。
+
+任务完成后，应该把真正稳定的经验沉淀到知识库或长期维护文档中；`.scale/events/` 和 `.scale/evidence/` 仍然是本地运行时产物，不应默认提交到 Git。
+
+新的推荐闭环是：
+
+```text
+runtime evidence -> memory pack -> memory settle -> 人审 -> knowledge/docs/rules
+```
+
+也就是说，Memory Fabric 先把证据和上下文压缩成候选，不会自动把一次会话里的判断升级成长期规则。存在失败证据时，候选会标记为 `resolve-failures-first`，避免把未闭环问题沉淀成“经验”。
+
+## 推荐使用场景
+
+- 长会话恢复前：先生成 context pack，避免重复读大量文档。
+- 多 Agent 协作前：把 context pack 交给审查 Agent 或测试 Agent。
+- 发版前：用 runtime evidence 和 session events 检查是否存在未闭环失败。
+- 任务结束后：用 `memory settle` 生成学习候选，再决定是否进入知识库、模块文档或工程规范。
+- 大型项目治理：结合 service matrix、resource governance 和 engineering standards，生成任务相关而不是全仓库噪声上下文。
+
+## 当前边界
+
+- 当前版本不内置向量数据库；如果项目配置了 SQLite knowledge base，会使用现有召回接口。
+- 当前版本只检测 Graphify 产物是否存在并生成摘要，不主动运行 Graphify。
+- HTML 可视化报告适合后续加在 context pack 之上；Memory Fabric 的核心产物先保持 JSON/Markdown，方便 diff、测试和 CLI 集成。
+
+## Memory Provider Router
+
+SCALE now treats strong memory systems as providers instead of rebuilding them inside the workflow engine.
+
+Default provider order:
+
+```text
+agentmemory -> gbrain -> scale-local
+```
+
+Commands:
+
+```bash
+scale memory provider init
+scale memory provider status --json
+scale memory provider recall "OAuth callback Redis state" --json
+```
+
+Provider rules:
+
+- `agentmemory` and `gbrain` are external providers and start disabled until endpoint, privacy, retention, and delete boundaries are reviewed.
+- External providers are read-only by default. Writes require an explicit provider policy change.
+- `scale-local` remains the fallback provider through Memory Brain and only promotes reviewed, evidence-backed memory.
+- `memory pack` automatically includes a `provider-memory` section when provider recall returns relevant active memories.
+
+This keeps agents flexible: they can ask the router for memory before planning, verification, review, or release, while SCALE still records which provider was used and why fallback was required.