Post-Cortex

面向AI助手的生产级智能内存系统

Post-Cortex 是一个高性能的 MCP（模型上下文协议）服务器，它将短暂的AI对话转换为持久且可搜索的知识，并保证零死锁。使用 Rust 编写并采用无锁并发架构，它使AI助手能够在会话之间维持完美的记忆，理解语义关系，并通过本地AI驱动的搜索检索上下文相关的数据。

核心特性

• 持久内存系统：三级分层存储（热/温/冷），使用 RocksDB 持久化
• 语义搜索引擎：本地变压器模型，支持可配置的精度/速度模式
• NER 动力知识图谱：使用 DistilBERT 自动实体提取，准确率超过95%
• 隐私优先架构：所有处理都在本地进行，无需外部API依赖
• 无锁并发：通过原子操作和 DashMap 实现零死锁保证
• 生产就绪性能：搜索速度提升6-8倍，内存压缩比192倍，I/O延迟改善10-50倍

性能亮点

阶段1-3，6项优化完成：

• 语义搜索：加速6.70倍（从6.7毫秒到1毫秒，近似模式）
• RocksDB I/O：通过 spawn_blocking 减少10-50倍的延迟
• 内存：使用产品量化压缩192倍（从153MB到800KB）
• 测试执行：加速22倍（从45秒到2秒）
• NER 引擎：懒加载和模式回退下准确率超过95%

快速开始

安装

Post-Cortex 提供了两个二进制文件：

1. post-cortex - 用于与 Claude Desktop 集成的标准IO MCP服务器
2. post-cortex-daemon - 用于API使用和后台服务的HTTP守护进程服务器

Homebrew (macOS/Linux) - 推荐：

brew install julymetodiev/tap/post-cortex

这将安装两个二进制文件：post-cortex 和 post-cortex-daemon

直接下载：

从 最新发布 下载适用于您平台的二进制文件：

# post-cortex (标准IO MCP服务器)
# macOS Intel:        post-cortex-x86_64-apple-darwin
# macOS Apple Silicon: post-cortex-aarch64-apple-darwin
# Linux:              post-cortex-x86_64-unknown-linux-gnu

# post-cortex-daemon (HTTP守护进程)
# macOS Intel:        post-cortex-daemon-x86_64-apple-darwin
# macOS Apple Silicon: post-cortex-daemon-aarch64-apple-darwin
# Linux:              post-cortex-daemon-x86_64-unknown-linux-gnu

# 示例安装（macOS Apple Silicon）：
curl -L https://github.com/julymetodiev/post-cortex/releases/latest/download/post-cortex-aarch64-apple-darwin -o /usr/local/bin/post-cortex && chmod +x /usr/local/bin/post-cortex
curl -L https://github.com/julymetodiev/post-cortex/releases/latest/download/post-cortex-daemon-aarch64-apple-darwin -o /usr/local/bin/post-cortex-daemon && chmod +x /usr/local/bin/post-cortex-daemon

从源码构建：

cargo build --release --features embeddings
# 生成的二进制文件：target/release/post-cortex 和 target/release/post-cortex-daemon

使用模式

Post-Cortex 提供两种部署选项：

1. 标准IO模式（简单 - Claude Desktop集成）

使用 post-cortex 二进制文件进行直接标准IO MCP集成：

# 手动运行（用于测试）
post-cortex

# 或从源码运行
./target/release/post-cortex

优点：

• 基于标准IO的简单MCP服务器
• 不需要守护进程
• 适合单项目工作流
• 直接与 Claude Desktop 集成

Claude Desktop 配置：

{
  "mcpServers": {
    "post-cortex": {
      "command": "post-cortex"
    }
  }
}

或使用绝对路径：

{
  "mcpServers": {
    "post-cortex": {
      "command": "/usr/local/bin/post-cortex"
    }
  }
}

2. 守护进程模式（高级 - HTTP API + 后台服务）

使用 post-cortex-daemon 二进制文件启动持久的HTTP服务器：

# 初始化配置（可选）
post-cortex-daemon init

# 在前台启动守护进程
post-cortex-daemon start

# 查看状态
post-cortex-daemon status

# 停止守护进程
post-cortex-daemon stop

优点：

• 多个AI助手之间的共享会话
• 单一 RocksDB 实例（避免锁冲突）
• HTTP RMCP API 默认在3737端口
• 通过systemd/launchd实现持久后台服务
• RESTful健康和统计端点

Claude Desktop 配置：

{
  "mcpServers": {
    "post-cortex": {
      "type": "sse",
      "url": "http://localhost:3737/sse"
    }
  }
}

配置文件：~/.post-cortex/daemon.toml

host = "127.0.0.1"
port = 3737
data_dir = "~/.post-cortex/data"

