brainctl (T Schonleber)

脑ctl

健忘的代理，由SQLite文件修复。

一 brain.db 为您的代理提供跨会话的持久内存——学习的事实、做出的决策、跟踪的实体和切换的状态。无需服务器。没有API密钥。无需LLM电话。

2026年5月17日星期六，代理内存市场在 brainctl.org/市场. 今天Solana上可以创建内存包(brainctl export --sign --mint)市场允许代理商通过以下方式相互买卖这些捆绑包 brainctl marketplace api 从CLI。社区代币随市场一起推出，在此之前故意不在此页面上命名。看 铸币部分 和 市场部分 下面是图元，以及 网站 了解完整的发布故事。

from agentmemory import Brain

brain = Brain(agent_id="my-agent")
ctx = brain.orient(project="api-v2")           # session start: handoff + events + triggers + memories
brain.remember("rate-limit: 100/15s", category="integration")
brain.decide("use Retry-After for backoff", "server controls timing", project="api-v2")
brain.wrap_up("auth module complete", project="api-v2")  # session end: logs + handoff for next run

安装

pip install brainctl

需要Python 3.11+。SQLite是内置的。没有其他强制依赖关系。

pip install brainctl[mcp]     # MCP server — 201 tools for Claude Desktop, Cursor, VS Code
pip install brainctl[vec]     # vector similarity search (sqlite-vec + Ollama)
pip install brainctl[signing] # Ed25519-signed memory exports + optional Solana on-chain pinning
pip install brainctl[all]     # everything

5行示例

from agentmemory import Brain

brain = Brain(agent_id="research-bot")
brain.remember("OpenAI rate-limits at 500k TPM on tier 3", category="integration")
results = brain.search("rate limit")          # FTS5 full-text, stemming, ranked
brain.entity("OpenAI", "service", observations=["500k TPM tier 3", "REST API"])
brain.relate("OpenAI", "provides", "GPT-4o")

功能检查表

内存类型

• convention, decision, environment, identity, integration, lesson, preference, project, user
• 类别控制自然半衰期：身份在约1年内衰减；约1个月内的集成详细信息
• 硬上限：每个代理10000个内存。紧急压缩会淘汰最低置信度条目。

检索模式

