{"skill":{"slug":"cognitive-brain","displayName":"Cognitive Brain","summary":"Provides a cross-session AI memory and cognition system with four-layer memory, real-time sync, free thinking, intelligent prediction, and knowledge visualiz...","description":"# 🧠 Cognitive Brain\n\n> **跨会话记忆与认知系统 v5.0** | Cross-Session Memory & Cognition System\n> \n> 让 AI 拥有像人类一样的记忆、思考和预测能力\n\n**Version: 7.0.1** | **License: MIT**\n\n---\n\n## ✨ 功能特性 | Features\n\n| 功能 | Feature | 描述 |\n|------|---------|------|\n| 🔄 实时共享 | Real-time Sharing | 跨会话毫秒级记忆同步 |\n| 🧠 四层记忆 | Four-Layer Memory | 感官/工作/情景/语义记忆架构 |\n| 💭 自由思考 | Free Thinking | 非任务驱动的意识流思考 |\n| 🔮 智能预测 | Prediction | 预测用户需求，预加载记忆 |\n| 📊 可视化 | Visualization | 知识图谱、时间线、摘要 |\n| 🔗 联想网络 | Association Network | 概念关联，激活扩散算法 |\n| 🏗️ 分层架构 | Layered Architecture | Domain/Repository/Service 分层设计 |\n| 🔒 事务安全 | Transaction Safety | UnitOfWork 确保数据一致性 |\n| 📚 完整文档 | Documentation | API 文档 + 架构文档 |\n| ✅ 测试覆盖 | Test Coverage | 自动化测试套件 |\n\n---\n\n## 🚀 快速开始 | Quick Start\n\n### 一键安装 | Quick Install\n\n```bash\n# 方式1: ClawHub 安装（推荐）\nclawhub install cognitive-brain\ncd ~/.openclaw/workspace/skills/cognitive-brain\nnpm run setup:auto    # 非交互模式，自动安装所有依赖\n\n# 方式2: 手动安装\ncd ~/.openclaw/workspace/skills/cognitive-brain\nnpm install\nnpm run setup         # 交互式配置\n```\n\n### 安装模式 | Install Modes\n\n| 命令 | 说明 |\n|------|------|\n| `npm run check` | 检查系统依赖（PostgreSQL, Redis, pgvector） |\n| `npm run setup` | 交互式安装，会提示输入数据库配置 |\n| `npm run setup:auto` | 自动安装，使用默认配置，自动安装缺失依赖 |\n| `npm run setup:resume` | 从断点恢复安装（安装失败后使用） |\n| `npm run health` | 健康检查 |\n| `npm run reset` | 重置数据库（清空记忆，保留表结构） |\n| `npm run uninstall` | 卸载（清理数据库、hooks、配置文件） |\n\n### 安装特性 | Install Features\n\n| 特性 | 说明 |\n|------|------|\n| 🔄 断点恢复 | 安装失败后运行 `npm run setup:resume` 继续 |\n| 📋 安装日志 | 记录到 `install.log`，便于排查问题 |\n| 🔍 已安装检测 | 自动检测是否已安装，避免重复 |\n| ⚡ 一键安装 | `installCommand` 自动执行完整安装流程 |\n\n### 系统要求 | Requirements\n\n| 依赖 | 版本 | 安装命令 (Ubuntu) |\n|------|------|-------------------|\n| Node.js | >= 18 | `apt install nodejs npm` |\n| PostgreSQL | >= 14 | `apt install postgresql` |\n| Redis | >= 6 | `apt install redis-server` |\n| pgvector | - | `apt install postgresql-16-pgvector` |\n\n> 💡 `npm run setup:auto` 会自动安装这些依赖（需要 root 权限）\n\n### 基础使用 | Basic Usage\n\n```javascript\nconst { CognitiveBrain } = require('./src/index.js');\nconst brain = new CognitiveBrain();\n\n// 存储记忆\nconst memory = await brain.encode('用户的项目叫 Alpha', {\n  type: 'conversation',\n  importance: 0.8\n});\n\n// 检索记忆\nconst memories = await brain.recall('项目');\n\n// 获取统计\nconst stats = await brain.stats();\n```\n\n### CLI 工具\n\n```bash\n# 编码记忆\nnode scripts/core/encode.cjs \"内容\" -t conversation -i 0.8\n\n# 检索记忆\nnode scripts/core/recall.cjs --query \"关键词\" --limit 5\n\n# 健康检查\nnode scripts/tools/health_check.cjs\n\n# 运行测试\n./tests/run.sh\n```\n\n---\n\n## 🏗️ 架构概览 | Architecture\n\n### v5.0 分层架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      API / CLI 层                           │\n│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │\n│  │  REST API  │  │   CLI      │  │   Hook     │            │\n│  └────────────┘  └────────────┘  └────────────┘            │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n┌─────────────────────────▼───────────────────────────────────┐\n│                   Service 层                                │\n│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │\n│  │   Memory   │  │   Concept  │  │ Association│            │\n│  │   Service  │  │   Service  │  │   Service  │            │\n│  └────────────┘  └────────────┘  └────────────┘            │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n┌─────────────────────────▼───────────────────────────────────┐\n│                Repository 层                                │\n│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │\n│  │   Memory   │  │   Concept  │  │ Association│            │\n│  │ Repository │  │ Repository │  │ Repository │            │\n│  └────────────┘  └────────────┘  └────────────┘            │\n│                      UnitOfWork (事务)                      │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n┌─────────────────────────▼───────────────────────────────────┐\n│                  Domain 层                                  │\n│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │\n│  │   Memory   │  │   Concept  │  │ Association│            │\n│  │   Entity   │  │   Entity   │  │   Entity   │            │\n│  └────────────┘  └────────────┘  └────────────┘            │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n┌─────────────────────────▼───────────────────────────────────┐\n│              持久层 | Persistence                           │\n│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │\n│  │  PostgreSQL│  │   Redis    │  │   Files    │            │\n│  │  (主存储)   │  │  (缓存)     │  │  (配置/日志)│            │\n│  └────────────┘  └────────────┘  └────────────┘            │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 设计原则\n\n1. **单一职责**: 每个模块只做一件事\n2. **依赖注入**: 通过参数传入依赖，不直接创建\n3. **接口隔离**: 清晰的模块边界\n4. **事务安全**: 多表操作原子性保证\n\n---\n\n## 🧠 四层记忆模型 | Four-Layer Memory\n\n| 层级 | Layer | Duration | Purpose | Description |\n|------|-------|---------|---------|-------------|\n| 感官记忆 | Sensory | Milliseconds | Buffer | Transient sensory buffer for immediate perception |\n| 工作记忆 | Working | Minutes~Hours | Active Processing | Active processing workspace for current tasks |\n| 情景记忆 | Episodic | Long-term | Experiences | Personal experiences and events with context |\n| 语义记忆 | Semantic | Long-term | Knowledge | Facts, concepts, and structured knowledge |\n\n---\n\n## 📚 核心 API\n\n### CognitiveBrain\n\n主入口类，提供统一的操作接口。\n\n```javascript\nconst { CognitiveBrain } = require('./src/index.js');\nconst brain = new CognitiveBrain();\n\n// 编码记忆\nconst memory = await brain.encode(content, {\n  type: 'conversation',\n  importance: 0.8,\n  sourceChannel: 'qq'\n});\n\n// 检索记忆\nconst memories = await brain.recall('关键词', { limit: 10 });\n\n// 事务操作\nawait brain.transaction(async (uow) => {\n  // 多表原子操作\n});\n\n// 获取统计\nconst stats = await brain.stats();\n```\n\n### 实体模型\n\n#### Memory (记忆)\n```javascript\n{\n  id: 'uuid',\n  content: '记忆内容',\n  type: 'episodic',\n  importance: 0.5,\n  sourceChannel: 'qq',\n  role: 'user',\n  entities: ['关键词'],\n  emotions: { valence: 0, arousal: 0 },\n  createdAt: Date,\n  updatedAt: Date\n}\n```\n\n#### Concept (概念)\n```javascript\n{\n  id: 'uuid',\n  name: '概念名称',\n  type: 'general',\n  importance: 0.5,\n  activation: 0.0,\n  accessCount: 0\n}\n```\n\n#### Association (关联)\n```javascript\n{\n  id: 'uuid',\n  fromId: '概念A-ID',\n  toId: '概念B-ID',\n  type: 'related',\n  weight: 0.5\n}\n```\n\n---\n\n## 🔒 事务管理\n\n使用 UnitOfWork 模式确保数据一致性：\n\n```javascript\nconst { UnitOfWork } = require('./src/repositories/UnitOfWork.js');\nconst { MemoryRepository } = require('./src/repositories/MemoryRepository.js');\n\n// 自动事务\nawait UnitOfWork.withTransaction(pool, async (uow) => {\n  const memRepo = new MemoryRepository(uow.getQueryClient());\n  const conceptRepo = new ConceptRepository(uow.getQueryClient());\n  \n  await memRepo.create(memory);\n  await conceptRepo.create(concept);\n  // 自动 commit 或 rollback\n});\n```\n\n---\n\n## 🧪 测试\n\n```bash\n# 运行所有测试\n./tests/run.sh\n\n# 运行特定测试\nnode tests/v5.test.cjs\nnode tests/db.test.cjs\nnode tests/memory.test.cjs\n\n# 健康检查\nnode scripts/tools/health_check.cjs\n```\n\n---\n\n## 📖 文档\n\n- [API 文档](./docs/README.md) - 完整 API 参考\n- [架构文档](./docs/ARCHITECTURE.md) - 架构设计说明\n\n---\n\n## 🔄 共享工作区 | Shared Workspace\n\n### 核心表 | Core Tables\n\n| 表名 | 用途 | 说明 |\n|------|------|------|\n| `episodes` | 情景记忆 | 存储对话和事件 |\n| `concepts` | 概念节点 | 提取的实体和关键词 |\n| `associations` | 概念关联 | 概念间的关系 |\n| `system_memory` | 系统配置 | 全局设置和状态 |\n\n### Hook 集成\n\n自动集成到 OpenClaw 消息流程：\n\n```\n用户消息 → Hook(cognitive-recall) → 检索记忆 → 注入上下文 → AI回复 → 编码记忆\n```\n\n---\n\n## 🔧 配置\n\n```json\n{\n  \"version\": \"5.3.25\",\n  \"storage\": {\n    \"primary\": {\n      \"type\": \"postgresql\",\n      \"host\": \"localhost\",\n      \"port\": 5432,\n      \"database\": \"cognitive_brain\"\n    },\n    \"cache\": {\n      \"type\": \"redis\",\n      \"host\": \"localhost\",\n      \"port\": 6379\n    }\n  }\n}\n```\n\n---\n\n## 📈 版本历史\n\n### v7.0.1 (2026-03-21)\n- 🔧 **记忆系统重构** - 修复 Hook 触发问题，改用 Cron 方案\n- ✨ **记忆读取** - `agent:bootstrap` Hook 即时注入记忆\n- ✨ **记忆写入** - Cron 每 1 分钟扫描会话文件\n- 🗑️ **清理无用脚本** - 删除 20+ 不常用脚本\n- 📝 **文档更新** - 简化架构说明\n\n### v5.3.32 (2026-03-21)\n- 🐛 **修复类型验证** - `type: 'conversation'` 改为有效类型 `'episodic'`\n- 🐛 **修复 Embedding 路径** - embed.py 路径错误导致 embedding 生成失败\n\n### v5.3.22 (2026-03-20)\n- 发布版本更新\n\n### v5.3.11 (2026-03-18)\n- 🧪 **测试覆盖率提升** - 新增 Repository/Service/API 测试 (7个测试文件)\n- 🧹 **事件监听器清理** - 优雅关闭时清理所有监听器，防止内存泄漏\n- 💓 **WebSocket 心跳** - 30秒 ping/pong 检测，120秒无响应自动断开\n- ⚡ **N+1 查询优化** - 批量插入从 O(N) 优化为 O(1)\n- 🔒 **API 速率限制** - 100 req/min 限流保护\n\n### v5.3.7 (2026-03-18)\n- 🗑️ **删除重复文档** - 删除 README.md，统一文档入口\n- 🔧 **统一代码规范** - 修复 80+ 文件缺少换行符\n- 🔧 **统一 Logger** - Winston logger 替代 console.log\n- 🔒 **事务安全** - 隔离级别 + 死锁重试 + 熔断器\n- ⚙️ **配置增强** - 连接池可配置 + 日志配置\n\n### v5.3.20 (2026-03-19)\n- ✨ **安装流程优化** - 非交互模式、断点恢复、安装日志\n- ✨ **Skill.json installCommand** - 支持一键自动安装\n- ✨ **卸载脚本** - `npm run uninstall` 清理所有组件\n- ✨ **重置脚本** - `npm run reset` 清空记忆数据\n- 🔧 **修复 create_indexes.cjs** - 模块路径错误\n- 🔧 **修复 health_check.cjs** - SQL 语法错误\n- 📝 **文档更新** - 安装指南、命令说明\n\n### v5.0.0 (2026-03-18)\n- ✨ 重构为分层架构 (Domain/Repository/Service)\n- ✨ 添加 UnitOfWork 事务管理\n- ✨ 添加领域模型验证\n- ✨ 添加测试框架 (13个测试)\n- ✨ 添加统一日志模块\n- ✨ 添加配置管理器\n- ✅ 修复 Pool 连接泄漏\n- ✅ 修复空 catch 块\n- ✅ 移除文件 fallback，强制数据库优先\n\n### v4.1.0 (Previous)\n- 基础记忆功能\n- 联想网络\n- 预测预加载\n- 心跳反思\n- 自由思考\n\n---\n\n## 🤝 贡献\n\n1. Fork 仓库\n2. 创建分支 (`git checkout -b feature/xxx`)\n3. 提交修改 (`git commit -m 'Add feature'`)\n4. 推送分支 (`git push origin feature/xxx`)\n5. 创建 Pull Request\n\n---\n\n## 📄 许可\n\nMIT License\n\n---\n\n**让 AI 拥有记忆，让对话更有温度** ❤️\n\n","topics":["会话记忆","会话","记忆"],"tags":{"latest":"7.0.1","ai":"5.3.19","api":"5.3.0","brain":"5.3.19","learning":"5.3.19","memory":"5.3.19","metrics":"5.2.0","production":"5.3.2","production-ready":"5.3.13","security":"5.3.0","v5":"5.3.19","websocket":"5.3.0"},"stats":{"comments":0,"downloads":1579,"installsAllTime":59,"installsCurrent":2,"stars":0,"versions":79},"createdAt":1773245475349,"updatedAt":1779078011285},"latestVersion":{"version":"7.0.1","createdAt":1774082170575,"changelog":"改为5分钟间隔，后台静默运行","license":"MIT-0"},"metadata":null,"owner":{"handle":"aboutyao","userId":"s175ws75xy4zy84z5z750eh3ex83h760","displayName":"aboutyao","image":"https://avatars.githubusercontent.com/u/68453955?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090015653}}