内容
# CerebroCortex-RS
> 一个类似大脑的人工智能记忆系统 — 纯Rust，单个二进制文件，可在Pi Zero W2上运行。
[](https://rustup.rs)
[](LICENSE)
[]()
**66个MCP工具。一个SQLite文件。无需外部进程。直接替换Python原版 — agentd完全不知晓。**
---
## 简介
CerebroCortex-RS是[CerebroCortex](https://github.com/buckster123/CerebroCortex)的完整Rust移植版，一个用于AI代理的认知记忆系统。它通过stdio公开了66个MCP工具，实现了ACT-R激活、FSRS间隔重复、传播激活和6阶段梦境巩固引擎 — 所有这些都在一个单独的静态链接二进制文件中，无需Python运行时、无需单独的向量DB进程，也无需GPU。
```
裸二进制文件（无模型）： 23 MB RSS， 6线程， 26毫秒召回
使用BGE-small-en-v1.5：275 MB RSS， 9线程， 26毫秒召回（余弦ANN）
二进制文件大小： 29 MB剥离arm64 ELF
冷启动： ~4.4秒（图重建 + 模型加载缓存）
```
热交换到一个运行中的[ApexOS](https://github.com/buckster123/ApexOS) Pi 5，只需更改`plugins.toml`中的一行。agentd计数到66个工具并继续运行。
---
## 为什么
| | Python | Rust |
|---|---|---|
| 运行时 | CPython + venv + pip | 单个二进制文件 |
| 向量数据库 | chromadb（独立进程） | sqlite-vec（SQLite扩展） |
| 图 | python-igraph（C绑定） | petgraph（纯Rust） |
| 嵌入 | sentence-transformers（PyTorch） | fastembed（ONNX，~33 MB模型） |
| REST | FastAPI + uvicorn | axum |
| MCP | MCP Python SDK | 手动编写的JSON-RPC over stdio |
| 空闲RAM | ~180 MB | 23 MB（无模型）/ 275 MB（有模型） |
| Pi Zero W2能力 | 否 | 是（禁用嵌入） |
| 数据库迁移 | 手动 | 自动检测和迁移Python `cerebro.db` |
**关键见解：** `sqlite-vec` + FTS5意味着整个存储层 — 关系数据、全文本搜索和近似最近邻向量搜索 — 生活在**一个SQLite文件中**。无需额外进程，无需网络调用进行检索。
---
## 架构
```mermaid
graph TB
subgraph Binaries
MCP[cerebro-mcp\nMCP stdio server\n66 tools]
API[cerebro-api\naxum REST API\nport 8767]
CLI[cerebro\nclap CLI]
end
subgraph Library["cerebro (lib)"]
Cortex[cortex.rs\nCoordinator]
subgraph Engines
TH[Thalamus\nGating]
AM[Amygdala\nEmotion]
TE[Temporal\nConcepts]
HI[Hippocampus\nEpisodic]
AS[Association\nLinks]
CB[Cerebellum\nProcedural]
PF[Prefrontal\nExecutive]
NC[Neocortex\nSchemas]
DR[Dream Engine\n6 phases]
end
subgraph Storage
SQ[(SQLite\nsource of truth)]
VE[sqlite-vec\nANN + FTS5]
GR[petgraph\nin-memory graph]
end
end
MCP --> Cortex
API --> Cortex
CLI --> Cortex
Cortex --> Engines
Cortex --> Storage
VE --> SQ
GR --> SQ
```
### 工作空间布局
```
crates/
cerebro/ # library — all cognitive logic (types, models, activation, engines, storage)
cerebro-mcp/ # MCP-over-stdio binary — ApexOS drop-in, 66 tools
cerebro-api/ # axum REST API + dashboard (optional, port 8767)
cerebro-cli/ # clap CLI (cerebro remember / recall / stats / dream ...)
```
---
## 记忆管道
### remember()
```mermaid
flowchart LR
Input([content]) --> TH[Thalamus\nsalience gate]
TH -->|passes| AM[Amygdala\nvalence + arousal]
AM --> TE[Temporal\nconcepts + bigrams]
TE --> SQ[(SQLite\ninsert)]
SQ --> VE[fastembed\n384-dim embed]
SQ --> GR[petgraph\nadd node + links]
VE --> SQ2[(memory_vectors\nvec0 index)]
GR --> Result([MemoryNode])
```
### recall()
```mermaid
flowchart LR
Query([query]) --> VEC[sqlite-vec\ncosine ANN]
Query --> FTS[FTS5\nkeyword fallback]
VEC -->|top-k candidates| ACT[Spreading Activation\nCollins & Loftus\n2 hops · 0.6 decay]
FTS --> ACT
ACT --> LOAD[bulk SQLite load]
LOAD --> PF[Prefrontal\nranking]
PF --> Results([ranked memories])
```
**召回分数：**
```
score = 0.35 × vector_sim + 0.30 × ACT-R + 0.20 × FSRS + 0.15 × salience
```
---
## 认知模型
### 记忆类型和层
```
MemoryType: Episodic | Semantic | Procedural | Affective | Prospective | Schematic
MemoryLayer: Sensory (minutes) → Working (days) → LongTerm (months) → Cortex (permanent)
Visibility: Private (agent-only) | Shared (all agents) | Thread (cross-agent dialogue)
```
### 激活数学
**ACT-R基准激活** — 最近度 + 频率衰减：
```
B(t) = ln( Σ t_k^{-d} ) + ε
```
- `t_k` = 秒数，自第k次访问以来，`d` = 0.5，`ε` ~ 均匀分布(±0.4)
- 访问时间戳上限为50个记忆
**FSRS可检索性** — 间隔重复遗忘曲线：
```
R(t, S) = (1 + t / 9S)^{-1}
```
- `t` = 天数，自上次复习以来，`S` = 稳定性（天）
- S在检索时更新：成功 → 增长，失败 → `S × 0.5`
**传播激活** — Collins & Loftus：
- 从种子节点进行BFS，最大2跳，0.6衰减/跳，50节点上限
- 边传导率 = `link_type_weight × link.effective_weight(now)`
- 链接权重随30天半衰期衰减
---
## 梦境引擎 — 6阶段巩固
```mermaid
flowchart LR
SWS[Phase 1\nSWS Replay\nalgorithmic] --> PAT[Phase 2\nPattern Extraction\nLLM]
PAT --> SCH[Phase 3\nSchema Formation\nLLM]
SCH --> EMO[Phase 4\nEmotional Reprocessing\nalgorithmic]
EMO --> PRU[Phase 5\nPruning\nalgorithmic]
PRU --> REM[Phase 6\nREM Recombination\nLLM]
```
| 阶段 | 引擎 | 描述 |
|-------|--------|-------------|
| 1 — SWS重放 | 算法 | 重放最近的事件；加强时间链接 |
| 2 — 模式提取 | LLM | 聚类相似的记忆；总结新兴模式 |
| 3 — 模式形成 | LLM | 抽象事件记忆 → 模式记忆 |
| 4 — 情感再处理 | 算法 | 根据情感标记调整显著性 |
| 5 — 精炼 | 算法 | 删除陈旧、低显著性、孤立的感官记忆 |
| 6 — REM重组 | LLM | 表面图上的非显式连接 |
LLM阶段需要`ANTHROPIC_API_KEY`。如果未设置，则阶段2、3、6会顺利跳过 — 算法阶段始终运行。LLM调用预算：每个梦境循环每个代理20次调用。
---
## 多代理隔离
```mermaid
graph TB
subgraph Agents
A1[FORGE ⚒]
A2[GROK]
A3[COMPOSER]
A4[CLAUDE-APEX]
end
subgraph VisibilityScope
VS{agent_id filter\nSQL fragment}
end
subgraph Storage
PRIV1[(FORGE private)]
PRIV2[(GROK private)]
SHARED[(shared pool)]
end
A1 -->|agent_id=FORGE| VS
A2 -->|agent_id=GROK| VS
A3 -->|agent_id=COMPOSER| VS
A4 -->|agent_id=CLAUDE-APEX| VS
VS --> PRIV1
VS --> PRIV2
VS --> SHARED
```
每个SQL查询都带有`VisibilityScope`，它会注入一个过滤器：
```sql
-- FORGE的私有查询：
WHERE (visibility='shared' OR (visibility='private' AND agent_id='FORGE'))
AND deleted_at IS NULL
```
代理可以`share_memory`以促进私有 → 共享，`send_message`用于跨代理收件箱传递，`get_thread_memories`用于共享对话上下文。
---
## MCP工具表面（66个工具）
<details>
<summary>按类别划分的完整工具列表</summary>
| 类别 | 工具 |
|----------|-------|
| 核心 | `remember`, `recall`, `get_memory`, `memory_store`, `memory_search`, `update_memory`, `delete_memory` |
| 关联 | `associate`, `memory_neighbors`, `common_neighbors`, `find_path`, `check_near_duplicates` |
| 会话/线程 | `session_save`, `session_recall`, `get_thread_memories`, `list_threads`, `prune_thread` |
| 事件 | `episode_start`, `episode_add_step`, `episode_end`, `get_episode`, `get_episode_memories`, `list_episodes` |
| 梦境 | `dream_run`, `dream_status` |
| 前瞻性 | `store_intention`, `list_intentions`, `resolve_intention` |
| 程序 | `store_procedure`, `list_procedures`, `find_relevant_procedures`, `record_procedure_outcome` |
| 模式 | `create_schema`, `list_schemas`, `find_matching_schemas`, `get_schema_sources` |
| 分析 | `emotional_summary`, `activation_curve`, `activation_heatmap`, `activation_at_risk`, `memory_health`, `cortex_stats`, `memory_graph_stats`, `audit_summary`, `query_audit` |
| 标签 | `list_tags`, `delete_tag`, `rename_tag`, `merge_tags` |
| 多代理 | `register_agent`, `list_agents`, `share_memory`, `send_message`, `check_inbox` |
| 生命周期 | `list_deleted`, `restore_memory`, `purge_memory`, `bulk_delete`, `purge_all_deleted`, `get_memory_versions`, `restore_version` |
| 导出 | `export_memories` |
| 引导 | `cognitive_bootstrap`, `ingest_file`, `describe_image`, `search_vision` |
</details>
Wire格式：每行分隔的JSON-RPC 2.0，stdin/stdout。协议版本`"2024-11-05"`。stderr仅用于跟踪日志 — stdout是MCP流。
---
## 存储
**SQLite是单一的事实来源。** 图和向量索引是启动时重建的缓存。
```
memories — 19 columns; access_times JSON for ACT-R; embedding BLOB for vec0
links — (source_id, target_id, link_type) PK; traversal stats for decay
memories_fts — FTS5 virtual table; INSERT/UPDATE/DELETE triggers keep it in sync
memory_vectors — vec0 virtual table (sqlite-vec); rowid-joined to memories
audit_log — append-only agent action log
episodes / steps — episodic sequence storage
dream_reports — persisted dream cycle output
schema_version — migration tracking (version 100 = migrated from Python schema)
```
**Python DB自动迁移：** 将`CEREBRO_DATA_DIR`指向现有的Python `cerebro.db`并启动二进制文件。`SqliteStore::open()`检测Python模式，在单个原子事务中进行迁移，并使用`schema_version=100`标记完成。后续启动是noop。旧Python表保留为 `_py_*`以确保安全。
---
## 部署
### ApexOS替换（Pi 5）
```toml
# /etc/agentd/plugins.toml
[[plugin]]
id = "cerebro"
cmd = "cerebro-mcp"
restart = "always"
[plugin.env]
CEREBRO_DATA_DIR = "/var/lib/agentd/cerebro"
FASTEMBED_CACHE_DIR = "/var/lib/agentd/cerebro/models"
RUST_LOG = "warn"
```
```bash
sudo systemctl restart agentd
# [supervisor] plugin 'cerebro' up — 66 tools
```
### 在Pi上构建（arm64）
始终本地构建 — 绝不交叉编译。
```bash
git pull
cargo build --release -p cerebro-mcp
sudo systemctl stop cerebro-mcp
sudo cp target/release/cerebro-mcp /usr/local/bin/cerebro-mcp
sudo systemctl start cerebro-mcp
```
### fastembed预热
在第一个部署时，将模型下载到缓存目录，以便agentd启动它：
```bash
sudo mkdir -p /var/lib/agentd/cerebro/models
sudo chown agentd:agentd /var/lib/agentd/cerebro/models
# 以服务用户身份运行 — 下载首次运行时约128 MB
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"prewarm","version":"0.1"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"remember","arguments":{"content":"prewarm","memory_type":"semantic"}}}\n' | \
sudo -u agentd env \
CEREBRO_DATA_DIR=/var/lib/agentd/cerebro \
FASTEMBED_CACHE_DIR=/var/lib/agentd/cerebro/models \
/usr/local/bin/cerebro-mcp`
```
### 平台层级
相同的二进制文件，不同的环境变量。每个设备无需特殊构建。
| 层级 | 硬件 | `CEREBRO_EMBED_MODEL` | RSS | 搜索 |
|------|----------|-----------------------|-----|--------|
| **Nano** | Pi Zero 2W, 任意512MB板 | `""`（禁用） | ~23 MB | FTS5关键词 |
| **Micro** | Pi 4 1-2GB | `BAAI/bge-small-en-v1.5` | ~275 MB | 余弦ANN（384-dim） |
| **Standard** | Pi 5, x86 mini-PC | `BAAI/bge-small-en-v1.5` | ~275 MB | 余弦ANN |
| **Pro** | x86 + GPU (CUDA/ROCm/CoreML) | `BAAI/bge-large-en-v1.5`* | ~500 MB | 余弦ANN（1024-dim） |
\* `bge-large`支持和GPU ONNX执行提供程序正在计划中 — 今天CPU在所有地方都有效，GPU是附加的。
**这很重要：** Pi 5 16GB现在售价$300+。真正的目标是抽屉里的硬件 — 上一代迷你PC、替换Mac Mini、之前的Pi 4。如果设置`CEREBRO_EMBED_MODEL=""`，整个内存系统在23 MB RSS中运行，留下其余部分用于agentd、本地推理和操作系统。
### 在没有嵌入的情况下运行（Pi Zero W2 / 1 GB设备）
设置`CEREBRO_EMBED_MODEL=""` — 跳过fastembed init，FTS5处理所有搜索。RSS保持~23 MB。召回延迟不变（~26毫秒，纯FTS5 + 传播激活）。
---
## 环境变量
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `CEREBRO_DATA_DIR` | `~/.cerebro-cortex/` | SQLite DB根目录 |
| `CEREBRO_EMBED_MODEL` | `BAAI/bge-small-en-v1.5` | fastembed模型ID（空 = 禁用） |
| `FASTEMBED_CACHE_DIR` | `.fastembed_cache` | 模型缓存目录 |
| `ANTHROPIC_API_KEY` | — | 梦境引擎LLM阶段（2, 3, 6）所需 |
| `RUST_LOG` | `info` | 跟踪过滤器 — 日志输出到stderr |
---
## 从源码构建
```bash
git clone https://github.com/buckster123/CerebroCortex-RS
cd CerebroCortex-RS
cargo build --release # all four crates
cargo test # 116 tests
```
**测试套件：
| 套件 | 测试 | 门控 |
|-------|-------|------|
| types | 6 | serde round-trips |
| activation | 41 | ACT-R + FSRS + spreading vs Python fixtures (within 1e-4) |
| storage | 21 | SQLite CRUD, vector search, graph rebuild |
| engines | 34 | all 8 deterministic engines |
| cortex | 6 | end-to-end remember + recall |
| cerebro-mcp | 8 | MCP dispatch + tool routing |
| db_compat | 2 | Python → Rust DB migration |
| **total** | **118** | |
---
## 相关
- [CerebroCortex](https://github.com/buckster123/CerebroCortex) — Python原版（参考实现，每天生产环境驱动）
- [ApexOS](https://github.com/buckster123/ApexOS) — 代理运行时此插件插入其中
---
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器