Clawhub Skill

核心用法

cc-soul 是一款面向AI对话系统的长期记忆引擎，通过REST API提供记忆存储与检索服务。用户可通过 POST /memories 存储用户偏好与对话事实，POST /search 进行智能检索，支持按用户ID隔离数据。核心架构采用零向量设计——完全摒弃Embedding和向量数据库，依赖符号化算法实现记忆关联与召回。

显著优点

1. 极致轻量：存储占用仅为向量方案的8.6%（5.7 MB vs 49.2 MB），p50召回延迟127ms，纯CPU运行无需GPU
2. 自学习进化：AAM自适应联想网络从对话中实时学习词关联，1200条消息后Hit@3从30%提升至67.5%
3. 多信号融合：整合ACT-R激活理论、BM25+检索、情绪共振、时间编码等9-12种信号动态评分
4. 隐私优先：完全本地运行，SQLite存储，零云端/零遥测，PII自动过滤，用户自主配置LLM密钥
5. 智能 persona：11种人格自动切换（工程师/导师/安慰者等），基于对话内容自适应

潜在局限

• 基准表现：LOCOMO总分76.2%虽位列全球第4，但多跳推理(65.7%)、对抗测试(56.5%)仍有明显短板
• 部署门槛：需Node.js 20+环境，npm安装路径可能因系统差异需手动调试启动
• 生态兼容：相比主流向量方案(LangChain等)，第三方集成案例与社区生态尚处早期
• 无LLM时功能受限：纯算法模式虽可用，但查询重写、结果重排序需依赖外部LLM

适合人群

• 隐私敏感型开发者：医疗、金融等场景需本地部署、数据不出境
• 资源受限环境：边缘设备、低配置服务器无法承载向量数据库与GPU
• 长对话Agent开发者：客服、陪伴型AI需跨会话记忆且追求可解释性召回逻辑
• 算法研究者：15种原创算法的符号化记忆实现可供学术复现与改进

常规风险

• 数据持久化：SQLite文件位于~/.cc-soul/data/，需自行备份防止误删
• LLM配置安全：ai_config.json中的API密钥以明文存储，需确保文件权限控制
• 自我学习偏差：AAM从用户对话中学习，若输入存在偏见，关联网络可能放大偏差
• 版本兼容性：v3.2.4 API格式，升级时需关注Breaking Changes

---

认证状态：报告占位符显示未执行安全扫描，建议结合代码审计与MIT协议开源特性自行验证。

核心用法

cc-soul 是一个零向量的 AI 记忆引擎，专为需要长期对话记忆能力的 Agent 设计。与传统依赖向量数据库的方案不同，它采用纯符号计算（symbolic）架构，通过 AAM 自适应联想记忆 和 NAM 神经激活记忆 两大核心机制实现智能召回。

部署极为轻量：一条 npm 命令完成安装，自动启动本地 REST API（默认 localhost:18800）。开发者可通过标准 HTTP 接口完成记忆存储（POST /memories）、语义检索（POST /search）和健康检查（GET /health）。系统可选配置外部 LLM（DeepSeek/OpenAI/Claude 等）用于查询重写和结果重排序，但核心 NAM 功能完全离线可用，召回延迟中位数仅 127ms。

关键创新在于 自学习机制：每轮对话自动更新词共现统计（PMI 模型），强关联自动晋升同义词表，Hit@3 准确率可从 30% 提升至 67.5%（1200 条消息后）。三层蒸馏架构（原始记忆→主题节点→心智模型）实现自动记忆压缩与淘汰，无需人工维护。

---

显著优点

1. 突破性效率指标

• 存储占用仅 5.7 MB，相比向量方案（49.2 MB）压缩 8.6 倍
• 零外部 API 依赖的纯本地模式，边缘设备友好
• LOCOMO 长程对话记忆基准 76.2% 准确率，全球第 4，且是唯一进入 Top 5 的非向量系统

2. 深度个性化能力

• 11 维自动人格切换：根据对话语境在 Engineer/Friend/Mentor/Analyst 等角色间无缝切换
• PADCN 五维情绪追踪（愉悦/唤醒/支配/确信/新奇），实现情绪一致的记忆召回
• 用户专属联想网络：从"马拉松"自动扩展至"跑步/比赛/训练"——学习自该用户的对话历史，非预置词库

3. 安全与隐私极致设计

• 全开源 MIT 许可，约 4.7 万行 TypeScript 无混淆可审计
• 数据本地化：SQLite 存储于 ~/.cc-soul/data/，零云上传、零遥测
• PII 自动过滤：邮箱、电话、API key 等敏感信息存储前脱敏

4. 智能查询路由（CNAS）
系统自动识别查询类型并切换策略：精确型启用严格 BM25 和主题分区；时间型增强时间信号匹配；多实体型采用覆盖度重排序；宽泛型执行全扫描松弛匹配。

---

潜在缺点与局限性

1. 冷启动与学习曲线
自学习机制意味着初期表现较弱（Hit@3 约 30%），需积累约 1200 条消息后才能达到最佳性能（67.5%）。对追求开箱即用的场景不够友好。

2. 符号架构的语义天花板
纯算法召回虽高效，但在处理高度抽象的语义关联（如隐喻、文化梗、跨领域类比）时，可能弱于大参数向量模型。LOCOMO 的 adversarial 项得分 56.5% 也反映了复杂对抗性查询的挑战。

3. 单用户/单会话架构
当前设计以 user_id 隔离记忆，但缺乏企业级多租户隔离、权限分级、审计日志等企业特性。大规模并发场景的横向扩展能力未经验证。

4. 依赖 Node.js 20+ 生态
对纯 Python 或 Rust 技术栈的团队引入额外运行时负担。虽然提供了 REST API，但深度定制仍需 TypeScript 开发能力。

---

适合的目标群体

| 场景 | 适配度 | 原因 |

|:---|:---|:---|

| **个人知识管理 Agent** | ⭐⭐⭐⭐⭐ | 隐私优先、长期学习、本地存储 |

| **客服/陪伴型 AI** | ⭐⭐⭐⭐⭐ | 情绪感知、人格切换、长程记忆 |

| **边缘设备/离线场景** | ⭐⭐⭐⭐⭐ | 零 GPU、极小存储、纯本地运行 |

| **多 Agent 协作系统** | ⭐⭐⭐⭐ | 标准化 REST API，易于集成 |

| **企业级 SaaS 平台** | ⭐⭐⭐ | 需自行补充租户隔离、审计、SLA 保障 |

| **科研语义检索** | ⭐⭐⭐ | 专业领域抽象概念关联可能弱于向量方案 |

---

使用风险与注意事项

1. 命令注入风险（中）
代码使用 child_process.spawn 调用用户配置的本地 LLM CLI（如 ollama）。虽然输入为用户自有查询且用于本地命令，理论上仍存在注入可能。建议启用前审查 ai_config.json 中的 cli_command 配置。

2. 外部 LLM 数据泄露（中）
配置外部 LLM 后，查询文本和 API key 将发送至第三方端点（DeepSeek/OpenAI 等）。虽经 TLS 加密，但敏感场景建议始终使用纯本地 NAM 模式。

3. 来源可信度 T3
维护者 GitHub 账号创建于 2026-02，公开信息有限。尽管代码完全开源可审计，企业部署建议进行内部安全审查后再上线生产环境。

4. 版本号不一致
SKILL.md（3.2.4）、package.json（3.2.0）、soul.json（2.9.2）版本号未同步，升级时需特别注意兼容性验证。

5. 数据持久化依赖
记忆数据存储于本地 SQLite，需自行配置备份策略。系统未内置自动备份或灾难恢复机制。