Ember3 Memory

Ember3

AI编码代理的持久内存。语义知识+可搜索的档案存储在一个SQLite数据库中，充当MCP服务器。

Ember3为您的AI助手提供跨会话持久的内存，在会话之间进行整合，并随着时间的推移变得更加智能。它适用于Claude Code、OpenAI Codex、Gemini CLI或任何讲MCP的东西。

是什么让它与众不同

• 两层架构：用于持久知识的语义记忆（矢量搜索）+用于会话日志、调试记录和原始历史的归档层（全文搜索）。一个数据库，两种了解方式。
• HESTIA评分：检索按余弦相似性、阴影衰减抑制、区域活力、效用反馈和项目相关性排名，而不仅仅是矢量距离。陈旧的知识会自动降低优先级；积极使用的知识得到了提升。
• 做梦周期：在会话之间进行的记忆巩固——提取事实，检测“无意识”主题（讨论过但从未存储过），弥合孤立的知识，发现矛盾，产生问题。你的特工醒来时比睡觉时更连贯。
• 桥梁余烬技术：你怎么样 *词* 内存决定其图形连接性。一个简单的事实创建了一个岛节点；关系语句在向量空间中创建边。这是实验证实的，而不是理论上的。
• 跨平台：macOS、Linux、Windows。ONNX嵌入（不是PyTorch）、SQLite（不是Postgres）。
• 代理不可知：MCP服务器可与任何客户端配合使用。Claude Code获得了完整的体验（钩子、梦境循环）；其他代理获得核心内存工具。

快速启动

git clone https://github.com/anomalous3/ember3-memory.git
cd ember3-memory
./setup.sh          # creates venv, installs deps, downloads embedding model

添加到您的Claude代码配置中(~/.claude.json):

{
  "mcpServers": {
    "ember": {
      "type": "stdio",
      "command": "/path/to/ember3-memory/.venv/bin/python3",
      "args": ["-m", "ember"],
      "env": {
        "EMBER_AGENT": "claude"
      }
    }
  }
}

对于Codex或Gemini，为您的工具添加等效的MCP配置。服务器使用标准MCP stdio。

第一次运行时，Ember会自动下载ONNX嵌入模型（约23MB）并创建数据库。核心内存系统不需要API密钥或外部服务。（梦周期的人工智能驱动阶段 claude -p，它使用您现有的Claude Code身份验证。)

重新启动您的代理。呼叫 ember_auto("hello") 以验证其是否正常工作。

建筑

                    ┌──────────────────────────────┐
                    │         MCP Server            │
                    │        (29 tools)             │
                    └──────┬───────────┬────────────┘
                           │           │
              ┌────────────▼──┐   ┌────▼────────────┐
              │   Semantic    │   │    Archive       │
              │   Layer       │   │    Layer         │
              │               │   │                  │
              │ Vector KNN    │   │ FTS5 + regex     │
              │ HESTIA scored │   │ BM25 ranked      │
              │ Shadow decay  │   │ Chunk types      │
              └───────┬───────┘   └────┬─────────────┘
                      │                │
                      └──────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │     SQLite       │
                    │  sqlite-vec +    │
                    │  FTS5 + WAL      │
                    │  (one .db file)  │
                    └──────────────────┘

语义层 存储持久的知识——事实、决策、偏好、学习。每个成员都通过全MiniLM-L6-v2（ONNX，384维）嵌入，并用sqlite-vec索引以进行KNN搜索。知识图（边表）跟踪关系。HESTIA评分对原始向量相似性之外的结果进行重新排序。

归档层 存储其他所有内容——会话记录、调试记录、实验日志、梦想周期输出。使用FTS5进行BM25关键字搜索。还支持大型文档的正则表达式搜索和行范围导航。

deep_recall 同时搜索两层。

一个数据库。备份是 cp.Sync是文件副本。内省是 sqlite3.

MCP工具（29）

磁芯存储器

档案

知识图谱

做梦周期

健康和维护

会议和管理

HESTIA评分

检索不仅仅是“最近向量”。HESTIA计算：

score = cos_sim * (1 - shadow_load)^gamma * vitality_factor * utility_factor

• cos_sim：查询和内存之间的语义相似性（0-1）
• shadow_load这个记忆被更新的、类似的知识取代了多少。通过Shadow Decay框架计算——当新记忆与旧记忆高度相似时，它们会“掩盖”旧记忆，在不删除旧信息的情况下将其向下推。
• 活力因子：记忆区域有多活跃。你正在积极工作的领域的知识会得到提升；休眠区域被降低优先级。
• 效用因子：这段记忆是否真的 *使用过的* 当之前浮出水面时。记忆浮出水面，但从未读过腐烂；阅读和行动的记忆得到了增强。通过召回日志进行跟踪。

附加修改：

• 项目范围界定：标记为活动项目的记忆得到提升；无关的项目记忆会受到惩罚。
• 基于重要性的半衰期事实衰减缓慢（365天），上下文衰减快（7天），决策（30天），偏好（60天），学习（90天）。

梦境循环

梦的循环就像克劳德密码一样 SessionEnd 钩子，分叉到一个独立的后台进程中，这样它就不会阻止关机。总运行时间通常为3-8分钟。

阶段0、2和3使用Claude CLI(claude -p)具有受限的工具访问权限——梦想中的AI只能使用特定的Ember工具，而不能任意访问系统。每个阶段都有一个超时（60-300s），因此卡住的阶段不会阻止其余的阶段。