• FTS5全文搜索，带词干（默认，零依赖）
• 通过sqlite vec+Ollama nomic嵌入文本实现矢量相似性(brainctl[vec])
• 混合：基于FTS5+矢量结果的互易秩融合
• 上下文配置文件：针对任务类型的命名搜索预设(--profile ops, --profile research等等）
• --benchmark 预设：降低综合评估运行的近因性/显著性

Reranker链

• 意图分类器（正则表达式，10个标签→ 6 配置文件）路由查询 cmd_search
• 通过新近度、显著性、Q值效用和贝叶斯召回置信度对FTS后进行重新排序
• 冷启动：自动检测可用的重新排序后端（交叉编码器>句子转换器>回退）
• 交叉编码器控制： --rerank-top-n 和 --rerank-budget-ms 调整候选窗口+严格的延迟预算
• 头重脚轻的分段展开控制（I6）： --rollout-mode, --rollout-canary-agents, --rollout-canary-percent, --rollback-top-heavy
• 卷展栏控件的环境镜像： BRAINCTL_TOPHEAVY_ROLLOUT_MODE, BRAINCTL_TOPHEAVY_CANARY_AGENTS, BRAINCTL_TOPHEAVY_CANARY_PERCENT, BRAINCTL_TOPHEAVY_ROLLBACK
• CI门控检索回归：P@1/P@5/MRR下降>2%/nDCG@5构建失败

知识图谱

• 类型化实体节点： agent, concept, document, event, location, organization, person, project, service, tool
• 自动实体链接：提及已知实体的记忆会自动创建边缘
• 每个实体编译的真相综合(brainctl entity compile )
• 三级富集层；规范别名已删除(brainctl entity alias add)
• 在图表中分散激活回忆(brain.think(query))

信念修正（AGM）

• 每个代理的信念集，带有置信权重
• 通过以下方式检测和解决冲突 brainctl belief conflicts 和 brainctl belief merge
• 崩溃机制：退相干信念被隔离，恢复候选人浮出水面
• 替代操作上的PII近因门（主动干扰指数）

已签署的出口

• brainctl export --sign 生成一个可移植的Ed25519签名JSON包
• brainctl verify 离线检查签名——无需brainctl进行验证
• 可选： --pin-onchain 将SHA-256哈希作为Solana备忘录事务写入（每个pin约0.001美元）
• 管理钱包： brainctl wallet new 在以下位置创建本地密钥对 ~/.brainctl/wallet.json 适用于没有现有Solana设置的用户
• 记忆永远不会离开机器；只有哈希值上链（选择加入）

Mint（v1，可选 [mint] 额外）

• brainctl export --sign --mint 为每个签名包铸造一个Light Protocol压缩令牌，由您的brainctl钱包拥有
• 捆绑包内容经过AES-256-GCM加密 之前 任何东西都会触及公共存储层（Arweave）——链存储所有权，从不明文存储
• 每个造币厂创建一个Memory NFT风格的代币：可在任何Solana钱包中扫描，可通过Tensor/Magic Eden开箱即用，每个造币场约0.0001美元（Light Protocol的压缩代币程序）
• 默认情况下为Devnet；主网测试版需要 --cluster mainnet-beta 和Helius API密钥
• 设置： pip install 'brainctl[mint]' 然后 cd tools && npm install （实际的mint在Node帮助程序中运行，因为Light Protocol的SDK在v0.23之前仅为TypeScript）
• 代理对代理内存市场的基础；看见 CLAUDE.md §“Mint”代表完整的代理流程

市场（v1.5，可选 [marketplace] 额外）

• brainctl marketplace api ... 推动链式规范内存市场 brainctl.org/市场
• 卖家名单已签署 *证明* （不是预先铸造的代币）；cNFT在结算时及时伪造，每个买家一个新造币厂
• Solana备忘录+Arweave清单上的谈判链——每个状态变化都是一份签名的备忘录，因此任何人都可以单独从链中复制市场状态
• 买家流量： browse → show → settle --submit → status --wait --auto-decrypt --ingest （四个命令中的完整端到端）
• 协商买家流量： `offer

--price-usd N → poll offers → 解决已接受的问题 offer_id`

• 卖家流量： list （公布证据）→ listen （守护进程mints cNFT+在支付成功时释放捆绑密钥）
• 谈判： `offers

, offer, counter, accept, reject, withdraw` --每一个动作都是一个签名的备忘录+Arweave清单，完全可由代理人调用

• 在本地解密您自己的加密包： brainctl bundle decrypt --ciphertext-uri ar://...

从其他提供商导入（v2.6.0）

• brainctl import mem0 --从mem0登机
• brainctl import json --通用JSON摄取（列表或 {"memories":[...]} 形状，也 .jsonl)
• 默认隔离：在范围内进口土地 `imported:

`；审核后晋升到你的主要工作范围

• 接下来将有更多的提供商（zep、cognee、letta、langchain）加入
• 结算时收取2.5%的协议费，美元挂钩定价上限为10000美元，SOL原生预发布（社区代币发布后）。每份清单/报价/柜台/接受/拒绝/提取的固定费用为0.10美元，造币时为0.50美元，提款时为0.10美元 --pin-onchain.Devnet是免费的。
• Auth是基于wallet-signature的-没有API密钥，您的索拉纳钱包 *是* 您的代理人身份
• 设置： pip install 'brainctl[marketplace]' （在顶部添加pynacl [mint])

插件（16个第一方）

代理框架：

交易机器人：

MCP服务器（201个工具）

{
  "mcpServers": {
    "brainctl": {
      "command": "brainctl-mcp"
    }
  }
}

添加 ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json或等效物。完整的工具列表和决策树： MCP_SERVER.md.

CLI参考

brainctl memory add "content" -c convention   # store a memory
brainctl search "query"                       # FTS5 search
brainctl vsearch "semantic query"             # vector search (requires [vec])
brainctl entity create "Alice" -t person      # create entity
brainctl entity relate Alice works_at Acme    # link entities
brainctl event add "deployed v3" -t result    # log an event
brainctl decide "title" -r "rationale"        # record a decision
brainctl export --sign -o bundle.json         # signed export
brainctl verify bundle.json                   # verify a bundle
brainctl wallet new                           # create managed signing wallet
brainctl wallet export-key                    # base58 private key for Phantom/Backpack/Solflare/Glow import
brainctl stats                                # DB overview
brainctl doctor                               # health check
brainctl lint                                 # quality issues
brainctl gaps scan                            # coverage + orphan + broken-edge scans
brainctl consolidate cycle                    # full consolidation pass

Python API（22种方法）

内存生命周期

