tessera

TESSERA (Temporal Evolving State Synthesis with Explicit Relations and Atomic Memories) 是一个面向 AI 智能体的文本优先内存与证据层。该项目以 tessera-agent-memory 名称发布，Python 导入名和 CLI 均为 tessera，要求 Python 3.9+，采用 MIT 许可，当前版本为 0.0.1。 该项目将自身定位为内存基础设施而非最终的推理智能体。Markdown 和文本源保持权威性；索引、图谱、缓存和证据记录均为派生且可重建的。检索返回的是结构化证据而非生成的答案。README 指出，相关性不被视为真理、置信度或权威性，索引过程中不会静默重写源文件，且基础检索路径不需要生成式 LLM。 接口与使用 - CLI：提供 tessera init, write, index, query 以及 config show/list/doctor/unregister。非交互式 init 需要明确的 --sources 策略，对现有配置的重大更改必须先通过 --dry-run 检查，然后通过 --update-existing 允许。 - Python API：通过 TesseraEngine(storage_dir=...).build_index() 和 retrieve_context(query, top_n=...) 调用，返回字段包括 id, score（含 score_explain）、relevant_evidence、完整内存正文、源路径、稳定的源文档标识、源版本哈希、证据跨度（span）及相关内存 ID。 - MCP：可选的 tessera[mcp] 扩展增加了 MCP 传输支持（SDK v1.30+, Python 3.10+, 在 3.12 上通过认证），使用 tessera-mcp --project /absolute/project；可选的 tessera[llm] 扩展则增加了一个 HTTP LLM 桥接。 内存模型与存储 - 保留三个语义抽屉：事实 (facts)、偏好 (preferences) 和洞察 (insights)。 - 身份与文件位置及内容版本分离，因此移动文档不会自动创建新的内存或源身份。 - 配置采用人类可读的 schema v2：store.path 是生成的内存目的地，sources.roots 是明确的读取/索引允许列表，index.path 是项目内部可丢弃的派生状态。用户全局注册表可以记录命名存储，而无需复制或合并其内存。 - 存储解析顺序为：显式路径 $\rightarrow$ TESSERA_STORAGE_DIR $\rightarrow$ 已弃用的 LAO_MEM_DIR $\rightarrow$ 最近的项目配置 $\rightarrow$ 命名的全局条目；若均未选中，CLI 操作将返回可操作的错误。 - Markdown 是唯一的规范可写格式；不支持的格式和任意 JSON 摄入在进入存储、注册表、图谱、索引或 Evidence Ledger 变更前将被拒绝。 - 写入遵循确定性合约：路径验证 $\rightarrow$ 检测 $\rightarrow$ 可选转换 $\rightarrow$ 准入 $\rightarrow$ 持久化。安全内容原样接受；空输入和直接的已知恶意指令被拒绝；引用示例和仅含可疑标签的输入将进入审核，不产生持久化副作用。 - 可选的 .tessera-ignore 支持文档化的部分忽略语法（注释, *, ?, **, 目录后缀, 有序的 ! 重新包含）；强制排除项（如 .git、派生索引和凭据产物）无法被重新包含。 评估与状态 一个紧凑且非敏感的账本对确定性的 LongMemEval V1 dev-50 检索配置文件进行版本管理，记录聚合检索指标、冻结输入、配置、提交来源、成本和哈希，而不提交数据集或地面真值映射。每个 PR 需声明基准适用性；每个 PR 运行离线报告检查，且冻结的 50 个查询配置文件在 PR 基础 SHA 处设有门禁。README 注明这些分数衡量的是证据检索，而非最终答案的正确性。 TESSERA 被描述为一个演进中的基础。目前已实现的功能包括：规范元数据与文档分类、稳定的内存与源身份、可解释的本地检索、查询感知的相关证据、Evidence Ledger 与溯源、关系解析/导航、Python/CLI/MCP 接口以及带有健全性评估的确定性 CI。仍在测试的项目包括：增量且幂等的索引、更广泛的文本摄入与分段、LongMemEval 基准线、查询感知的图扩展、时间状态、冲突证据的仲裁以及自适应检索。文档涵盖了架构、概念、查询示例、检索输出合约、路线图、研究参考和变更策略；该仓库目前由 Luigi Ferronatto 维护。