Claude Cortex Core

克劳德皮质核心

克劳德皮质核心 是一个最小的、生产就绪的MCP（模型上下文协议）服务器，它为Claude Code提供了持久的大脑般的记忆。这是一个精简的叉子 claude-cortex 它删除了所有非必要的子系统，同时保留了完整的记忆/回忆/遗忘/整合管道。

关键统计数据

• 依赖项：3个生产部门（低于7个）

- @modelcontextprotocol/sdk -MCP协议 - better-sqlite3 -数据库 - zod -架构验证

• 尺寸：75MB节点模块（从~150MB+下降）
• 代码：15个源文件中有4748行
• 攻击面：零网络连接，无HTTP服务器，无外部模型下载
• 工具：15个用于内存操作的MCP工具

删除了什么

• ❌ 仪表板（Next.js+Three.js 3D大脑可视化）
• ❌ API服务器（Express+WebSocket）
• ❌ 嵌入（@huggingface/transfers语义搜索）
• ❌ 传播激活（临时会话状态）
• ❌ 矛盾检测（主动分析）
• ❌ 脑力劳动者（背景滴答声处理）
• ❌ 维修安装程序（自动启动系统）
• ✅ 钩子脚本（SessionStart、PreCompact）- 现在重新添加为可选功能

原版 克劳德皮层 有两个钩子，可以自动保存。这些已在 克劳德皮层核心 作为保持最低理念的独立可执行文件。

这些是 完全可选 并且可以通过配置Claude Code挂钩来启用。有关设置说明，请参阅下面的“自动内存挂钩”部分。

留下什么

• ✅ 完整的内存管道
• ✅ FTS5全文搜索（内置SQLite）
• ✅ 时间衰减与强化
• ✅ 自动显著性检测
• ✅ STM → LTM整合
• ✅ 项目自动范围界定
• ✅ 记忆关系（链接）
• ✅ 丰富（上下文积累）
• ✅ Hebbian学习（共同访问加强）

预期工作流程

主动手动保存：

• 做出决定后→ 记住（{标题：“…”，内容：“……”}）
• 修复错误后→ 记住（{标题：“…”，内容：“……”}）
• 在学习了一些东西之后→ 记住（{标题：“…”，内容：“……”}）
• 会话开始时→ get_text（）用于恢复上下文

权衡是：更多的控制，更少的魔法。你决定什么值得记住， 而不是依赖于自动启发式。

安装和设置

# Clone or download the repository
git clone https://github.com/michaelv2/claude-cortex-core.git
cd claude-cortex-core

# Install dependencies
npm install

# Build the project
npm run build

# Add MCP server to Claude Code (use absolute path)
claude mcp add memory node $(pwd)/dist/index.js

# Verify it's connected
claude mcp list
# Should show: memory: ... - ✓ Connected

重要：使用 claude mcp add 命令，而不是手动编辑配置文件。Claude Code将MCP服务器存储在 ~/.claude.json CLI命令可确保正确注册。

自动内存挂钩（可选）

Claude Cortex Core现在包括 可选的自动内存挂钩 它们的灵感来自最初的克劳德皮层。这些钩子可以自动提取和恢复记忆，而无需手动调用工具。

可用挂钩

1.预紧钩

在上下文压缩之前自动提取内存：

• 扫描对话中的突出内容
• 自动提取决策、修复、学习、模式
• 每次压缩最多可保存5个内存
• 带有“自动提取”的标签

2.会话启动钩子

会话开始时自动恢复上下文：

• 加载项目特定上下文
• 显示架构决策、模式、偏好
• 显示多达15个高显著性记忆

设置

1. 构建项目 （钩子与主服务器一起编译）：

npm run build

1. 添加MCP服务器 （如果尚未完成）：

claude mcp add memory node $(pwd)/dist/index.js

1. 在Claude代码中配置钩子 通过编辑 ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/claude-cortex-core/dist/bin/session-start.js"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/claude-cortex-core/dist/bin/pre-compact.js"
          }
        ]
      }
    ]
  }
}