• 写入门 （W（m））：意外评分拒绝冗余的写入。旁通 force=True.
• 三层路由：高价值记忆得到完整索引；低价值获得轻量级存储。
• 重复抑制：近似重复会强化现有的记忆，而不是创建新行。
• 半衰期衰减：未使用的记忆会按照类别设置的速率褪色。回忆的记忆被强化了。
• 整合Hebbian学习、时间提升、压缩——按照cron时间表运行。

检索基准

使用默认设置进行测试，不调整基准数据。两个线束 树上的船：

• tests/bench/ --单系统检索基线 Brain.search

和 cmd_search，对照CI的回归。

• tests/bench/competitor_runs/ --相同的夹具头对头安全带

配备适用于Mem0、Letta、Zep、Cognee、MemPalace、OpenAI Memory的适配器。 Skip-not-fabricate合约：缺少SDK/neneneba API密钥引发 CompetitorUnavailable 而不是返回假0。每个结果 行携带a provenance 块记录 retrieval_mode, vector_enabled, embedding_model, rerankers_active，以及 满的 search_args 因此JSON是自描述的。

仅限brainctl基线（Brain.search、FTS5）

LongMemEval （289个问题检索友好子集 longmemeval_s):

LongMemEval锁快照 （仅限旧FTS基线与最终锁定，n=289）：

机车 （1982个问题，5个类别，10个对话）：

LOCOMO最新检索操作要点 （n=1982，无LLM检索）：

解释：混合领导会议hit@1, hit@5MRR，以及 多跳hit@5，暂时联系hit@5，并略有痕迹 单跳hit@5.

Brain.search的基线在跳跃密集的类别中仍然较弱 （单跳/多跳hit@1 0.167 / 0.174).根本原因：近期和 显著性重评者倾向于最近的记忆；伦敦奥组委使用制服 具有黄金证据的合成时间戳集中在早期会话中， 因此，重新排序可以对抗词汇证据。A. --benchmark 预设 平坦化新近性/显著性可用于评估运行。

头重脚轻的推出和来源（I2/I3/I4/I6）

• 推出政策分阶段进行，金丝雀优先：从 --rollout-mode canary，然后移动到 on 护栏固定后。
• 紧急回滚是明确的： --rollback-top-heavy 或 BRAINCTL_TOPHEAVY_ROLLBACK=1.
• 交叉编码器顶部沉重旋钮是明确的： --rerank-top-n N, --rerank-budget-ms MS.
• Canary目标支持同种异体和百分比抽样： --rollout-canary-agents / BRAINCTL_TOPHEAVY_CANARY_AGENTS, --rollout-canary-percent / BRAINCTL_TOPHEAVY_CANARY_PERCENT.
• 来源通过以下方式在搜索输出中发出 _debug （总是与 --debug；机会主义地相反）。检查： topheavy.rollout_mode, topheavy.rollout_reason, topheavy.enabled, .cross_encoder_applied, .cross_encoder_skipped, .cross_encoder_latency_ms, .cross_encoder_p95_ms, .cross_encoder_top_n，以及门钥匙，例如 .recency_skipped, .salience_skipped, .qvalue_skipped, .trust_skipped, .fetch_narrowed.

正面对决MemPalace（2026-04-18测量）

同一台机器（Intel Core Ultra 7 258V/33.9 GB RAM/Windows 10）， 相同的数据集，相同的评分。转载： python benchmarks/compare_memory_engines.py --label full_compare.

诚实警告（逐字取自工件包）： 这 矢量开/关标志 cmd_search 跑步并没有坚持下去 特定捆绑。后续运行 tests/bench/competitor_runs/ 记录 retrieval_mode + vector_enabled 自动（commit 40c1ed2），因此该差距被缩小以备将来再次运行。我们不会 引用上面的cmd_search数字作为干净的向量vs FTS语句 而无需在捕获标志的情况下重新运行该变体。

升级

cp $BRAIN_DB $BRAIN_DB.pre-upgrade
brainctl doctor      # diagnose migration state
brainctl migrate     # apply pending migrations

对于迁移跟踪器之前的数据库，请参阅README的升级部分（完整文档中安装块下方）中的完整恢复工作流程。

多代理

researcher = Brain(agent_id="researcher")
writer     = Brain(agent_id="writer")

researcher.remember("API uses OAuth 2.0 PKCE", category="integration")
writer.search("OAuth")   # finds researcher's memory — same brain.db, shared graph

每个操作都接受 agent_id 归因。代理商共享一个 brain.db知识图自动连接跨代理的见解。

文档

许可证

麻省理工学院