kenaz 0.3.17 → 0.3.19

package/core/.system/memory/README.md

@@ -1,719 +0,0 @@
-> REMOVED 2026-10-11 (TASK_2411): the memory system (Synapse/Hippocampus/Cortex/Alaya recall) no longer exists in code.
-> Kept for history only; do not follow it. Lessons now: `kenaz learn` and native memory files.
-
-# .memory 記憶系統
-
-## 系統概述
-
-`.memory/` 是 Kenaz AI 專案的**智能記憶系統**，模擬人腦記憶機制，為 AI Agent 提供持久化知識儲存與檢索能力。
-
-**設計理念**：
-- **自動化記憶**：Agent 自動判斷什麼值得記憶，自動分類標籤
-- **語義檢索**：透過 Kenaz Cortex 進行語義搜尋與向量檢索
-- **雙層架構**：主記憶（跨專案）+ 專案記憶（專案專屬）
-- **優先級繼承**：專案記憶 > 主記憶 > 系統預設
-
-**核心功能**：
-```
-Agent 工作流程
-    ↓
-1. 任務開始前 → 查詢相關記憶（避免重複踩坑）
-    ↓
-2. 任務執行中 → 實時存取知識（模式、解決方案）
-    ↓
-3. 任務完成後 → 自動記錄經驗（決策、失敗、模式）
-```
-
----
-
-## 目錄結構
-
-```
-.memory/
-├── README.md                 # 本文件
-├── CORTEX_GUIDE.md           # Cortex 系統整合指南
-├── SECURITY_TOKEN_OPTIMIZATION.md  # 安全與 Token 優化
-│
-├── registry.json             # 記憶索引（元數據）
-├── access.yaml               # 存取控制配置
-├── CONTEXT.md                # 當前狀態摘要
-├── COMPLETED_TASKS.json      # 已完成任務記錄
-│
-├── decisions/                # decision 類型記憶（決策記錄）
-├── failures/                 # failure 類型記憶（失敗經驗）
-├── patterns/                 # pattern 類型記憶（可複用模式）
-├── insights/                 # insight 類型記憶（洞察理解）
-├── contexts/                 # context 類型記憶（狀態快照）
-├── references/               # reference 類型記憶（外部資源）
-│
-├── logs/                     # 記憶系統日誌
-│   └── README.md
-│
-├── config/                   # 記憶系統配置
-│   └── memory-config.yaml
-│
-├── schema/                   # 記憶條目 Schema
-│   └── memory-entry.schema.json
-│
-└── tools/                    # 記憶工具腳本
-    ├── memory-tools.js       # CRUD 工具（add, get, search, list, update, delete）
-    ├── memory-agent.js       # 自動記憶 Agent（on-task-completed, should-remember）
-    ├── README.md             # 工具使用指南
-    ├── MEMORY_AGENT_README.md  # 自動記憶機制說明
-    ├── LEARNING_MECHANISM.md   # 學習機制設計
-    └── prompts/              # Agent 使用的 Prompt 模板
-        └── auto-classify.prompt.md
-```
-
----
-
-## 雙層記憶架構
-
-### 系統架構圖
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Cortex 系統                               │
-│                                                                  │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
-│  │   記憶中心   │  │   檢索引擎   │  │   規則層     │          │
-│  │  (.memory/)  │  │(kenaz-cortex)│  │  (.rule/)    │          │
-│  │              │  │              │  │              │          │
-│  │ • 經驗儲存   │  │ • 語義搜尋   │  │ • 強制約束   │          │
-│  │ • 模式學習   │  │ • 向量檢索   │  │ • 行為規範   │          │
-│  │ • 失敗記錄   │  │ • 混合排序   │  │ • 優先級     │          │
-│  └──────────────┘  └──────────────┘  └──────────────┘          │
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │                 主記憶 (.kenaz/main-memory/)               │  │
-│  │           開發者維護 • 全局知識庫 • 唯讀繼承               │  │
-│  └──────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### 雙層架構定義
-
-| 層級 | 位置 | 性質 | 內容 | 維護方式 |
-|------|------|------|------|---------|
-| **主記憶** | `.kenaz/main-memory/` | 唯讀、全局 | Kenaz 系統知識、通用最佳實踐 | 開發者手動更新 |
-| **專案記憶** | `.memory/` | 讀寫、專案專屬 | 決策、失敗經驗、模式、洞察 | Agent 自動生成 + 開發者審查 |
-
-### 優先級繼承機制
-
-查詢記憶時遵循以下優先級：
-
-```
-1. 專案記憶 (.memory/)          ← 當前專案專屬，最高優先級
-   ↓ 專案規則覆蓋主記憶
-2. 主記憶 (.kenaz/main-memory/) ← 跨專案共享，中等優先級
-   ↓ 主記憶覆蓋系統預設
-3. 系統預設 (Claude Code 內建) ← 全局，最低優先級
-```
-
-**規則**：優先級高的記憶會覆蓋優先級低的記憶。
-
-**範例**：
-```yaml
-# 主記憶：通用 JSON BOM 問題解決方案
-K-SOL-001: "使用 fix_json.js 修復 JSON BOM 問題"
-
-# 專案記憶：專案特定的處理方式
-MEM-2026-0211-003: "本專案統一使用 PowerShell 腳本處理 BOM"
-  ↓
-# 查詢結果：專案記憶優先（專案有特定流程）
-```
-
----
-
-## 記憶類型
-
-### 類型定義
-
-| 類型 | 說明 | 觸發場景 | 範例 |
-|------|------|---------|------|
-| **decision** | 決策記錄 | 架構選型、技術決策、權衡取捨 | 選擇 React 而非 Vue 的原因 |
-| **failure** | 失敗經驗 | Bug、錯誤、踩坑經歷 | FAIL-003: TASK_QUEUE 污染問題 |
-| **pattern** | 可複用模式 | 程式碼片段、流程範本、最佳實踐 | Team 調用的標準流程 |
-| **insight** | 洞察理解 | 對系統的新認識、發現 | Cortex V2 的 4 層檢索架構 |
-| **context** | 狀態快照 | 專案當前進度、重要狀態 | 專案當前有 88 個已完成任務 |
-| **reference** | 外部資源 | 文檔連結、API 參考 | Supabase RLS 文檔連結 |
-
-### 記憶條目結構
-
-```yaml
-# 記憶條目標準格式（存儲於 .memory/<type>/MEM-YYYY-MMDD-NNN.json）
-memory_entry:
-  # ========== 基本識別 ==========
-  id: "MEM-2026-0211-001"           # 唯一 ID
-  version: 1                         # 版本號（支援更新）
-  type: "decision"                   # 記憶類型
-
-  # ========== 適用範圍 ==========
-  scope:
-    level: "feature"                 # project | feature | task | session
-    project_id: "kenaz-ai"
-    feature_id: "F-009"
-    task_id: "TASK_153"
-
-  # ========== 創建者資訊 ==========
-  actor:
-    agent_type: "strategy"           # 創建的 Agent 類型
-    formation: "squad"               # 所屬陣型
-    session_id: "sess_abc123"
-
-  # ========== 時間軸 ==========
-  temporal:
-    created_at: "2026-02-11T10:30:00Z"
-    updated_at: "2026-02-11T10:30:00Z"
-    last_accessed: "2026-02-11T12:00:00Z"
-    access_count: 5
-
-  # ========== 重要性評分 ==========
-  scoring:
-    importance: 4                    # 1-5，Agent 評估
-    confidence: 0.85                 # 0-1，正確性信心度
-
-  # ========== 關聯性 ==========
-  relations:
-    - target_id: "MEM-2026-0210-005"
-      relation_type: "extends"       # extends | contradicts | supports | replaces
-      confidence: 0.9
-
-  # ========== 語義標籤 ==========
-  tags: ["architecture", "formation-system", "performance"]
-
-  # ========== 實際內容 ==========
-  content:
-    title: "Formation 系統採用多陣型模式的原因"
-    summary: "選擇 unit/solo/squad/legion 四種陣型而非單一模式..."
-    full: |
-      ## 決策背景
-      在設計 Formation 系統時，考慮了多種協作模式...
-
-  # ========== 向量嵌入（Cortex 使用） ==========
-  embedding:
-    model: "text-embedding-3-small"
-    vector: [0.123, -0.456, ...]
-
-  # ========== 元數據 ==========
-  meta:
-    source_file: ".formation/solo/strategy.yaml"
-    git_commit: "abc123"
-    checksum: "sha256:..."
-```
-
----
-
-## Agent 使用指南
-
-### 核心規則：AGT-001
-
-**遵循 AGT-001 規則：記憶點優先**（定義於 `.rule/general/agent-workflow.yaml`）
-
-> **任務開始前必須檢查 .memory/ 是否有相關記憶，避免重複做已經做過的事。**
-
-### 使用場景
-
-#### 1. 任務開始前（查詢記憶）
-
-**必須執行**：檢查相關記憶，避免重複錯誤
-
-```bash
-# 方法 1：語義搜尋（推薦）
-node .memory/tools/memory-tools.js search "團隊調用"
-
-# 方法 2：按類型過濾
-node .memory/tools/memory-tools.js search "" --type decision
-
-# 方法 3：按重要性過濾
-node .memory/tools/memory-tools.js search "" --minImportance 4
-
-# 方法 4：組合搜尋
-node .memory/tools/memory-tools.js search "架構" --type decision --minImportance 3
-```
-
-**輸出結果**：
-- 匹配的記憶數量
-- 記憶標題、摘要、重要性
-- 相關標籤與關聯記憶
-
-**範例輸出**：
-```
-Found 3 memories matching "團隊調用":
-
-1. MEM-2026-0211-005 (decision) - Importance: 4
-   Title: "Team 調用標準流程"
-   Summary: "使用 run-team.js --team=X --task=Y 調用 Team..."
-   Tags: team, workflow, formation
-
-2. MEM-2026-0210-012 (pattern) - Importance: 3
-   Title: "Leader-Worker 協作模式"
-   Summary: "Leader 負責協調，Worker 獨立執行任務..."
-   Tags: pattern, team, architecture
-```
-
-#### 2. 任務執行中（存取記憶）
-
-```bash
-# 獲取特定記憶的完整內容
-node .memory/tools/memory-tools.js get MEM-2026-0211-001
-
-# 列出所有記憶
-node .memory/tools/memory-tools.js list
-
-# 列出特定類型的記憶
-node .memory/tools/memory-tools.js list --type failure
-```
-
-#### 3. 任務完成後（記錄記憶）
-
-**自動記憶觸發**（由 Formation 系統自動調用）：
-
-```bash
-# 任務完成時自動評估是否需要記憶
-node .memory/tools/memory-agent.js on-task-completed \
-  --task-id TASK_158 \
-  --summary "記憶系統基礎架構完成"
-```
-
-**手動記憶操作**（Agent 或開發者）：
-
-```bash
-# 記錄決策
-node .memory/tools/memory-tools.js add \
-  --type decision \
-  --title "選擇 React 框架" \
-  --summary "因為生態系成熟、團隊熟悉度高" \
-  --importance 4 \
-  --tags "frontend,architecture"
-
-# 記錄失敗經驗
-node .memory/tools/memory-tools.js add \
-  --type failure \
-  --title "並行任務衝突" \
-  --summary "同時啟動兩個 Team 會覆蓋 state.json" \
-  --importance 5 \
-  --tags "pipeline,concurrency"
-
-# 記錄可複用模式
-node .memory/tools/memory-tools.js add \
-  --type pattern \
-  --title "Team 調用標準流程" \
-  --summary "使用 run-team.js --team=X --task=Y" \
-  --importance 3 \
-  --tags "team,workflow"
-```
-
-#### 4. 更新記憶
-
-```bash
-# 更新記憶內容
-node .memory/tools/memory-tools.js update MEM-2026-0211-001 \
-  --title "新標題" \
-  --importance 5 \
-  --tags "new,tags"
-```
-
-#### 5. 刪除記憶
-
-```bash
-# 刪除記憶（慎用）
-node .memory/tools/memory-tools.js delete MEM-2026-0211-001
-```
-
----
-
-## Cortex 檢索層級
-
-Agent 查詢時，Cortex 按以下層級處理：
-
-```
-Agent 查詢 Cortex
-    ↓
-Layer 1: 規則層（.rule/, CLAUDE.md, .failure/）
-    ↓
-Layer 1.5: 記憶層（.memory/）← 自動載入高重要性記憶
-    ↓
-Layer 2-4: 架構層、智能檢索層、全局驗證層
-```
-
-### 智能載入策略
-
-**根據任務類型動態調整載入深度：**
-
-| 任務類型 | 載入記憶數 | 載入字段 | Max Tokens |
-|---------|-----------|---------|------------|
-| **簡單任務** | 5 | title, summary | 500 |
-| **P2/P3 任務** | 10 | title, summary, tags | 1000 |
-| **P0/P1 任務** | 15-20 | title, summary, full, relations | 2000 |
-
-**混合排序策略**：
-
-```python
-score = relevance * 0.5 + recency * 0.2 + importance * 0.3
-```
-
-- **relevance**: 語義相似度（向量距離）
-- **recency**: 時間衰減（70 天半衰期）
-- **importance**: 重要性分數（1-5）
-
----
-
-## 重要性評分指南
-
-### 評分標準
-
-| 分數 | 說明 | 適用場景 |
-|------|------|---------|
-| **5** | 極重要 | 架構決策、核心原則、關鍵失敗 |
-| **4** | 很重要 | 功能設計、重要模式、嚴重問題 |
-| **3** | 中等 | 一般決策、常用模式、中等問題 |
-| **2** | 較低 | 小優化、輔助資訊、小問題 |
-| **1** | 最低 | 臨時筆記、瑣碎資訊 |
-
-### 自動評估機制
-
-```javascript
-// .memory/tools/memory-agent.js
-
-function calculateImportance(event) {
-  let score = 3; // 預設中等
-
-  // 規則 1：失敗必記（+2）
-  if (event.type === 'failure') score += 2;
-
-  // 規則 2：架構決策（+2）
-  if (event.type === 'decision' && event.scope.level === 'project') score += 2;
-
-  // 規則 3：可複用模式（+1）
-  if (event.type === 'pattern' && event.reuse_count > 1) score += 1;
-
-  // 規則 4：影響範圍（+1）
-  if (event.scope.level === 'global') score += 1;
-
-  return Math.min(5, score); // 限制最大值 5
-}
-```
-
----
-
-## 安全性
-
-### 敏感資訊過濾
-
-寫入記憶時自動過濾敏感資訊：
-
-```javascript
-// .memory/tools/security-filter.js
-
-const patterns = [
-  /sk-[a-zA-Z0-9]{48}/g,        // OpenAI API Key
-  /password\s*[=:]\s*\S+/gi,    // 密碼
-  /token\s*[=:]\s*[a-zA-Z0-9]+/gi, // Token
-  /supabase.*key.*anon/gi,      // Supabase Anon Key
-];
-
-function filterSensitive(content) {
-  let filtered = content;
-  for (const pattern of patterns) {
-    filtered = filtered.replace(pattern, '[REDACTED]');
-  }
-  return filtered;
-}
-```
-
-### 專案隔離
-
-- 每個專案使用獨立的記憶系統（`.memory/` 目錄）
-- Cortex 使用專案 hash 作為 Collection 名稱
-- 專案 A 的記憶在專案 B 中不可見
-
-### 存取控制
-
-```yaml
-# .memory/access.yaml
-
-access_control:
-  read:
-    - all_agents       # 所有 Agent 可讀取
-    - human_developers # 所有開發者可讀取
-  write:
-    - agents:          # Agent 可自動寫入
-        - strategy
-        - developer
-        - backend
-        - formation_lead
-    - human_developers # 開發者手動寫入
-  delete:
-    - human_developers # 僅開發者可刪除
-```
-
----
-
-## Token 優化策略
-
-### 智能裁剪
-
-根據任務優先級動態調整：
-
-```yaml
-# P0/P1 任務（高優先級）
-high_priority:
-  max_memories: 20
-  fields: [title, summary, full, relations]
-  max_tokens_per_memory: 150
-  total_max_tokens: 2000
-
-# P2/P3 任務（中優先級）
-medium_priority:
-  max_memories: 10
-  fields: [title, summary]
-  max_tokens_per_memory: 80
-  total_max_tokens: 1000
-
-# 簡單任務（低優先級）
-low_priority:
-  max_memories: 5
-  fields: [title, summary]
-  max_tokens_per_memory: 50
-  total_max_tokens: 500
-```
-
-### Session 快取
-
-```javascript
-// 同一 session 內避免重複查詢
-const cache = new Map();
-
-function getCachedMemory(query) {
-  const cacheKey = hash(query);
-  if (cache.has(cacheKey)) {
-    return cache.get(cacheKey);
-  }
-  const result = queryMemory(query);
-  cache.set(cacheKey, result);
-  return result;
-}
-```
-
-詳細優化策略參考：`.memory/SECURITY_TOKEN_OPTIMIZATION.md`
-
----
-
-## 與其他系統的關係
-
-### 優先級順序
-
-```
-1. .rule/      (最高優先級 - 必須遵守的規則)
-2. .failure/   (失敗經驗 - 應避免的模式)
-3. .memory/    (經驗記錄 - 參考學習)
-4. CLAUDE.md   (專案指導 - 工作流程)
-```
-
-### 與 .failure/ 的關係
-
-- `.failure/` 是傳統的失敗記錄系統（YAML 格式）
-- `.memory/failures/` 整合了 `.failure/` 的內容（JSON 格式）
-- 新的失敗經驗優先記錄到 `.memory/failures/`
-- 兩個系統可以共存，Cortex 同時索引兩處
-
-**遷移方向**：
-```
-.failure/ (YAML) → .memory/failures/ (JSON + Cortex 索引)
-```
-
-### 與 kenaz-cortex 的關係
-
-- 記憶系統作為 **Layer 1.5** 整合到 Cortex
-- 使用 ChromaDB 進行向量存儲
-- 支持語義檢索和混合排名
-
-**整合架構**：
-```
-Cortex 檢索引擎
-    ↓
-Layer 1.5: 記憶層 (.memory/)
-    ↓
-ChromaDB 向量資料庫
-```
-
----
-
-## 工作流程整合
-
-### Agent 執行前（查詢記憶）
-
-```bash
-# 查詢失敗經驗（避免重複錯誤）
-node .memory/tools/memory-tools.js search \
-  --query="與任務相關的失敗" \
-  --type=failure \
-  --limit=5
-
-# 查詢成功模式（參考有效方法）
-node .memory/tools/memory-tools.js search \
-  --query="任務關鍵詞" \
-  --type=pattern \
-  --limit=5
-```
-
-### Agent 執行完成後（自動記憶）
-
-```javascript
-// Formation 系統自動調用
-node .memory/tools/memory-agent.js on-task-completed \
-  --task-id TASK_158 \
-  --summary "記憶系統基礎架構完成"
-
-// 自動判斷：
-// - 成功 → 記錄為 pattern 類型
-// - 失敗 → 記錄為 failure 類型
-// - 決策 → 記錄為 decision 類型
-```
-
-### 定期維護（每週）
-
-```bash
-# 檢視所有記憶
-node .memory/tools/memory-tools.js list --limit=100
-
-# 清理過時記憶（手動評估）
-node .memory/tools/memory-tools.js search "" --minImportance 1 | \
-  grep "2025" | \
-  # 檢視後決定是否刪除
-```
-
----
-
-## 常見問題（FAQ）
-
-### Q1: 記憶會自動刪除嗎？
-
-**A**: 不會。所有記憶永久保留，需手動管理。建議定期檢視低重要性記憶（importance < 2）並決定是否刪除。
-
-### Q2: 如何避免記憶爆炸？
-
-**A**: 透過以下機制控制：
-1. **智能裁剪**：只載入相關記憶（混合排序 top-K）
-2. **重要性評分**：低重要性記憶不會被 Cortex 優先載入
-3. **Token 限制**：動態調整載入深度（簡單任務 500 tokens，複雜任務 2000 tokens）
-
-### Q3: 專案記憶和主記憶有什麼區別？
-
-**A**:
-- **專案記憶** (`.memory/`)：專案專屬，Agent 自動生成，讀寫
-- **主記憶** (`.kenaz/main-memory/`)：跨專案共享，開發者維護，唯讀
-
-查詢時專案記憶優先。
-
-### Q4: 如何更新主記憶？
-
-**A**: 主記憶僅開發者手動更新：
-1. 在 `.kenaz/main-memory/` 對應目錄建立 Markdown 文件
-2. 更新 `registry.json` 新增索引條目
-3. 更新 `version.yaml` 記錄變更
-4. 建立 Git commit
-
-### Q5: 記憶工具不存在怎麼辦？
-
-**A**:
-```bash
-# 檢查記憶工具
-ls .memory/tools/
-
-# 如果不存在，參考 docs/specs/MEMORY_SYSTEM_SPEC.md 建立基礎架構
-```
-
----
-
-## 故障排查
-
-### 記憶工具不存在
-
-```bash
-# 檢查記憶工具
-ls .memory/tools/
-
-# 如果不存在，執行 TASK_158 建立基礎架構
-```
-
-### 查詢無結果
-
-```bash
-# 檢查 registry.json
-cat .memory/registry.json
-
-# 確認記憶已被索引
-node .memory/tools/memory-tools.js list --limit=100
-```
-
-### Cortex 整合問題
-
-```bash
-# 檢查 Cortex 狀態
-python kenaz-cortex/src/cortex/api/status.py
-
-# 重新索引記憶
-python kenaz-cortex/src/cortex/retrieval/memory_layer.py --reindex
-```
-
----
-
-## 最佳實踐
-
-1. **定期記錄決策** - 重要的技術決策應立即記錄
-2. **失敗必記** - 所有失敗經驗都值得記憶（AGT-005）
-3. **避免過度記憶** - 只記錄有價值的信息（importance >= 3）
-4. **定期清理** - 刪除過時或不再相關的記憶
-5. **善用標籤** - 使用一致的標籤系統便於查詢
-6. **記憶點優先** - 任務開始前必須查詢記憶（AGT-001）
-
----
-
-## 相關文檔
-
-| 文檔 | 路徑 | 說明 |
-|------|------|------|
-| **Cortex 整合指南** | `.memory/CORTEX_GUIDE.md` | Cortex 系統架構與使用方式 |
-| **記憶工具使用指南** | `.memory/tools/README.md` | CRUD 工具詳細使用說明 |
-| **自動記憶機制** | `.memory/tools/MEMORY_AGENT_README.md` | 自動記憶觸發與評估機制 |
-| **安全與優化** | `.memory/SECURITY_TOKEN_OPTIMIZATION.md` | 安全過濾與 Token 優化策略 |
-| **完整規格** | `docs/specs/MEMORY_SYSTEM_SPEC.md` | 記憶系統完整需求規格 |
-| **主記憶說明** | `.kenaz/main-memory/README.md` | 主記憶系統架構與使用 |
-| **規則系統** | `.system/rule/README.md` | 規則優先級與 AGT-001 規則 |
-| **失敗學習系統** | `.system/failure/README.md` | 失敗經驗與 .failure/ 關係 |
-
----
-
-## 統計數據（截至 2026-02-19）
-
-```yaml
-# 專案記憶統計
-project_memory:
-  total_memories: 12
-  by_type:
-    decision: 3
-    failure: 5
-    pattern: 2
-    insight: 1
-    context: 1
-    reference: 0
-  by_importance:
-    5: 2    # 極重要
-    4: 4    # 很重要
-    3: 4    # 中等
-    2: 1    # 較低
-    1: 1    # 最低
-  total_access_count: 48
-
-# 主記憶統計（來自 .kenaz/main-memory/）
-main_memory:
-  total_memories: 26
-  knowledge: 8    # 通用知識
-  kenaz: 18       # 系統專屬知識
-```
-
----
-
-*建立日期: 2026-02-19 | 更新: 2026-02-19*