Skill: chen-feng123/cognitive-enhancement-engine (version 1.0.2)

--- name: cognitive-enhancement-engine description: AI Agent cognitive enhancement engine with working memory, TF-IDF vector memory, planning, reasoning, reflection, and metacognitive monitoring. Zero external dependencies. Pure Python stdlib. --- # Cognitive Enhancement Engine (认知力增强引擎) Lightweight AI Agent cognitive engine with working memory, TF-IDF vector memory, planning, reasoning, reflection, and metacognitive monitoring. **Zero external dependencies** — pure Python standard library. ## Quick Start ```bash # Run built-in demo python skills/cognitive-enhancement-engine/engine.py # Or one-click setup bash skills/cognitive-enhancement-engine/scripts/setup.sh # Linux/macOS/WSL skills\cognitive-enhancement-engine\scripts\setup.bat # Windows ``` ## Core Usage ```python from engine import CognitiveEnhancer # Create engine brain = CognitiveEnhancer(long_term_capacity=1000) # Learn brain.memorize("Paris is the capital of France.", importance=0.9) brain.perceive("User asked about French capital") # Retrieve results = brain.recall("capital of France", top_k=3) # Plan plan = brain.plan("Build a web application") # Reason answer = brain.reason("What is the capital of France?") # Reflect suggestions = brain.reflect() # Full task execution result = brain.execute_task("Calculate 15% tip on $200 bill") print(result) # Status status = brain.get_status() ``` ## API Overview | Method | Description | |--------|-------------| | `perceive(observation)` | Store perception into working memory | | `recall(query, top_k)` | Search long-term memory | | `memorize(content, importance)` | Store into long-term memory | | `plan(goal)` | Decompose goal into actionable steps | | `reason(problem)` | Memory-based reasoning | | `reflect()` | Discover failure patterns, suggest improvements | | `execute_task(goal, executor)` | End-to-end task execution | | `get_status()` | Return engine runtime status | ## Configuration | Parameter | Default | Description | |-----------|---------|-------------| | `long_term_capacity` | 1000 | Max long-term memories | | `working_memory_size` | 10 | Working memory FIFO size | | `similarity_threshold` | 0.15 | Recall similarity threshold | ## Features - **TF-IDF Vector Memory** — Inverted-index fast similarity search - **Working Memory** — FIFO short-term context cache - **Planner** — Goal decomposition + automatic task type detection (calculate/search/summarize/translate/write) - **Reasoner** — Memory-retrieval based Q&A - **Reflector** — Failure pattern tracking and root cause mining - **Metacognitive Monitor** — Task duration & error rate tracking, dynamic adjustment ## Installation | Method | Command | |--------|---------| | One-click (Linux/macOS) | `bash scripts/setup.sh` | | One-click (Windows) | `scripts\setup.bat` | | Copy-only | Copy `engine.py` to your project | | ClawHub | `clawhub install cognitive-enhancement-engine` | ## File Structure ``` cognitive-enhancement-engine/ ├── SKILL.md ├── engine.py # Core engine (~17KB) ├── index.js # Node.js bridge ├── package.json ├── assets/ │ └── icon.svg ├── references/ │ ├── API_SPEC.md │ └── USE_GUIDE.md └── scripts/ ├── setup.sh ├── setup.bat ├── test-basic.py └── test-client.js ``` ## License MIT

path: engine.py
content: """
认知力增强引擎（高性能优化版）
为AI Agent提供记忆、规划、推理、反思与元认知能力
"""
from __future__ import annotations
import hashlib
import heapq
import math
import re
import time
from collections import defaultdict, deque
from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Callable, Deque, Dict, List, Optional, Set, Tuple, Union


# ======================= 分词器 =======================

class Tokenizer:
    """统一分词工具（中英文基础）"""
    @staticmethod
    def tokenize(text: str) -> List[str]:
        if not text:
            return []
        text = text.lower()
        words = re.findall(r"[a-zA-Z0-9\u4e00-\u9fa5]+", text)
        return [w for w in words if len(w) > 1 or w.isdigit()]