环境变量：

• PC_HOST - 覆盖主机（默认：127.0.0.1）
• PC_PORT - 覆盖端口（默认：3737）
• PC_DATA_DIR - 覆盖数据目录
• RUST_LOG - 日志级别（例如：RUST_LOG=debug）

服务管理（守护进程模式）

Linux (systemd)

# 复制服务文件
cp install/systemd/post-cortex.service ~/.config/systemd/user/
systemctl --user daemon-reload

# 开启并设置自动启动
systemctl --user enable --now post-cortex

# 查看日志
journalctl --user -u post-cortex -f

详见 install/systemd/README.md 的详细说明。

macOS (launchd)

# 复制plist文件
cp install/launchd/com.post-cortex.daemon.plist ~/Library/LaunchAgents/

# 加载并启动
launchctl load ~/Library/LaunchAgents/com.post-cortex.daemon.plist

# 查看日志
tail -f /tmp/post-cortex.log

详见 install/launchd/README.md 的详细说明。

推荐：

• 使用标准IO模式进行简单的 Claude Desktop 集成
• 使用守护进程模式进行多项目工作流、API访问或后台服务

二进制文件间的数据共享

重要：post-cortex 和 post-cortex-daemon 共享相同的代码库和数据格式，这意味着：

✅ 您可以同时使用两个二进制文件共享同一个数据库，只要它们不同时运行

• 默认数据目录：~/.post-cortex/data（两者共享）
• 在标准IO和守护进程模式之间自由切换而不会丢失数据
• 所有会话、嵌入式向量、HNSW索引、实体图和工作空间都得以保存

在模式之间切换时共享的内容：

• 所有的对话会话和历史记录
• 实体图及其关系
• 语义嵌入（384维向量）
• HNSW搜索索引
• 工作空间和元数据
• 热/温/冷内存状态在 RocksDB 中持久化

为什么这可行： 两个二进制文件使用完全相同的存储逻辑来自 src/storage/rocksdb_storage.rs。唯一的限制是 RocksDB 文件锁，这阻止了同时访问，但在进程停止时会自动释放。

示例工作流程：

# 上午：使用守护进程模式
post-cortex-daemon start
# 工作，创建会话，添加数据...
post-cortex-daemon stop

# 下午：切换到通过 Claude Desktop 的标准IO
# Claude Desktop 配置：{"command": "post-cortex"}
# 守护进程的所有会话都可以使用！

# 晚上：回到守护进程
post-cortex-daemon start
# 所有来自标准IO模式的数据都在这里！

使用单独的数据库（可选）：

如果您需要隔离的数据库用于测试或不同的项目：

对于标准IO模式 - 设置在 Claude Desktop 配置中：

{
  "mcpServers": {
    "post-cortex": {
      "command": "post-cortex",
      "env": {
        "PC_DATA_DIR": "~/.post-cortex/stdio-data"
      }
    }
  }
}

对于守护进程模式 - 使用环境变量或配置文件：

PC_DATA_DIR=~/.post-cortex/daemon-data post-cortex-daemon start

或在 ~/.post-cortex/daemon.toml 中：

data_directory = "~/.post-cortex/daemon-data"

⚠️ 注意：使用单独的目录，数据不会共享 - 每个实例都有独立的会话和索引。

为您的项目设置

1. 在项目根目录创建一个 CLAUDE.md 文件：

# CLAUDE.md

## 使用 Post-Cortex 进行知识管理

**项目会话ID**：`YOUR-SESSION-ID-HERE`

**在整个对话过程中：**
- 使用 `update_conversation_context(session_id: "YOUR-SESSION-ID")` 添加上下文
- 使用 `semantic_search_session(session_id: "YOUR-SESSION-ID")` 查询

2. 创建您的项目会话：

询问您的AI助手：

"为这个项目创建一个 Post-Cortex 会话"

3. 将返回的 session_id 添加到 CLAUDE.md

就这样！您的AI现在为这个项目有了持久的记忆。

搜索模式（第6阶段优化）

Post-Cortex 提供三种可配置的搜索模式以优化精度/速度权衡：

SearchMode 选项：

• 精确：完整的线性扫描 - 100%精度，最慢（基准：6.7毫秒）
• 近似：HNSW，ef_search=32 - 6.70倍更快，约98%精度（1毫秒）
• 平衡（默认）：HNSW，ef_search=64 - 6倍更快，约99%精度（1.1毫秒）

SearchQualityPreset：

• 快速：ef_search=32
• 平衡：ef_search=64
• 精确：ef_search=128
• 最大：ef_search=256

示例用法：

// 使用平衡模式（默认）
db.search(&query, 10)

