使用说明

巩固记忆

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

存储发生的事情。巩固你所学到的知识。回想一下出处——当回购继续进行时，信任度会降低。

consolidation-memory 是为长期编码工作构建的本地第一代理内存：磁盘上的SQLite+FAISS+markdown主题，跨Python、MCP、REST和OpenAI风格工具的语义契约，以及显式的信任信号，而不是不透明的相似性搜索。

概览

	典型代理内存	整合内存
重用单元	嵌入式聊天片段	索赔 --具有出处的哈希稳定信念
原始输入	与检索相同的blob	剧集 --证据与信仰分开保存
固执	隐藏到错误	漂流挑战当锚定文件更改时
时间	仅限现在时	`as_of` 对先验信念状态的查询
分享	希望过滤器能正常工作	范围信封 +持久化策略/ACL原语
整合	始终调用LLM	快速路径对于结构化剧集；LLM仅适用于残渣

集中： 漂移感知调试内存——保留修复，用信任信号调用，重构后优雅降级。

心理模型

索赔是可重复使用的单元；这些事件是它们背后的原始证据。

  Episode                 Evidence from a session (chat, tool output, structured JSON)
      │
      ▼ consolidation
  Knowledge record        Typed fact · solution · preference · procedure · strategy
      │
      ▼ deterministic materialization
  Claim                   Reusable belief + sources + lifecycle events
      │
      ▼ human-readable view
  Topic                   Markdown file + DB rows you can open and audit

矛盾、挑战和到期仍然可见。该系统不会默默地覆盖不确定的信念。

flowchart TB
  subgraph ingest["Ingest"]
    E["Episodes"]
    A["File / path anchors"]
  end

  subgraph consolidate["Consolidate"]
    C["Cluster by embedding + scope"]
    FP["Fast path — no LLM"]
    LLM["LLM extraction — unstructured residue"]
    R["Knowledge records"]
    CL["Claims + edges + events"]
  end

  subgraph recall["Recall"]
    H["Hybrid search — FAISS + FTS + trust ranking"]
    T["Temporal filter — as_of"]
    S["Scope + policy filter"]
  end

  subgraph trust["Trust maintenance"]
    D["Git drift → challenge claims"]
    X["Contradiction log"]
    P["Precision + outcome signals"]
  end

  E --> C
  A --> E
  C --> FP
  C --> LLM
  FP --> R
  LLM --> R
  R --> CL
  CL --> H
  E --> H
  H --> T
  T --> S
  D --> CL
  X --> CL
  P --> CL

深潜：建筑学

能力

混合动力车召回

语义向量（FAISS）、关键字回退（FTS5，如果可用）以及跨剧集、主题、记录和声明的元数据感知排名。应对措施可能包括不确定性、矛盾背景、策略证据和范围归因。

采用确定性快速路径进行整合

相关事件通过嵌入相似性和范围隔离进行聚类。结构化剧集整合 没有LLM呼叫 当他们匹配时快速路径形状；其他一切都会退回到您配置的LLM后端（或者在以下情况下明显失败 llm.backend = "disabled").

漂移感知信任

detect_drift 地图 git 变化→ 文件锚点→ 受影响的索赔→ 可审计的 code_drift_detected 事件。陈旧的调试结论会失去准确性，而不是伪装成新的事实。

时间正确性

询问在某个时间点人们相信什么 as_of 关于召回和索赔搜索——在重构、回滚或事后分析后很有用。

范围共享

命名空间、项目、应用程序、代理和会话列保留在内存行上。策略和ACL表支持有意共享，而不会发生意外的跨项目泄漏。细节：架构——范围.

自适应调度

公用事业调度程序会权衡积压压力、召回失误、矛盾峰值、质疑索赔和失败的行动结果。 memory_status 暴露 utility_scheduler.run_decision.explanation, fast_path_hits, llm_fallbacks，以及 trust_profile 因此，自动化是可检查的，而不是神奇的。

表面奇偶性

通过的每条运输路线 MemoryClient 以及共享查询语义——没有“仅MCP”的行为漂移。

表面	入口
python `from consolidation_memory import MemoryClient`
MCP	`consolidation-memory serve` / `python -m consolidation_memory serve`
休息	`consolidation-memory serve-rest` （可选 `[rest]` 额外）
OpenAI工具	`schemas.openai_tools` + `dispatch_tool_call`