# ======================= 长期记忆（高性能向量检索）=======================

class VectorMemory:
    """
    基于TF-IDF和倒排索引的长期记忆存储
    - 添加时预处理tokens并预计算向量范数
    - 检索时仅扫描包含查询中任一token的候选记忆，大幅加速
    """
    def __init__(self, capacity: int = 1000, similarity_threshold: float = 0.15):
        self.capacity = capacity
        self.similarity_threshold = similarity_threshold
        self.memories: Dict[str, Dict] = {}  # id -> {content, metadata, importance, tokens, norm, ts, access}
        self.inverted_index: Dict[str, Set[str]] = defaultdict(set)
        self._idf_dirty = True
        self._idf_cache: Dict[str, float] = {}
        self.tokenizer = Tokenizer()

    def add(self, content: str, metadata: Optional[Dict] = None, importance: float = 1.0) -> str:
        """添加记忆，返回唯一标识"""
        if not content or not content.strip():
            raise ValueError("Memory content cannot be empty")
        if metadata is None:
            metadata = {}
        mem_id = hashlib.md5(f"{content}{time.time()}{id(self)}".encode()).hexdigest()[:12]

        token_list = self.tokenizer.tokenize(content)
        token_set = set(token_list)
        if not token_set:
            raise ValueError("Memory content has no valid tokens")

        if len(self.memories) >= self.capacity:
            self._evict()

        self.memories[mem_id] = {
            "content": content,
            "metadata": metadata,
            "importance": min(1.0, max(0.0, importance)),
            "timestamp": time.time(),
            "access_count": 0,
            "tokens": token_list,
            "norm": 0.0,  # 延迟计算（依赖于idf）
        }

        for token in token_set:
            self.inverted_index[token].add(mem_id)
        self._idf_dirty = True
        return mem_id

    def get(self, mem_id: str) -> Optional[Dict]:
        mem = self.memories.get(mem_id)
        if mem:
            mem["access_count"] += 1
        return mem

    def retrieve(self, query: str, top_k: int = 5) -> List[Tuple[Dict, float]]:
        """检索相似记忆，返回 (记忆内容, 相似度) 列表"""
        if not self.memories:
            return []

        query_tokens = set(self.tokenizer.tokenize(query))
        if not query_tokens:
            return []

        # 使用倒排索引缩小候选集：至少包含一个查询token的记忆
        candidate_ids = set()
        for token in query_tokens:
            candidate_ids.update(self.inverted_index.get(token, set()))
        if not candidate_ids:
            return []

        # 更新IDF并计算各记忆的范数（惰性计算）
        idf = self._get_idf()
        query_vec = {tok: idf.get(tok, 0.0) for tok in query_tokens}
        query_norm = math.sqrt(sum(v * v for v in query_vec.values()))

        scores = []
        for mem_id in candidate_ids:
            mem = self.memories[mem_id]
            # 计算该记忆的向量（基于当前idf）和范数
            mem_vec = {tok: idf.get(tok, 0.0) for tok in mem["tokens"]}
            if mem["norm"] == 0.0:
                mem["norm"] = math.sqrt(sum(v * v for v in mem_vec.values()))
            norm_mem = mem["norm"]
            if norm_mem == 0.0:
                continue

            # 余弦相似度
            dot = sum(query_vec.get(tok, 0.0) * mem_vec.get(tok, 0.0) for tok in set(query_vec) & set(mem_vec))
            raw_sim = dot / (query_norm * norm_mem) if query_norm > 0 else 0.0

            # 综合重要性与访问热度
            adjusted = raw_sim * (0.7 + 0.3 * mem["importance"]) * (0.9 + 0.1 * math.log(mem["access_count"] + 1))
            if adjusted > self.similarity_threshold:
                scores.append((mem, adjusted))

        scores.sort(key=lambda x: x[1], reverse=True)
        return scores[:top_k]

    def _get_idf(self) -> Dict[str, float]:
        if not self._idf_dirty and self._idf_cache:
            return self._idf_cache
        n = len(self.memories)
        idf = {}
        for token, docs in self.inverted_index.items():
            idf[token] = math.log((n + 1) / (len(docs) + 1)) + 1
        self._idf_cache = idf
        self._idf_dirty = False
        return idf

    def _evict(self):
        """淘汰最不重要的记忆（基于重要性、访问次数、时效）"""
        if not self.memories:
            return
        now = time.time()
        scored = []
        for mem_id, mem in self.memories.items():
            age = now - mem["timestamp"]
            score = mem["importance"] * (mem["access_count"] + 1) / (age + 1)
            scored.append((score, mem_id))
        heapq.heapify(scored)
        _, worst_id = heapq.heappop(scored)
        self._remove(worst_id)

    def _remove(self, mem_id: str):
        if mem_id not in self.memories:
            return
        mem = self.memories[mem_id]
        for token in set(mem["tokens"]):
            docs = self.inverted_index.get(token)
            if docs:
                docs.discard(mem_id)
                if not docs:
                    del self.inverted_index[token]
        del self.memories[mem_id]
        self._idf_dirty = True