备注：替换 /path/to/claude-cortex-core 使用您的实际安装路径。应使用以下方式添加MCP服务器 claude mcp add （步骤2），不要在settings.json中手动操作。

1. 可选：自定义挂钩行为 (~/.claude-cortex/hooks.json):

{
  "preCompact": {
    "enabled": true,
    "minSalience": 0.30,
    "maxMemoriesPerCompact": 5,
    "categories": ["architecture", "pattern", "error", "learning"],
    "autoTag": "auto-extracted",
    "timeout": 5000
  },
  "sessionStart": {
    "enabled": true,
    "maxMemories": 15,
    "minSalience": 0.5,
    "categories": ["architecture", "pattern", "preference"],
    "format": "summary",
    "timeout": 3000
  }
}

复制 hooks.json.example 到 ~/.claude-cortex/hooks.json 作为一个起点。

挂钩配置选项

PreCompact挂钩:

• enabled -启用/禁用挂钩（默认值：true）
• minSalience -最小重要性阈值（默认值：0.30）
• maxMemoriesPerCompact -每次压缩可保存的最大内存（默认值：5）
• categories -自动提取哪些类别（默认：架构、模式、错误、学习）
• autoTag -标签已添加到自动提取的内存中（默认：“自动提取”）
• timeout -最大处理时间（毫秒）（默认值：5000）

会话启动挂钩:

• enabled -启用/禁用挂钩（默认值：true）
• maxMemories -要加载的最大上下文项数（默认值：15）
• minSalience -最小重要性阈值（默认值：0.5）
• categories -要包括哪些类别（默认：架构、模式、首选项）
• format -输出格式：“摘要”、“详细”或“最小”（默认为“摘要”）
• timeout -最大处理时间（毫秒）（默认值：3000）

利益与权衡

好处:

• 自动存储，无需手动 remember() 电话
• 会话开始时自动恢复上下文
• 每个项目的可配置行为
• 故障安全：钩子故障永远不会破坏克劳德代码

权衡:

• 模式匹配可能会提取误报
• 为压缩增加1-3秒的延迟
• 需要Claude Code挂钩支持
• 与手动保存相比，控制更少

禁用挂钩

要禁用而不从Claude Code配置中删除，请设置 enabled: false 在 ~/.claude-cortex/hooks.json:

{
  "preCompact": { "enabled": false },
  "sessionStart": { "enabled": false }
}

或删除 hooks 部分从 ~/.claude/settings.json 完全。

故障排除

MCP服务器未连接

如果在安装后看到“未配置MCP服务器”：

1. 验证服务器是否已正确添加:

claude mcp list
# Should show: memory: ... - ✓ Connected

1. 如果未列出，请使用CLI添加 （不要手动编辑配置文件）：

cd /path/to/claude-cortex-core
claude mcp add memory node $(pwd)/dist/index.js

1. 检查服务器运行状况:

claude mcp get memory
# Should show: Status: ✓ Connected

1. 手动测试服务器:

cd /path/to/claude-cortex-core
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js
# Should return JSON response with server info

1. 必要时重建:

npm run build
claude mcp remove memory
claude mcp add memory node $(pwd)/dist/index.js

常见问题

• “未找到MCP服务器”：使用 claude mcp add 而不是手动编辑配置文件
• 服务器不在列表中：MCP服务器存储在 ~/.claude.json （项目特定）或全局配置，不是 ~/.claude/settings.json
• 构建错误：确保你有Node.js≥18.0.0并运行 npm install
• 权限不足：确保 dist/index.js 可读(chmod +r dist/index.js)

用法示例

基本内存操作

# Store a memory
remember({
  title: "Authentication uses JWT tokens",
  content: "The auth system uses JWT tokens with 24h expiry. Refresh tokens stored in httpOnly cookies.",
  category: "architecture",
  importance: "high"
})

# Search memories
recall({
  query: "authentication",
  limit: 5
})