// 显式选择模式
db.search_with_mode(&query, 10, SearchMode::Approximate, None)

// 自定义 ef_search 值
db.search_with_mode(&query, 10, SearchMode::Balanced, Some(128))

语义搜索

Post-Cortex 使用本地变压器模型进行隐私优先的语义搜索：

嵌入模型：

• MiniLM（384维，默认） - 平衡性能
• StaticSimilarityMRL（1024维） - 适用于Mac M系列优化
• TinyBERT（312维） - 低内存环境
• BGESmall（384维） - 最大精度

搜索流水线：

1. 文本 → 384维向量（本地变压器）
2. 长文本总结，优先提取
3. 向量在HNSW中索引以快速检索
4. 结果排名：(相似度 × 0.7) + (重要性 × 0.3)

质量评分：

• 0.85-1.00 优秀 - 精确语义匹配
• 0.70-0.84 很好 - 直接匹配
• 0.55-0.69 好 - 相关概念
• 0.40-0.54 中等 - 间接相关
• < 0.30 过滤掉

隐私优先：所有模型都在本地运行，零外部API调用。

NER 动力知识图谱（第3.2阶段）

自动实体提取：

• DistilBERT-NER 模型，准确率超过95%
• 懒加载（按需加载，零启动延迟）
• 模式回退（当模型不可用时，准确率为60-70%）
• 提取：人名、组织、地点、杂项实体

关系映射：

• 映射连接：相关于、导致、实现、解决
• 基于提及和关系的重要性评分
• 活跃会话中有1000多个关系的网络图

生产中的示例：

跟踪了388个实体
映射了1015个关系
顶级：无锁（44次提及）、会话（42次）、搜索（38次）

可用工具（24个MCP工具）

会话管理：

• create_session、load_session、list_sessions、search_sessions
• update_session_metadata

添加上下文：

• update_conversation_context - QA、决策、问题、代码更改
• bulk_update_conversation_context - 批量更新

上下文类型：

• qa - 问题和答案
• decision_made - 架构选择及其理由
• problem_solved - 错误及其解决方案
• code_change - 重构和新功能

搜索：

• semantic_search_session - AI驱动的意义搜索（自动向量化）
• semantic_search_global - 跨所有会话搜索
• query_conversation_context - 快速关键词搜索（小于10毫秒）
• find_related_content - 跨会话相似性

分析：

• get_structured_summary - 完整会话概述
• get_key_decisions、get_key_insights - 决策时间轴
• get_entity_importance_analysis、get_entity_network_view - 实体分析

工作空间管理：

• create_workspace、list_workspaces、get_workspace
• add_session_to_workspace、remove_session_from_workspace

查看完整工具文档

架构

三层内存：

热内存（50项）     → DashMap缓存，即时访问
温内存（200项）   → 压缩缓存，快速访问
冷存储（无限）    → RocksDB持久化

无锁并发：

• 使用 DashMap、ArcSwap 和原子操作
• 异步存储操作的Actor模式
• 生产使用中零死锁
• 线性扩展至CPU核心数

为什么无锁？ 消除：

• 错误锁顺序引起的死锁
• 高并发下的性能瓶颈
• 不可预测的延迟峰值
• 优先级反转

阶段1-3，6项优化：

1. RocksDB：所有异步方法包装在 spawn_blocking 中（I/O加快10-50倍）
2. 产品量化：192倍内存压缩，保留大于90%的精度
3. NER 引擎：DistilBERT，懒加载和模式回退
4. 活动会话：无锁热上下文，使用 DashMap 和 Arc 包装组件
5. 类型错误：使用 thiserror 的 SystemError 枚举，更好的错误处理
6. HNSW 调优：可配置搜索模式，加速6.70倍

性能

实际指标：

• 上下文更新：每秒500+操作，带并行向量化
• 关键词搜索：<10毫秒（实体图查询）
• 语义搜索：1-7毫秒（近似：1毫秒，精确：6.7毫秒）
• 嵌入生成：每秒17-20条文本
• 缓存命中率：约50%（热/温层）
• 查询缓存：约30%命中率

可扩展性（在活跃开发中验证）：

• 跟踪122+对话更新
• 提取898+实体
• 映射1,015+关系
• 索引10k+语义嵌入
• 在数千个并发操作中无死锁

配置

SystemConfig {
    // 内存限制
    max_hot_context_size: 50,
    max_warm_context_size: 200,

    // 语义搜索
    enable_embeddings: true,
    auto_vectorize_on_update: true,
    semantic_search_threshold: 0.7,

    // 存储
    data_directory: "./post_cortex_data",
    cache_capacity: 100,
}

开发

# 运行测试
cargo test --features embeddings

# 使用调试日志运行守护进程
RUST_LOG