# ======================= 工作记忆 =======================

class WorkingMemory:
    """短期上下文（FIFO）"""
    def __init__(self, capacity: int = 20):
        self.buffer: Deque[Dict] = deque(maxlen=capacity)

    def add(self, item: Dict):
        self.buffer.append(item)

    def get_recent(self, n: int = 10) -> List[Dict]:
        return list(self.buffer)[-n:]

    def clear(self):
        self.buffer.clear()


# ======================= 规划器 =======================

@dataclass
class PlanStep:
    description: str
    dependencies: List[int] = field(default_factory=list)
    status: str = "pending"  # pending, running, done, failed


class Planner:
    """将目标分解为可执行步骤，支持自定义分解器"""

    DEFAULT_KEYWORDS = {
        "calculate": ["calculate", "compute", "solve", "math"],
        "search": ["search", "find", "lookup", "query"],
        "summarize": ["summarize", "summary", "abstract"],
        "translate": ["translate", "language"],
        "write": ["write", "compose", "draft"],
    }

    def __init__(self, custom_decomposer: Optional[Callable[[str], List[str]]] = None):
        self.custom_decomposer = custom_decomposer

    def decompose(self, goal: str) -> List[PlanStep]:
        if self.custom_decomposer:
            return [PlanStep(desc) for desc in self.custom_decomposer(goal)]
        lower_goal = goal.lower()
        for category, keywords in self.DEFAULT_KEYWORDS.items():
            if any(kw in lower_goal for kw in keywords):
                return self._get_steps_for_category(category)
        return [PlanStep("Analyze problem"), PlanStep("Outline solution"), PlanStep("Execute"), PlanStep("Review")]

    def _get_steps_for_category(self, category: str) -> List[PlanStep]:
        steps_map = {
            "calculate": ["Gather data", "Perform calculation", "Verify result"],
            "search": ["Generate query", "Execute search", "Filter results"],
            "summarize": ["Read source", "Extract key points", "Write summary"],
            "translate": ["Detect language", "Translate text", "Proofread"],
            "write": ["Outline structure", "Draft content", "Revise and polish"],
        }
        return [PlanStep(desc) for desc in steps_map.get(category, ["Analyze", "Execute", "Evaluate"])]

    def validate_plan(self, plan: List[PlanStep]) -> bool:
        n = len(plan)
        indeg = [0] * n
        graph = defaultdict(list)
        for i, step in enumerate(plan):
            for dep in step.dependencies:
                if dep < 0 or dep >= n:
                    return False
                graph[dep].append(i)
                indeg[i] += 1
        q = deque([i for i in range(n) if indeg[i] == 0])
        visited = 0
        while q:
            u = q.popleft()
            visited += 1
            for v in graph[u]:
                indeg[v] -= 1
                if indeg[v] == 0:
                    q.append(v)
        return visited == n


# ======================= 推理器 =======================

class Reasoner:
    """基于记忆检索的简单问答引擎"""
    def __init__(self, memory: VectorMemory):
        self.memory = memory

    def query(self, question: str, context: Optional[List[str]] = None) -> List[str]:
        results = self.memory.retrieve(question, top_k=3)
        return [mem["content"] for mem, _ in results]