# Get context at session start
get_context({
  query: "What was I working on?"
})

# Delete old memories
forget({
  olderThan: 30,  // days
  dryRun: true    // preview first
})

# Run consolidation (like brain sleep)
consolidate({
  dryRun: false
})

# View statistics
memory_stats()

项目范围界定

内存会自动作用于从中检测到的项目 process.cwd():

# Current project
get_project()
# → "claude-cortex-core" (detected from /path/to/claude-cortex-core)

# Switch to global scope
set_project({ project: "*" })

# Recall across all projects
recall({
  query: "typescript patterns",
  project: "*"
})

高级功能

内存链接 -自动检测到的关系：

# View related memories
get_related({ id: 42 })

# Manually create a link
link_memories({
  sourceId: 42,
  targetId: 87,
  relationship: "references",
  strength: 0.8
})

会话 -跟踪工作周期：

start_session({ project: "my-app" })
# → Returns session ID + context summary

# ... do work, create memories ...

end_session({
  sessionId: 123,
  summary: "Implemented user authentication"
})
# → Triggers consolidation

导出/导入 -备份或传输：

# Export
export_memories({ project: "my-app" })
# → Returns JSON

# Import
import_memories({ data: "[...]" })

运作原理

内存类型

• 短期的 （STM）-最近的工作记忆（最多250个）
• 长期 （LTM）-整合的重要记忆（最多5000个）
• 情节性的 -会话标记和时间戳

分类

architecture, pattern, preference, error, context, learning, todo, note, relationship, custom

显著性（重要性）

• 根据内容自动计算（0.0-1.0）
• 基于：显式请求、架构关键字、错误模式、代码引用、情感标记
• 在收益递减的情况下加强准入

时间衰减

• 记忆会随着时间的推移而褪色（指数衰减）
• LTM的衰减速度比STM慢（每日vs每小时）
• 访问计数减缓衰减（最多慢30%）
• 特定类别的删除阈值（架构更难删除）

整合

服务器启动时每4小时自动运行一次：

1. 促进高度显著的STM→ LTM
2. 删除低于阈值的衰减内存
3. 强制内存限制（250 STM，5000 LTM）
4. 更新衰变分数
5. 增强中枢记忆（高度关联）

搜索

FTS5全文搜索与相关性评分：

• 关键字匹配（30%）
• 腐烂分数（25%）
• 优先级分数（10%）
• 近期增长（0-10%）
• 类别匹配（0-10%）
• 链接增强（0-15%）
• 标签匹配（0-10%）

前5个结果会自动增强。

数据库位置

~/.claude-cortex/memories.db （带WAL模式的SQLite）

传统路径 ~/.claude-memory/ 仍然适用于向后兼容性。

表格

• memories -核心内存存储
• memories_fts -全文搜索索引（FTS5）
• sessions -会话跟踪
• memory_links -记忆之间的关系

反Bloat保障措施

• 每个内存内容限制为10KB（带截断警告）
• 100MB数据库硬限制
• 每4小时自动整合一次
• 删除后自动抽真空
• 250 STM/5000 LTM强制限制

发展

# Watch mode
npm run dev

# Build
npm run build

# Custom database path
node dist/index.js --db /path/to/custom.db

与原版的主要区别

何时使用Which

在以下情况下使用克劳德皮质核心：

• 您希望最小化依赖关系
• 你不需要仪表板
• 您信任FTS5关键字搜索
• 你想要快速启动
• 您正在生产环境中进行部署

在以下情况下使用克劳德皮质：

• 您需要语义搜索（嵌入）
• 你想要3D大脑可视化
• 您需要API仪表板
• 你正在探索/实验

备注

• 所有15个MCP工具的工作原理与原始工具相同
• 现有数据库兼容（忽略未使用的列）
• 项目自动检测的工作方式相同
• 内存格式不变
• MCP接口无中断更改

该系统已准备好投入生产，并针对速度、简单性和安全性进行了优化。