📦 Cortex — 本地记忆管理

# Cortex — 本地优先的智能体记忆 OpenClaw 本应内置的记忆层。 Cortex 是一个开源、以“先导入”为核心的 AI 智能体记忆系统。单文件 Go 二进制、SQLite 存储、零云依赖。它解决了 OpenClaw 的头号抱怨：压缩后一切细节都被遗忘。 GitHub： https://github.com/hurttlocker/cortex 安装： brew install hurttlocker/cortex/cortex 或从 Releases 下载 ## 为什么选 Cortex？ OpenClaw 的默认记忆是 Markdown 文件。当上下文满了，压缩会总结并销毁细节。Cortex 解决此问题： | 问题 | Cortex 解决方案 | |---|---| | 压缩丢失细节 | 持久 SQLite 数据库跨会话存活 | | 无法搜索——只能把文件扔进上下文 | 混合 BM25 + 语义搜索（关键词约 16 ms，语义约 52 ms） | 所有信息权重相同 | 艾宾浩斯衰减——重要事实留存，噪音自然消退 | | 无法导入已有文件 | 先导入：Markdown、文本、任意文件。8 个连接器（GitHub、Gmail、日历、Drive、Slack、Notion、Discord、Telegram） | | 多智能体记忆泄露 | 内置按智能体隔离 | | 云记忆服务昂贵 | 0 美元/月，永久免费，本地 SQLite | ## 快速开始 ### 1. 安装 Cortex ``bash # macOS/Linux（Homebrew） brew install hurttlocker/cortex/cortex # 或直接下载二进制 # https://github.com/hurttlocker/cortex/releases/latest ` ### 2. 导入你的记忆 `bash # 导入 OpenClaw 的记忆文件 cortex import ~/clawd/memory/ --extract # 导入特定文件 cortex import ~/clawd/MEMORY.md --extract cortex import ~/clawd/USER.md --extract ` ### 3. 搜索 `bash # 快速关键词搜索 cortex search "wedding venue" --limit 5 # 语义搜索（需 ollama + nomic-embed-text） cortex search "what decisions did I make about the project" --mode semantic # 混合（推荐） cortex search "trading strategy" --mode hybrid ` ### 4. 作为 MCP 服务器使用（OpenClaw 推荐） `bash # 加入你的 MCP 配置——Cortex 暴露 17 个工具 + 4 个资源 cortex mcp # stdio 模式 cortex mcp --port 8080 # HTTP+SSE 模式 ` ## 核心功能 ### 艾宾浩斯遗忘曲线 事实按类型以不同速率衰减。身份事实（姓名、角色）持续约 2 年；时间事实（事件、日期）约 1 周；状态事实（状态、心情）约 2 周。搜索结果因此自然优先展示重要内容——无需手动整理。 ### 混合搜索 - BM25 —— 通过 SQLite FTS5 实现即时关键词匹配（约 16 ms） - Semantic —— 基于含义的本地嵌入（约 52 ms） - Hybrid —— 两者结合，采用倒数秩融合 ### 事实抽取 每个导入文件自动抽取事实： - 基于规则抽取（零成本、即时） - 可选 LLM 增强（Grok、Gemini 或任意提供商——发现规则遗漏的事实） - 自动分类为 9 种类型：identity、relationship、preference、decision、temporal、location、state、config、kv ### 连接器（Beta） 从外部源拉取记忆： `bash cortex connect sync --provider github --extract cortex connect sync --provider gmail --extract cortex connect sync --all --extract ` ### 知识图谱 可视化浏览记忆： `bash cortex graph --serve --port 8090 # 在浏览器打开交互式 2D 图谱浏览器 ` ### 自清理 `bash cortex cleanup --purge-noise # 移除垃圾 + 重复 cortex stale 30 # 找出 30 天未访问的事实 cortex conflicts # 检测矛盾 cortex conflicts --resolve llm # 用 LLM 自动解决 ` ## 与 OpenClaw 集成 ### 推荐搜索链 ` memory_search → Cortex → QMD → ripgrep → web search ` 对话历史用 OpenClaw 内置的 memory_search，深层知识检索用 Cortex。 ### 封装脚本 附带的 scripts/cortex.sh 提供快捷命令： `bash scripts/cortex.sh search "query" 5 # 混合搜索 scripts/cortex.sh stats # 记忆健康 scripts/cortex.sh stale 30 # 检测陈旧事实 scripts/cortex.sh conflicts # 检测矛盾 scripts/cortex.sh sync # 增量导入 scripts/cortex.sh reimport # 全量清空 + 重导 scripts/cortex.sh compaction # 压缩前状态简报 ` ### 自动同步（launchd/systemd） `bash # 每 30 分钟自动导入会话 + 同步连接器 cortex connect schedule --every 30m --install ` ## 架构 - 语言： Go（62,300+ 行，1,081 项测试） - 存储： SQLite + FTS5 + WAL 模式 - 二进制： 19 MB，纯 Go，零 CGO，零运行时依赖 - 平台： macOS（arm64/amd64）、Linux（arm64/amd64）、Windows（amd64） - MCP： 17 个工具 + 4 个资源（stdio 或 HTTP+SSE） - 嵌入： 本地通过 Ollama（nomic-embed-text），或 OpenAI/DeepSeek/自定义 - LLM： 可选增强，任意提供商（Grok、Gemini、DeepSeek、OpenRouter） - 规模： 实测 100K+ 记忆。每天 20–50 条，5 年以上不会触顶 - 许可证： MIT ## 与其他记忆工具对比 | | Cortex | Mem0 | Zep | LangMem | |---|---|---|---|---| | 部署 | 单二进制 | 云或 K8s | 云 | Python 库 | | 费用 | $0 | $19–249/月 | $25/月+ | 基础设施成本 | | 隐私 | 100% 本地 | 默认云端 | 云端 | 视情况 | | 衰减 | 艾宾浩斯（7 档速率） | 仅 TTL | 时间型 | 无 | | 导入 | 文件 + 8 连接器 | 聊天抽取 | 聊天/文档 | 聊天抽取 | | 搜索 | BM25 + 语义 | 向量 + 图谱 | 时间 KG | JSON 文档 | | MCP | 17 工具原生 | 无 | 无 | 无 | | 依赖 | 零 | Python + 云 | 云 + 额度 | Python + LangGraph | ## 需求 - Cortex 二进制 —— 通过 Homebrew 或 GitHub Releases 下载 - 可选： Ollama + nomic-embed-text 用于语义搜索 - 可选： LLM API 密钥用于增强（Grok、Gemini 等） - 无需 Python、Node、Docker、云账号，只需一个二进制。 ## v1.1/v1.2 集成指南（为 OpenClaw 智能体接线） ### 何时用 cortex answer 与 cortex search - answer —— “关于 X 我知道什么？” / “Y 是谁？” / 综合问题 → 带引用的连贯单条回答 - search —— “找到提到 X 的文件” / 调试 / 探索存在什么 → 排序结果列表 ### 来源加权（config.yaml） 添加到 ~/.cortex/config.yaml： `yaml search: source_boost: - prefix: "memory/" weight: 1.5 - prefix: "file:MEMORY" weight: 1.6 - prefix: "github" weight: 1.3 - prefix: "session:" weight: 0.9 ` 权重越高越可信。每日笔记与核心文件排名高于自动导入的会话。 ### 搜索意图 当你知道答案在哪时用 --intent： - --intent memory —— 个人决策、偏好、人物 - --intent connector —— 代码、PR、邮件、外部数据 - --intent import —— 导入的文件与文档 - 无 flag = 搜索全部（默认，适合发现） ### 生命周期运行器定时 `bash # 每晚 dry-run + 应用（launchd 或 cron） cortex lifecycle run --dry-run > /tmp/lifecycle-plan.log 2>&1 # 若发现异常，则应用： cortex lifecycle run ` 建议：每天 3:30 AM。第一周仅 dry-run，查看日志。 ### 策略预设 新智能体（< 500 事实）： `yaml policies: reinforce_promote: min_reinforcements: 3 min_sources: 2 decay_retire: inactive_days: 90 confidence_below: 0.25 conflict_supersede: min_confidence_delta: 0.20 ` 成熟智能体（2000+ 事实）： `yaml policies: reinforce_promote: min_reinforcements: 5 min_sources: 3 decay_retire: inactive_days: 45 confidence_below: 0.35 conflict_supersede: min_confidence_delta: 0.10 ` ### 导入后清理 批量导入后运行： `bash cortex cleanup --dedup-facts # 移除近似重复 cortex conflicts --auto-resolve # 解决矛盾 ` ### 推荐的 OpenClaw 搜索链（更新） ` memory_search → cortex answer（综合） → cortex search（指针） → QMD → ripgrep → web ``