# ======================= 反思引擎 =======================

class ReflectionEngine:
    """记录成败并挖掘重复失败模式"""
    def __init__(self, memory: VectorMemory, max_failure_log: int = 50):
        self.memory = memory
        self.failure_log: Deque[Dict] = deque(maxlen=max_failure_log)

    def record_outcome(self, goal: str, plan: List[PlanStep], success: bool, feedback: str = ""):
        entry = {
            "goal": goal,
            "plan": [s.description for s in plan],
            "success": success,
            "feedback": feedback,
            "timestamp": datetime.now().isoformat(),
        }
        self.failure_log.append(entry)
        if not success:
            summary = f"Failed: '{goal}'. Reason: {feedback}. Avoid plan: {entry['plan']}"
            self.memory.add(summary, metadata={"type": "reflection", "success": False}, importance=0.8)

    def generate_insights(self) -> List[str]:
        failures = [e for e in self.failure_log if not e["success"]]
        if len(failures) < 2:
            return ["Not enough data for insights (need ≥2 failures)."]
        goal_counts = defaultdict(int)
        for f in failures:
            goal_counts[f["goal"]] += 1
        suggestions = []
        for goal, cnt in goal_counts.items():
            if cnt >= 2:
                suggestions.append(f"Goal '{goal}' failed {cnt} times → consider alternative strategy.")
        if not suggestions:
            suggestions.append("No recurring failure pattern; try adjusting memory/similarity threshold.")
        return suggestions


# ======================= 元认知监控 =======================

class MetaCognitiveMonitor:
    """监控任务耗时和错误率，动态建议参数调整"""
    def __init__(self, history_size: int = 100):
        self.history: Deque[float] = deque(maxlen=history_size)
        self.error_rate = 0.0
        self.consecutive_failures = 0

    def record_task_performance(self, duration: float, success: bool):
        self.history.append(duration)
        if not success:
            self.error_rate = 0.9 * self.error_rate + 0.1 * 1.0
            self.consecutive_failures += 1
        else:
            self.error_rate = 0.9 * self.error_rate + 0.0
            self.consecutive_failures = 0

    def suggest_adjustments(self) -> Dict[str, str]:
        adj = {}
        if len(self.history) >= 10 and sum(self.history) / len(self.history) > 5.0:
            adj["working_memory"] = "reduce capacity"
        if self.error_rate > 0.3:
            adj["reasoning"] = "increase depth"
            adj["reflection"] = "increase frequency"
        if self.consecutive_failures > 2:
            adj["planning"] = "use more cautious strategy"
        return adj


# ======================= 主引擎 =======================