快速开始

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

在...期间 init，选择 disabled 对于LLM后端，除非您已经运行了LM Studio、Ollama或OpenAI。您仍然可以获得持久存储、混合召回、漂移检测和MCP服务。

任选附件

额外	启用
`[fastembed]`	本地嵌入（推荐默认）
`[openai]`	托管OpenAI嵌入/LLM
`[rest]`	FastAPI HTTP服务器
`[dashboard]`	文本TUI检查员
`[desktop]`	带有系统托盘图标的原生桌面UI(`consolidation-memory app`)
`[all,dev]`	全栈+测试/棉绒工具

后端矩阵：模型支撑 ·可布线：示例/

连接您的代理（MCP）

使用A 绝对Python路径 --比控制台脚本更可靠，尤其是在Windows上：

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

consolidation-memory init 打印完整的推荐环境（超时、预热、轻量级状态）。插入配置：光标 · 继续

简单配置文件 （3个 28 完整配置文件工具）：添加 "CONSOLIDATION_MEMORY_MCP_TOOL_PROFILE": "simple" 到 env --暴露 memory_recall, memory_remember，以及 memory_ask 只有。

MCP工具（代表）

工具	目的
`memory_store` / `memory_store_batch`	用类型、标签、范围来持久化剧集
`memory_recall`	对剧集、主题、记录、索赔的混合回忆
`memory_search`	纯文本搜索（非语义）
`memory_claim_search` / `memory_claim_browse`	以索赔为中心的检索
`memory_detect_drift`	基于Git的索赔挑战
`memory_consolidate`	按需运行整合
`memory_status`	健康、调度程序、信任文件、快速路径指标
`memory_timeline` / `memory_contradictions`	审计生命周期和冲突
`memory_export` / `memory_correct`	备份和人工更正
`memory_hygiene_scan` / `memory_hygiene_apply`	嘈杂的事件扫描和孤儿索赔清理
`memory_outcome_record` / `memory_outcome_browse`	将行动与结果联系起来

完整架构： src/consolidation_memory/schemas.py

Python API

from consolidation_memory import MemoryClient

with MemoryClient(auto_consolidate=False) as mem:
    mem.store(
        "Prefer PR summaries with concrete file paths, not high-level narration.",
        content_type="preference",
        tags=["workflow", "reviews"],
    )
    result = mem.recall("how should I format PR summaries?", n_results=5)
    print(result.episodes, result.claims)

在代码更改后挑战陈旧的信念：

report = mem.detect_drift()
print(report.challenged_claim_ids)

检查信任和调度程序状态：

status = mem.status()
print(status["trust_profile"])
print(status["utility_scheduler"]["run_decision"]["explanation"])

LLM可选合并

集 llm.backend = "disabled" 并将剧集存储在快速路径形状 --偏好、路径锚定解决方案、JSON事实/程序/策略。整合保持确定性；在启用LLM之前，非结构化残留物根本不会固结。

memory_status 报告提取混合(fast_path_hits, llm_fallbacks)，整合质量聚合，以及为什么调度程序接下来会运行。

这是给谁的

合适

在真实存储库上使用Cursor、Claude Code、Continue或自定义代理的开发人员
需要具有明确作用域边界的持久代理内存的团队
文件更改应降低对先前结论的信任的工作流程
希望在磁盘上可检查的工件，而不是托管的黑匣子的构建者

不合身

通用的“记住一切”消费者助手
替换git、问题跟踪器或规范产品文档
不透明矢量RAG，无来源故事

隐私和数据

没有内置遥测。
默认数据目录： platformdirs.user_data_dir("consolidation_memory")/projects/<project>/
仅对嵌入/LLM后端进行网络I/O 你配置。
REST绑定需要在非环回暴露之前进行身份验证。

文档

Doc	为什么要读它
建筑学	模块、持久性、数据流
快速通道事件	LLM自由固结形状
模型支撑	嵌入式和LLM后端
例子	游标、REST、LangGraph、插件
信任vs RAG	同一个bug两次——回忆+漂移挑战演示
插件开发	钩子表面和作者指南
LoCoMo基准	外部存储器比较线束

贡献者：见贡献.md.

社区

麻省理工学院· 行为准则