梦想周期是可选的，并且是特定于克劳德代码的。核心内存系统在没有它的情况下工作。

关键概念

桥梁余烬技术

你如何书写记忆决定了它的图形连接性。语义嵌入编码关系，而不仅仅是主题。存储连接短语实际上会在向量空间中创建边：

Isolated:   "User has RTX 3090"                    -> 0 graph connections (island)
Connected:  "RTX 3090 enables local model training  -> 18 connections via 2 hops
             for discriminator models, connecting
             the multi-agent architecture to
             on-device compute"

模板： [fact] -- [why it matters] in the context of [what it connects to], which means [implication for future work]

储存前有三扇门

1. 这耐用吗？ 下周会是真的吗？如果不→ 存档，而不是余烬。
2. 是否存在类似的余烬？ 先检查一下。更新，不要重复。
3. 这是一种关系吗？ 将其与相关内容联系起来。

积极储存，明智搜索

存储成本低廉；失去上下文是代价高昂的。储存一切。但要有选择性地将内容加载回上下文中——只记得当前任务需要什么。

多代理支持

多个代理可以共享一个Ember数据库。每个代理通过 EMBER_AGENT env-var，在每次操作中都会记录其来源。

梦循环和会话钩子是Claude Code的特性（它们使用Claude Code中的钩子系统）。29个MCP工具适用于任何客户端。

高级模式

这 examples/ 目录涵盖了从Ember中获得更多好处的技术：

• CLAUDE.md.示例 --初学者配置，用于指导您的代理有效使用Ember。会话礼仪、三关、桥牌技巧、注意铃练习。
• subgent-recipes.md --使用余烬加载作为上下文塑造：存在优先路由（何时直接体验与委托体验）、模型级联、不同认知模式的加载配方、外部化协议。包括关于为什么过度授权会降低判断质量的调查结果。
• 元成员.md --自我建议知识：将指令存储为灰烬，与他们建议的知识一起出现。该图通过LLM自我建议。轻量级递归自修改，无需更改服务器。

配置

环境变量

数据目录布局

~/.ember/                          # or %APPDATA%/ember on Windows
├── ember3.db                      # The single database file
├── models/
│   └── all-MiniLM-L6-v2/
│       ├── model.onnx             # Embedding model (~23MB, auto-downloaded)
│       └── tokenizer.json
├── dream-log.md                   # Most recent dream cycle output
└── archive/
    └── exports/                   # Raw JSONL session backups

可调常数

编辑 ember/config.py 调整评分行为：

钩子（克劳德代码，Unix/macOS）

Ember附带了用于Claude Code生命周期事件的钩子。钩子需要类Unix系统（macOS、Linux）——核心MCP服务器是跨平台的，但钩子使用 os.fork()、bash，以及可选的tmux/jq：

示例钩子配置 ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "type": "command",
        "command": "/path/to/ember3/.venv/bin/python3 /path/to/ember3/ember/hooks/session_end_export.py"
      },
      {
        "type": "command",
        "command": "/path/to/ember3/ember/hooks/session_end_dream.sh"
      }
    ],
    "PreCompact": [
      {
        "type": "command",
        "command": "/path/to/ember3/.venv/bin/python3 /path/to/ember3/ember/hooks/pre_compact_export.py"
      }
    ]
  }
}

维护

maintain.py 运行内存管理（梦周期的非AI阶段）：

python maintain.py                    # Report only (default)
python maintain.py --all              # Run all maintenance tasks
python maintain.py --utility          # Compute utility scores from recall logs
python maintain.py --vitality         # Update per-cell vitality
python maintain.py --prune-stale      # Delete embers marked as stale
python maintain.py --archive-decayed  # Archive heavily-shadowed embers
python maintain.py --unconscious      # Detect topics discussed but never stored
python maintain.py --report           # Print full maintenance report

依赖项

• Python>=3.10
• 主控程序 >=1.0-MCP服务器框架
• ONNX运行时 >=1.17.0--嵌入推理
• 分词器 >=0.15.0--快速标记化
• sqlite-vc ~=0.1.6——SQLite中的矢量搜索
• 数值Python >=1.24.0--矢量运算
• aiosqlite >=0.20.0--异步SQLite
• 拥抱面中心 >=0.20.0——模型下载

可选： 特富兹 用于数据挖掘中的模糊字符串匹配。

世系

Ember3起源于https://github.com/Sysbaia/ember-mcp-memoire-claude.原版通过FAISS索引提供了基本的语义记忆。从那时起，发展出现了实质性的分化：

• 余烬1.x （fork）——每个内存的JSON文件、FAISS索引、numpy向量存储、用于存档搜索的单独BM25库、基于YAML的存档块。功能强大但脆弱——状态分散在十几种文件格式中。
• 余烬2.x --介绍了HESTIA评分、阴影衰减框架、梦循环、Voronoi单元拓扑、效用反馈、桥接技术和归档层。定义系统的想法。
• Ember 3.0 --彻底重写存储。一个SQLite数据库。sqlite-vec取代了FAISS。FTS5取代了bm25。同样的29个MCP工具，同样的梦想周期。备份是一个文件副本，自省是 sqlite3.

不同版本之间思想的连续性比代码的连续性更重要。血统，而非转世。

许可证

麻省理工学院