class CognitiveEnhancer:
    """AI Agent认知力增强引擎（高性能版）"""
    def __init__(
        self,
        long_term_capacity: int = 1000,
        working_capacity: int = 20,
        similarity_threshold: float = 0.15,
        auto_reflect_interval: int = 10,
    ):
        self.long_term_memory = VectorMemory(long_term_capacity, similarity_threshold)
        self.working_memory = WorkingMemory(working_capacity)
        self.planner = Planner()
        self.reasoner = Reasoner(self.long_term_memory)
        self.reflection = ReflectionEngine(self.long_term_memory)
        self.meta_monitor = MetaCognitiveMonitor()
        self.auto_reflect_interval = auto_reflect_interval
        self._task_counter = 0

    def perceive(self, observation: Union[str, Dict]) -> None:
        """将感知信息存入工作记忆"""
        if isinstance(observation, str):
            obs = {"type": "observation", "content": observation, "timestamp": time.time()}
        else:
            obs = observation.copy()
            obs["timestamp"] = time.time()
        self.working_memory.add(obs)

    def recall(self, query: str, top_k: int = 3) -> List[Dict]:
        """从长期记忆中检索相关内容"""
        return [mem for mem, _ in self.long_term_memory.retrieve(query, top_k)]

    def memorize(self, content: str, importance: float = 1.0, metadata: Optional[Dict] = None) -> str:
        """存入长期记忆"""
        return self.long_term_memory.add(content, metadata, importance)

    def plan(self, goal: str) -> List[PlanStep]:
        """生成执行计划"""
        steps = self.planner.decompose(goal)
        if not self.planner.validate_plan(steps):
            raise ValueError("Invalid plan: circular dependency detected")
        self.working_memory.add({"type": "plan", "goal": goal, "steps": [s.description for s in steps]})
        return steps

    def reason(self, problem: str) -> List[str]:
        """基于记忆进行推理"""
        return self.reasoner.query(problem)

    def reflect(self) -> List[str]:
        """主动反思，生成改进建议"""
        insights = self.reflection.generate_insights()
        for ins in insights:
            if "Not enough" not in ins:
                self.memorize(f"Reflection: {ins}", importance=0.6, metadata={"type": "insight"})
        return insights

    def execute_task(self, goal: str, executor: Optional[Callable[[PlanStep], None]] = None) -> Dict[str, Any]:
        """
        完整执行一项任务：规划 → 执行（可注入执行器） → 记录 → 反思 → 元监控
        :param executor: 可选的可调用对象，接收PlanStep并执行实际动作
        """
        start = time.time()
        plan: List[PlanStep] = []
        success = True
        feedback = ""
        try:
            plan = self.plan(goal)
            for step in plan:
                step.status = "running"
                if executor:
                    executor(step)
                step.status = "done"
            self.working_memory.add({"type": "task_result", "goal": goal, "success": True})
        except Exception as e:
            success = False
            feedback = str(e)
            self.working_memory.add({"type": "task_result", "goal": goal, "success": False, "error": feedback})
        duration = time.time() - start
        self.meta_monitor.record_task_performance(duration, success)
        self.reflection.record_outcome(goal, plan, success, feedback)
        self._task_counter += 1
        if self._task_counter % self.auto_reflect_interval == 0:
            self.reflect()
        adjustments = self.meta_monitor.suggest_adjustments()
        if adjustments:
            self.working_memory.add({"type": "meta_suggestion", "adjustments": adjustments})
        return {
            "goal": goal,
            "success": success,
            "duration": round(duration, 3),
            "feedback": feedback,
            "meta_adjustments": adjustments,
        }

    def get_status(self) -> Dict:
        """返回引擎当前状态"""
        return {
            "long_term_memories": len(self.long_term_memory.memories),
            "working_memories": len(self.working_memory.buffer),
            "tasks_executed": self._task_counter,
            "error_rate": round(self.meta_monitor.error_rate, 3),
            "consecutive_failures": self.meta_monitor.consecutive_failures,
        }


# ======================= 演示与测试 =======================

if __name__ == "__main__":
    brain = CognitiveEnhancer(long_term_capacity=500, auto_reflect_interval=3)
    brain.perceive("User: What is the capital of France?")
    brain.memorize("Paris is the capital of France.", importance=0.9)
    recalled = brain.recall("France capital")
    print("Recalled:", [r["content"] for r in recalled])
    answers = brain.reason("capital of France")
    print("Reasoning result:", answers)
    result = brain.execute_task("Calculate 15% tip on $200 bill")
    print("Task result:", result)
    print("Reflection insights:", brain.reflect())
    print("Engine status:", brain.get_status())
    for i in range(3):
        brain.execute_task(f"Dummy task {i+1}")
    print("Final status:", brain.get_status())


path: index.js
content: /**
 * Cognitive Enhancement Engine — pure Node.js info module
 * Pure Python engine. This file provides metadata only.
 */
const path = require('path');

/**
 * Get engine info and capabilities.
 */
