Context Lattice

Context Lattice 是一个独立的、来源可验证的记忆索引，用于 AI 编程代理的对话导出。将 Codex、Cursor、Kiro 或你自己的代理生成的 JSON 或 JSONL 指向它，即可检索到一个紧凑的证据包，而不是把整个历史重新灌入下一个上下文窗口。

原始记录保持不可变。分层摘要是有损的、可随时丢弃的导航索引。每一条结果都指回源文件、JSON 记录和 SHA-256 哈希。

快速开始

无需 API 密钥或外部数据库。支持 Python 3.11+。

cd /path/to/context-lattice
python3 -m pip install -e .

context-lattice init --root ~/exports/coding-sessions/
context-lattice ingest ~/exports/coding-sessions/
context-lattice query "Why did we change the retry policy?"
context-lattice query "What is the latest payment reference?" --json --debug
context-lattice inspect
context-lattice verify
context-lattice doctor

默认情况下，数据库创建在 ~/.context-lattice/memory.db，可通过 --db /path/to/memory.db 覆盖该路径。导入接受单个 .json、单个 .jsonl，或者同时包含两者的目录树。init 会基于同一个数据库和源根目录打印可直接粘贴的 MCP 配置，避免 CLI/服务器配置漂移。

Related MCP server: TimeReverse

作为 MCP 服务器安装

Context Lattice 通过本地 stdio MCP 暴露 memory_search、memory_get、memory_explain、memory_sync 和 memory_status。先配置数据库与显式的源白名单，再把任意支持 MCP 的客户端指向已安装的可执行文件：

{
  "mcpServers": {
    "context-lattice": {
      "command": "context-lattice-mcp",
      "env": {
        "CONTEXT_LATTICE_DB": "/absolute/path/to/memory.db",
        "CONTEXT_LATTICE_ALLOWED_ROOTS": "/absolute/path/to/agent/sessions"
      }
    }
  }
}

多个允许的根目录使用平台路径分隔符（macOS/Linux 上为 :，Windows 上为 ;）。memory_sync 是唯一会变更数据的 MCP 操作。搜索证据被明确标记为不可信，受 token 预算约束，并可溯源到源哈希。参见 docs/MCP.md。

输入适配器

--adapter auto 检查记录的信封结构，目前可识别：

• codex：包含 session_meta 和 response_item 记录的事件 JSONL；

• cursor：包含消息、气泡或回合的导出对话；

• kiro：带元数据头部的角色/内容 JSONL；

• claude：包含嵌套消息块的 Claude Code 项目 JSONL；

• canonical：稳定的 Context Lattice v1 格式；

• generic：常见的角色/内容、说话者/文本以及嵌套消息结构。

提供商格式可能会变化。Codex、Cursor 和 Kiro 适配器有意保持宽容并通过 fixture 测试，但 canonical schema 是保证的集成边界：schemas/conversation-v1.schema.json。最小完整示例见 examples/canonical.json。

{
  "schema": "context-lattice/v1",
  "conversation_id": "release-planning",
  "messages": [
    {
      "role": "user",
      "content": "The deployment region is ap-south-1.",
      "timestamp": "2026-08-20T10:00:00Z",
      "fact_key": "deployment-region",
      "entities": ["ap-south-1"]
    }
  ]
}

没有可识别对话内容的记录会被计为跳过。畸形或解析失败的记录会显示在导入结果中，并存储在导入审计日志中。重复导入同一文件是幂等的。

检索模型

• SQLite 中不可变、仅追加的原始事件；

• 原始 JSON，外加文件/记录来源与哈希；

• 用于精确标识符检索的 FTS5/BM25；

• 带离线特征哈希基线的倒排稀疏 postings 索引；

• 固定扇出的时间顺序摘要树；

• 跨词汇、语义和分层候选的倒数排名融合；

• 通过可选的 fact_key 值形成的更正链；

• 分歧触发的搜索扩展与基于置信度的弃权；

• 显式的证据 token 预算和可检查的检索轨迹。

索引器和检索器都是确定性的，且不会调用 LLM。内置的语义模型基于 feature hashing，因此可移植、可精确复现，但弱于学习型嵌入模型。外部 LLM 可以消费这些证据，但它不会被信任来维护记忆索引。嵌入边界可以在不改变证据契约的前提下替换。

按时间排序的分层结构是一种类似线段树的导航索引。它无法取代语义或词汇查找：它裁剪时间范围，而 FTS5 与稀疏 postings 负责定位术语，FTS5 与稀疏 postings 负责定位的词汇和概念。查询时的点积在 SQLite 内聚合，而树只栈有界根集合和 beam 沿着树下探。参见 docs/ARCHITECTURE.md。

测试与评估

python3 -m unittest discover -s tests -v
python3 -m context_lattice.cli eval --output benchmark-results.json
python3 -m context_lattice.cli golden-eval --output golden-results.json
python3 -m context_lattice.cli demo \
  "What is the current meeting room for team-3?"

确定性的 50 题评估会比较近期 token 窗口、滚动摘要、扁平向量搜索和分层混合检索。answer_accuracy 是证据充分性指标，而不是 LLM 评判分数。参见 benchmark-results.json 和 DESIGN.md。

人工审阅的 golden-v1 套件是 source recall、精确率、排序、过期事实、无依据结果、引用完整性和层次分支召回率的发布门禁。当阈值回退时，它会刻意让命令失败。参见 docs/GOLDEN_EVAL.md。

生产姿态

本地优先的核心具有逐对话原子索引更新、WAL 并发、跨进程维护锁、不可变事件、来源验证、受限的输入与检索、嵌套符号定位安全的 MCP 白名单、schema 兼容性检查、CI 和确定性发布门禁。context-lattice doctor 检查数据库完整性、索引新鲜度、FTS5、权限、SQLite、Python 和 MCP。Provider 格式仍然非官方，且可能变化；canonical v1 schema 才是稳定的集成边界。在将任何对象暴露到本地 stdio 之外之前，请先审阅 SECURITY.md。具体的发布检查列表与当前非目标见 docs/RELEASE_GATES.md。