Consolidation Memory

巩固记忆

 ](https://github.com/charliee1w/consolidation-memory/releases)    ](https://github.com/charliee1w/consolidation-memory/stargazers)

信任编码代理的校准工作记忆。

consolidation-memory 它围绕一个简单的立场构建：声明是可重用的单元，事件是原始证据，代码漂移是不信任陈旧内存的首要原因。该系统存储偶发事件，将其合并为结构化知识和声明，并在Python、MCP、REST和OpenAI风格的工具调用中提供相同的信任感知检索语义。

设计理念

• 将系统视为编码代理内存的信任层，而不是通用的blob存储。
• 比起原始的情节回忆，更喜欢有出处的可重复使用的声明。
• 通过时间有效性、矛盾历史和漂移挑战信号保持不确定性。
• 保持本地优先可检查性：SQLite、FAISS、markdown和日志在磁盘上都应该保持可理解性。
• 仅当作用域和策略确保重用安全时，才支持共享内存。

它是什么，不是什么

consolidation-memory 适用于：

• 需要持久、可检查工作记忆的编码代理
• 希望在不混合无关上下文的情况下实现可重用声明的团队
• 代码更改应自动降低对旧结论的信任的工作流

consolidation-memory 不是试图成为：

• 通用的“每个AI应用程序的内存”平台
• 源代码管理、问题跟踪器或主要文档的替代品
• 隐藏检索原因的黑盒矢量存储

5分钟内试试

pip install "consolidation-memory[fastembed]"
consolidation-memory init
consolidation-memory test
consolidation-memory serve

挑选 disabled 对于LLM步骤，除非您已经配置了LM Studio、Ollama或OpenAI。这为您提供了一个干净的首次运行路径，其中包含本地存储、回调和MCP服务。

这会立即给你什么：

• 使用SQLite+FAISS实现持久的本地存储
• 对运行时进行端到端验证的健康检查
• 编码代理可以通过stdio连接到的MCP服务器
• REST、OpenAI风格的工具和稍后使用的作用域共享内存的干净路径

如果你想要可运行的集成代码段而不是文档，请从开始 示例/.

为什么不同

建筑一瞥

flowchart LR
    A["Agent / App"] --> B["MCP / REST / Python / OpenAI tools"]
    B --> C["MemoryClient"]
    C --> D["Canonical query semantics"]
    C --> E["SQLite + knowledge markdown"]
    C --> F["FAISS vector store"]
    C --> G["Claim graph + anchors + drift signals"]
    G --> H["Changed files -> challenged claims"]
    D --> I["Episodes + topics + records + claims"]

更多细节生活在 docs/ARCHITECTURE.md.

memory_status / MemoryClient.status() 也暴露了a trust_profile 因此，呼叫者可以检查当前的索赔覆盖范围、来源覆盖范围、锚点覆盖范围、矛盾压力和漂移观察姿势。

示例

repo现在在根目录中保持可运行或接近可运行的示例 示例/ 目录：

• Python快速入门
• REST API客户端
• 光标MCP配置
• 继续配置
• LangGraph内存节点
• 插件挂钩示例

旧的原始配置片段仍然存在于 文档/示例/.

后端支持

consolidation-memory 支持完全本地和托管设置。

看 docs/MODEL_SUPPORT.md 有关完整矩阵、默认值和安装说明。

隐私和信任

• 没有内置遥测。
• 数据存储在本地 platformdirs.user_data_dir("consolidation_memory").
• 网络调用只会转到您配置的嵌入和LLM后端。
• 非环回绑定前需要REST身份验证。
• 回购附带了测试、烟雾检查、释放门、lint、类型检查和安全扫描。

安装

pip install "consolidation-memory[fastembed]"

常见附加：

• consolidation-memory[rest] 用于FastAPI端点
• consolidation-memory[fastembed,rest] 对于默认的本地REST设置
• consolidation-memory[dashboard] 用于文本仪表板
• consolidation-memory[openai] 用于OpenAI SDK后端
• consolidation-memory[all,dev] 促进当地全面发展

快速开始

consolidation-memory init
consolidation-memory test
consolidation-memory serve

consolidation-memory 没有子命令，默认为 serve.

CLI命令

serve            Start MCP server (default command)
serve --rest     Start REST API
init             Interactive setup
test             End-to-end health check
status           Runtime/system stats
consolidate      Trigger consolidation run
detect-drift     Challenge claims impacted by changed files
export           Export full snapshot JSON
import PATH      Import snapshot JSON
reindex          Rebuild vectors with current embedding backend
browse           Browse knowledge topics
setup-memory     Add reusable memory instructions to an agent file
dashboard        Launch Textual dashboard

MCP设置

{
  "mcpServers": {
    "consolidation_memory": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "consolidation_memory", "--project", "default", "serve"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "CONSOLIDATION_MEMORY_IDLE_TIMEOUT_SECONDS": "900"
      }
    }
  }
}

比起Python解释器，更喜欢精确的Python解释器 consolidation-memory 控制台脚本。它避免了PATH和env漂移，并且在MCP主机重新启动服务器时在Windows上更可靠。