function info() {
  return {
    name: 'cognitive-enhancement-engine',
    version: '1.0',
    description: 'AI Agent cognitive enhancement with memory, planning, reasoning, reflection, and metacognition',
    language: 'Python 3',
    dependencies: 'none (stdlib only)',
    features: [
      'TF-IDF long-term memory with inverted index',
      'Working memory (FIFO short-term context cache)',
      'Planner with task type auto-detection',
      'Reasoner with retrieval-augmented QA',
      'Reflection engine with failure pattern mining',
      'Metacognitive monitor: task duration + error rate tracking',
      'Zero external dependencies (pure Python stdlib)'
    ],
    usage: `from engine import CognitiveEnhancer
brain = CognitiveEnhancer(long_term_capacity=1000)
brain.memorize("Paris is the capital of France.", importance=0.9)
result = brain.execute_task("Calculate 15% tip on $200 bill")`,
    run: 'python engine.py',
    test: 'python scripts/test-basic.py'
  };
}

module.exports = { info };


path: package.json
content: {
  "name": "cognitive-enhancement-engine",
  "version": "1.0.0",
  "description": "AI Agent cognitive enhancement engine with working memory, TF-IDF vector memory, planning, reasoning, reflection, and metacognition. Zero external dependencies.",
  "main": "index.js",
  "dependencies": {},
  "keywords": [
    "cognitive-enhancement",
    "memory",
    "planning",
    "reasoning",
    "reflection",
    "metacognition",
    "ai-agent",
    "vector-memory",
    "tf-idf"
  ],
  "author": "ZhouYi",
  "license": "MIT"
}


path: scripts/setup.sh
content: #!/usr/bin/env bash
# Cognitive Enhancement Engine - One-click Setup
# Platforms: Linux / macOS / Windows (Git Bash / WSL)
set -e

DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ENGINE_PY="$DIR/engine.py"

echo "=== Cognitive Enhancement Engine Setup ==="

# 1. Check Python
if command -v python3 &>/dev/null; then
    PYTHON=python3
elif command -v python &>/dev/null; then
    PYTHON=python
else
    echo "[ERROR] Python not found. Please install Python 3.8+"
    exit 1
fi

echo "[1/3] Python version: $($PYTHON --version 2>&1)"

# 2. Verify engine
echo "[2/3] Verifying engine..."
cd "$DIR"
$PYTHON -c "
import sys
sys.path.insert(0, '.')
from engine import CognitiveEnhancer
brain = CognitiveEnhancer()
brain.memorize('Installation test', importance=1.0)
brain.perceive('verification')
status = brain.get_status()
assert status['long_term_memories'] == 1, 'Memory not working'
print('Engine verified OK')
print(f'  Memories: {status[\"long_term_memories\"]}')
print(f'  Working:  {status[\"working_memories\"]}')
"

# 3. Create shell alias (optional)
echo "[3/3] Creating shell alias (optional)..."
SHELL_RC="$HOME/.bashrc"
[ -f "$HOME/.zshrc" ] && SHELL_RC="$HOME/.zshrc"

ALIAS_CMD="alias cognitive-enhance='cd $DIR && $PYTHON -c \"import sys; sys.path.insert(0, \\\"$DIR\\\"); from engine import CognitiveEnhancer; b = CognitiveEnhancer(); print(\\\"Cognitive Enhancement Engine loaded. Use b.perceive(), b.memorize(), b.recall() etc.\\\"); import code; code.interact(local=dict(b=b))\"'"

if ! grep -q "cognitive-enhance" "$SHELL_RC" 2>/dev/null; then
    echo "$ALIAS_CMD" >> "$SHELL_RC"
    echo "  Alias 'cognitive-enhance' added to $SHELL_RC"
    echo "  Run: source $SHELL_RC && cognitive-enhance"
else
    echo "  Alias 'cognitive-enhance' already exists"
fi

echo ""
echo "=== Setup Complete ==="
echo "Quick start:  python \"$ENGINE_PY\""
echo "API mode:     from engine import CognitiveEnhancer"


path: scripts/test-basic.py
content: """认知力增强引擎 — 基础功能测试"""
import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
from engine import CognitiveEnhancer

def test_basic():
    brain = CognitiveEnhancer(long_term_capacity=10)
    
    # 测试记忆
    brain.memorize("Python is a programming language.", importance=0.8)
    brain.memorize("Lists are mutable in Python.", importance=0.7)
    
    # 测试检索
    results = brain.recall("Python programming", top_k=2)
    assert len(results) > 0, "Should find memories"
    print(f"[PASS] Recall: found {len(results)} results")
    
    # 测试感知
    brain.perceive("User asked about Python")
    status = brain.get_status()
    assert status['working_memories'] > 0, "Working memory should have entries"
    print(f"[PASS] Working memory: {status['working_memories']} entries")
    
    # 测试规划
    plan = brain.plan("Calculate 15 + 27")
    assert len(plan) > 0, "Should produce a plan"
    print(f"[PASS] Planning: {len(plan)} steps")
    
    # 测试推理
    answer = brain.reason("What programming language uses lists?")
    assert len(answer) > 0, "Should produce an answer"
    print(f"[PASS] Reasoning: produced answer")
    
    # 测试任务执行
    result = brain.execute_task("Calculate 15 + 27")
    assert result.get('success', False), "Task should complete"
    print(f"[PASS] Execute task: success={result.get('success')}")
    
    # 测试反思
    suggestions = brain.reflect()
    print(f"[PASS] Reflection: {len(suggestions)} suggestions")
    
    # 测试状态
    status = brain.get_status()
    print(f"[PASS] Status: {status['long_term_memories']} memories, "
          f"{status['working_memories']} working, "
          f"{status['tasks_executed']} tasks")
    
    print("\n=== ALL TESTS PASSED ===")

if __name__ == '__main__':
    test_basic()


path: scripts/test-client.js
content: /**
 * Cognitive Enhancement Engine — Node.js client test
 * Pure Python execution via Python directly (see SKILL.md).
 * This file verifies engine.py loads and runs correctly.
 * 
 * Usage: node scripts/test-client.js
 */

const path = require('path');

const ENGINE_DIR = path.join(__dirname, '..');
const ENGINE_PY = path.join(ENGINE_DIR, 'engine.py');

function test() {
  console.log('=== Testing Cognitive Enhancement Engine ===\n');
  console.log('This skill runs on Python 3.8+ with zero dependencies.');
  console.log('');
  console.log('To verify the engine works:');
  console.log(`  python "${ENGINE_PY}"`);
  console.log(`  python scripts/test-basic.py`);
  console.log('');
  console.log('Engine location: ' + ENGINE_DIR);
  console.log('Engine file: ' + ENGINE_PY);
  console.log('');
  console.log('=== ALL TESTS SKIPPED (run python scripts/test-basic.py instead) ===');
}

test();


path: references/API_SPEC.md
content: # API 规格说明书 — 认知力增强引擎 (Cognitive Enhancement Engine)

## CognitiveEnhancer

核心类，整合所有认知能力。

### 构造函数

```python
CognitiveEnhancer(
    long_term_capacity: int = 1000,
    working_memory_size: int = 10,
    similarity_threshold: float = 0.15
)
```

**参数：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `long_term_capacity` | int | 1000 | 长期记忆最大条目数 |
| `working_memory_size` | int | 10 | 工作记忆 FIFO 缓存大小 |
| `similarity_threshold` | float | 0.15 | 检索相似度最低阈值 |

---

### 方法

#### `perceive(observation: str) -> None`
将感知信息存入工作记忆。

- **输入：** `observation` — 感知文本（非空字符串）
- **输出：** 无
- **错误：** 空字符串抛出 ValueError

#### `recall(query: str, top_k: int = 5) -> List[Dict]`
从长期记忆中检索最相关内容。

- **输入：** `query` — 查询文本；`top_k` — 返回结果数（1-50）
- **输出：** `[{content, metadata, importance, score, timestamp}, ...]`
- **错误：** 空 query 返回空列表

#### `memorize(content: str, metadata: Optional[Dict] = None, importance: float = 1.0) -> str`
将内容存入长期记忆。

- **输入：** `content` — 记忆内容；`metadata` — 元数据字典；`importance` — 重要性（0-2.0）
- **输出：** `memory_id` — 记忆唯一标识
- **错误：** 空内容抛出 ValueError

#### `plan(goal: str) -> List[Dict]`
将目标分解为可执行步骤。