stdio MCP服务器现在强制每个父进程和项目有一个活动服务器，建议的空闲超时为900秒，因此泄漏的主机会自行清理，而不是无限期累积。集 CONSOLIDATION_MEMORY_IDLE_TIMEOUT_SECONDS=0 只有当您明确需要永不退出服务器时。

MCP工具暴露于 server.py:

• memory_store
• memory_recall
• memory_store_batch
• memory_search
• memory_claim_browse
• memory_claim_search
• memory_detect_drift
• memory_status
• memory_forget
• memory_export
• memory_correct
• memory_compact
• memory_consolidate
• memory_consolidation_log
• memory_decay_report
• memory_protect
• memory_timeline
• memory_contradictions
• memory_browse
• memory_read_topic

Python示例

from consolidation_memory import MemoryClient

with MemoryClient(auto_consolidate=False) as mem:
    mem.store(
        "User prefers short PR summaries with concrete file paths.",
        content_type="preference",
        tags=["workflow", "reviews"],
    )

    result = mem.recall(
        "how should I format PR summaries?",
        n_results=5,
        include_knowledge=True,
    )

    print(len(result.episodes), len(result.knowledge), len(result.records), len(result.claims))

REST API

运行：

pip install "consolidation-memory[fastembed,rest]"
consolidation-memory serve --rest --host 127.0.0.1 --port 8080

对于非环回绑定（例如 --host 0.0.0.0)，先设置身份验证：

export CONSOLIDATION_MEMORY_REST_AUTH_TOKEN="change-me"
consolidation-memory serve --rest --host 0.0.0.0 --port 8080

$env:CONSOLIDATION_MEMORY_REST_AUTH_TOKEN = "change-me"
consolidation-memory serve --rest --host 0.0.0.0 --port 8080

启用身份验证后，发送 Authorization: Bearer 在所有端点上，除了 /health.

终点：

• GET /health
• POST /memory/store
• POST /memory/store/batch
• POST /memory/recall
• POST /memory/search
• POST /memory/claims/browse
• POST /memory/claims/search
• POST /memory/detect-drift
• GET /memory/status
• DELETE /memory/episodes/{episode_id}
• POST /memory/consolidate
• POST /memory/correct
• POST /memory/export
• POST /memory/compact
• GET /memory/browse
• GET /memory/topics/{filename}
• POST /memory/timeline
• POST /memory/contradictions
• POST /memory/protect
• POST /memory/consolidation-log
• GET /memory/decay-report

OpenAI兼容工具

用途：

• consolidation_memory.schemas.openai_tools
• consolidation_memory.schemas.dispatch_tool_call

这使工具定义和调度行为与MCP和REST使用的相同语义保持一致。

范围模型（兼容性+共享使用）

默认情况下，现有的单个项目用法仍然有效。

当提供范围包络时，记录将以显式的范围维度持久化：

• namespace_*
• project_*
• app_client_*
• agent_*
• session_*

这允许在不混合无关上下文的情况下进行选择性共享。

可选的 scope.policy 控制：

• read_visibility: private （默认）， project, namespace
• write_mode: allow （默认）， deny

还支持持久ACL实体(access_policies, policy_principals, policy_acl_entries). 当持久的ACL行与解析的作用域和主体匹配时，它们具有权威性 scope.policy. 冲突规则：写入 deny 覆盖 allow；读取可见性解析到最严格的级别。

存储布局

数据在 platformdirs.user_data_dir("consolidation_memory")/projects/ /.

memory.db
faiss_index.bin
faiss_id_map.json
faiss_tombstones.json
.faiss_reload
knowledge/
knowledge/versions/
consolidation_logs/
backups/

配置

配置文件发现：

1. CONSOLIDATION_MEMORY_CONFIG
2. 平台默认配置路径
3. 内置默认值

每个标量字段都可以用以下内容覆盖 CONSOLIDATION_MEMORY_.

示例：

CONSOLIDATION_MEMORY_PROJECT=work
CONSOLIDATION_MEMORY_EMBEDDING_BACKEND=fastembed
CONSOLIDATION_MEMORY_LLM_BACKEND=ollama
CONSOLIDATION_MEMORY_CONSOLIDATION_INTERVAL_HOURS=6

文档地图

• 建筑
• 建筑商基线
• 模型支撑
• 释放闸门
• 发布自动化
• 新颖性指标
• 新颖性评估指南
• 外部审查手册
• 推荐代理说明
• 通用内存策略文档

发展

git clone https://github.com/charliee1w/consolidation-memory
cd consolidation-memory
pip install -r requirements-dev.txt
python scripts/smoke_builder_base.py
pytest tests/ -q
pytest tests/ -q -W error::ResourceWarning
ruff check src/ tests/
mypy src/consolidation_memory/
bandit -q -r src scripts

社区

• 贡献者： 贡献者.md
• 问题：
• 讨论：
• 发布：

许可证等。

项目政策：

• 安全
• 贡献
• 行为准则

麻省理工学院