- **输入：** `goal` — 目标描述
- **输出：** `[{step_id, action, params, expected_output}, ...]`
- **任务类型自动检测：** 计算、搜索、摘要、翻译、写作

#### `reason(problem: str) -> str`
基于长期记忆进行推理问答。

- **输入：** `problem` — 问题描述
- **输出：** 推理结果文本

#### `reflect() -> List[str]`
主动反思，挖掘失败模式并生成改进建议。

- **输入：** 无
- **输出：** 建议列表

#### `execute_task(goal: str, executor: Optional[Callable] = None) -> Dict`
完整任务执行流程（规划 → 执行 → 记忆 → 反思）。

- **输入：** `goal` — 目标；`executor` — 自定义执行函数（默认用内置推理器）
- **输出：** `{goal, plan, result, reflections, status, working_memory, ...}`

#### `get_status() -> Dict`
返回引擎完整运行状态。

- **输入：** 无
- **输出：** `{long_term_count, working_memory, reflection_count, ...}`

---

## 内部组件

### Tokenizer
统一分词工具，中英文基础支持。

### VectorMemory
TF-IDF + 倒排索引的长期记忆存储，O(n) 检索 → O(query_tokens)。

### WorkingMemory
FIFO 短期上下文缓存，附带时间戳。

### Planner
目标分解引擎，通过关键词匹配自动识别任务类型。

### Reasoner
基于记忆检索的问答引擎。

### Reflector
失败模式记录和重复失败规律挖掘。

### MetacognitiveMonitor
任务耗时和错误率追踪。


path: references/USE_GUIDE.md
content: # 使用指南 — 认知力增强引擎

## 安装

### 方式一：一键安装（推荐）

```bash
# Linux / macOS / WSL
bash scripts/setup.sh

# Windows
双击 scripts/setup.bat
# 或在 cmd 中运行:
scripts\setup.bat
```

安装脚本自动检测 Python 并验证引擎。

### 方式二：直接使用
```bash
# 复制 engine.py 到项目目录
cp skills/cognitive-enhancement-engine/engine.py ./my_project/
```

### 方式三：ClawHub 安装
```bash
clawhub install cognitive-enhancement-engine
cd cognitive-enhancement-engine
bash scripts/setup.sh  # 补充安装
```

## 快速上手

### 基础用法

```python
from engine import CognitiveEnhancer

# 初始化
brain = CognitiveEnhancer(long_term_capacity=100)

# 1. 记忆知识
brain.memorize("The Earth orbits the Sun.", importance=0.8)
brain.memorize("Light travels at 299,792,458 m/s.", importance=0.7)

# 2. 检索
results = brain.recall("speed of light", top_k=2)
for r in results:
    print(f"[{r['importance']:.1f}] {r['content']}")

# 3. 规划
plan = brain.plan("Calculate the time for light to reach Earth")
for step in plan:
    print(f"Step {step['step_id']}: {step['action']}")

# 4. 直接执行
result = brain.execute_task("What is the distance from Earth to Sun?")
print(result['result'])
```

### 工作记忆

```python
# 感知信息自动进入工作记忆
brain.perceive("User is asking about astronomy")
brain.perceive("Current topic: solar system")

# 工作记忆是 FIFO 队列
status = brain.get_status()
print(status['working_memory'])  # 最近 10 条
```

### 反思

```python
# 触发反思（基于过去的失败记录）
suggestions = brain.reflect()
for s in suggestions:
    print(f"Suggestion: {s}")
```

## 最佳实践

1. **记忆容量管理** — 设置合适的 `long_term_capacity`，超出时最早的记忆会被淘汰
2. **重要性权重** — 关键知识设 `importance=1.5`，临时信息设 `importance=0.5`
3. **定期反思** — 在任务间隙调用 `reflect()`，挖掘失败模式
4. **工作记忆大小** — 根据上下文窗口调整，默认 10 适合大多数场景

## 运行测试

```bash
# Python 测试
python scripts/test-basic.py

# Node.js 测试
node scripts/test-client.js

# 内置演示
python engine.py
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)