Cortex 本地记忆检索的可验证性解析

Cortex 本地记忆检索的可验证性解析 Cortex 本地记忆检索的可验证性解析【免费下载链接】LifeOS⛰️ LifeOS — The universal AI Harness designed to move you from Current to Ideal state in both life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOSLifeOS Cortex 是构建在既有文件型记忆系统之上的本地记忆检索 CLI本文拆解它的命令契约、fail-closed 隐私边界、BM25 检索基准测试与运营健康检查两条证据门控链路说明它如何在不引入向量索引、常驻进程与网络服务的前提下获得可验证的检索与受控写入。定位按需调用的 CLI不是常驻记忆运行时一句话说清Cortex v1 是基于 Bun 运行时的本地记忆检索 CLI入口是单个 Cortex.ts直接读取规范化的 Markdown/JSONL 记忆树输出可验证的检索结果与受控写入入口。它刻意不是不是 MCP 服务器、不是 HTTP 服务——没有守护进程不被调用就不启动不增加任何常驻进程不是第二个记忆运行时——不引入 Chroma、CMEM、SQLite FTS、向量索引或任何外部遥测不是同步或远程服务——无跨设备同步、无远程变更通道不是通用适配器守护进程——只有四个受识别身份claude/hermes/codex/subagent获得进程内适配器其余采集写者仍走原有路径。v1 的隐私边界覆盖reviewer 输入、reviewer 调试/错误产物、进入MemorySystem.add()及其受治理持久化路径的类型化条目以及 search/timeline/get/export/rebuild 的规范读。三条贯穿全系统的硬约束读这篇代码时最值钱的是四条设计原则。fail-closed。一切不确定——畸形私有标签、非法时间戳、realpath 逃逸、坏 JSONL——都按拒绝继续处理而不是尝试解析。原因记忆系统最坏的模式不是无结果而是静默返回了不该被看到的东西。证据门控。任何状态声明索引不存在检索是新鲜的重建是等价的都必须有可测量产物支撑策略标记、日志行、摘要值。缺失的证据不产生绿灯。文件即事实源派生物可丢弃。Markdown/JSONL 是规范形态索引、摘要、卡片都必须能由文件确定性重建。逐次授权、最小披露。写权限逐次授予而非身份级检索默认只返回卡片、从不返回正文。渐进披露是默认姿态不是优化项。架构总览一个 Markdown 文件如何变成一张卡片只读路径的数据流全部发生在进程内根解析 → 钉住规范根 → 语料遍历(计数/字节/记录数上限 符号链接检查) → 逐记录完整性校验 → private 净化 → 有效期窗口过滤 → BM25 排序(或 timeline 锚点) → 卡片投影(无正文) → 五字段信封 → stdout 退出码每层做一件事。根解析按四级优先级取运行时注入的memoryRoot→--memory-root→ 环境变量CORTEX_MEMORY_ROOT→ 默认~/.claude/LIFEOS/MEMORY。钉住根目录时对顶层做一次realpath解析把解析后的真实目录作为信任边界——这是默认LIFEOS/MEMORY符号链接指向私有用户数据树时仍能工作的机制。语料遍先在读取任何内容前检查文件数、单文件字节、总字节与记录数上限每条记录再过 ID 唯一性、时间戳合法性、控制字符检查与隐私净化。写路径只有一个出口remember/propose校验授权绑定与条目类型后委托给MemorySystem.add()——变更分层、目标钉住、提案审批、审计日志、快照与收缩守卫在那里继续保有权威地位Cortex 只是带闸门的入口。安全与完整性模型privatespanfail-closed 匹配不做宽松恢复显式私有 span 采用类标签语法public privatesecret/private public。CaptureEnvelope.ts 中stripPrivateContent的匹配语义大小写不敏感容忍无害空白与属性嵌套 span 整体移除用深度计数不是单条正则孤儿闭合标签视为控制标记——标签移除、两侧公开文本保留未闭合的开头标签 fail closed从该位置到字符串末尾全部抑制。更进一步任何归一化后形似 private 开头标签NUL/控制字符插入、全角 Unicode、丢失右尖括号但格式不良的构造一律视为不可信开头并抑制不尝试宽松的 HTML 恢复。净化是递归的覆盖内容之外承载持久化语义的元数据剥离后变空的必填字段直接拒绝。逐次授予不是身份级remember/propose双重绑定身份与授权分离——必须同时给出受识别的--adapter与--allow-write只命名身份不授予任何写权限命令与判别器绑定——remember只接受type为memory/idea/knowledgepropose只接受type:proposal不匹配在进入MemorySystem.add()之前就被拒绝。进程内适配器工厂 CortexAdapter.ts 在 API 层面落实逐次授予writePermission只接受键集合恰好为{allowWrite: true}的选项对象任何多余键或非布尔值都使授权判定为 null、整体拒绝。规范语料的信任边界语料级上限在读取任何内容之前检查≤ 10,000 个文件、单文件 ≤ 8 MiB、总量 ≤ 128 MiB、记录 ≤ 50,000 条。记录级问题一律以integrity_error失败退出码 4根之下任何符号链接或非常规模块文件、realpath 逃逸重复 ID坏 JSONL 或未知字段不可能时间戳updated早于created、valid_from valid_until、不存在的日历日期控制字符与孤立代理项。缺失 ID 的 Markdown 获得稳定路径派生 IDpath: 路径 SHA-256 前 16 位provenance 恒用相对规范根的路径——更换绝对根别名不改变记录摘要。两条读写路径及其契约只读路径卡片、分页与退出码status/search/timeline/get/export/rebuild六个只读命令都向 stdout 输出恰好一个 JSON 对象{schema:lifeos-cortex/v1,ok:false,command:search,data:null,error:{code:not_found,message:Expansion root not found: x}}不允许任何额外顶层字段。这一约定在库内自校验validateCortexEnvelope检查字段集合恰好为command/data/error/ok/schema每次成功或失败构造结果后都先过一遍校验器再返回发布版 Schemalifeos-cortex-v1.schema.json用oneOf约束成功/失败两种形态均additionalProperties:false。调用方必须同时看进程退出码与信封——能解析出 JSON 不等于成功退出码含义典型错误码0成功—1未预期的内部失败internal_error3显式 ID 或锚点未找到not_found4非法命令/选项/过滤器或规范完整性问题invalid_input、integrity_error5缺少写授权或既有治理拒绝变更write_refused、governance_refused检索是本地 BM25词元按[a-z0-9]切分idf 为log(1(n-df0.5)/(df0.5))tf 饱和系数 2.5长度归一化 b0.250.75·len/avgdl同分按 ID 字典序打破平局。--type/--source/--session是精确匹配--from/--to对created做闭区间过滤--recency必须是有限非负数、只按updated加权而不替代词法相关性。结果只含卡片、从不含正文卡片恰好是id/type/created/updated/provenance/score/est_tokens其中est_tokens 净化后正文字符数除以 4 向上取整。分页报精确过滤后的totalpage从 1 起默认每页 10 条、上限 100。timeline锚点可为记录 ID 或合法日期before/after默认 5、范围 0–100ID 锚点在中心记录仍落在所选过滤器内时包含中心记录本身。get/export接受最多 100 个显式 ID任一缺失、过期或尚未生效则整条命令以退出码 3 失败——all-or-nothing。export名字像写操作实际只是把选中记录序列化为lifeos-cortex-export/v1打印到 stdout不创建任何文件。bun LIFEOS/TOOLS/Cortex.ts search kafka compaction --type knowledge --page 1 bun LIFEOS/TOOLS/Cortex.ts get rec-001 rec-002变更路径仅有的两个动词bun LIFEOS/TOOLS/Cortex.ts remember {type:memory,id:m-1,title:t,content:...} \ --adapter claude --allow-write每条写命令恰好接受一个 JSON payload上限 262,144 字节通过双重绑定后委托MemorySystem.add()。治理拒绝返回退出码 5不存在部分成功。证据门控基准与健康检查各回答一个问题基准回答渐进披露省多少。CortexBenchmark.ts 导入生产代码——rankBM25、toCortexCard、activeCortexRecords与规范摘要函数——而不是携带一份基准专用排序器。每条带标签查询运行一次生产排序并把同一份结果在两种披露测量间共享bm25-baseline序列化完整 top-5 记录progressive序列化 top-5 卡片、只抓取第一条完整记录——排序质量被刻意保持完全相同被比较的是披露与注入成本不是两个检索算法。每条查询测 25 个样本报告含 Recall5、MRR、时序成对排序准确率、假阳性召回、注入 token、p95 延迟、盘上字节、后代进程数与峰值 RSS另记录语料分词次数与排序运行次数防止卡片优先的比较掩盖重复的检索工作。标签行必须携带lifeos-cortex-benchmark-label-provenance/v1溯源证明期望 ID 来自真实live-cortex-cli执行与人工语料核验持久化报告被锁定在MEMORY/BENCHMARKS/之下、使用版本化文件名且不覆盖已存在的报告。健康检查回答当前证据能否证明系统健康。核心原则是缺失的证据永远不产生绿灯格式错误的 JSONL 被暴露而不是静默跳回上一次成功非法或未来时间戳不能证明新鲜度新运行目录 10 分钟宽限后仍无终行即判超时最新 reviewer 证据优先于历史成功最新一次失败、超时、格式错误或 schema 不完整均为 CRITICAL阈值覆盖只接受有限正数值非法覆盖产生 critical finding而不是让比较失效。证据默认阈值越界结果最新 reviewer 成功新鲜度7 天陈旧 → WARN进行中 reviewer 运行终行宽限10 分钟超时 → CRITICAL检索证据新鲜度24 小时缺失/陈旧 → WARN待审提案积压status 恰为pending大于 10WARN可观测性日志字节数MEMORY/OBSERVABILITY/大于 256 MiBWARN最老可观测性日志年龄大于 30 天WARN已采用索引新鲜度大于 7 天WARN索引策略no-index-v1 是显式基线不是默认值派生索引可丢弃不能成为事实源。系统随发布提供一个肯定性标记 CORTEX_INDEX_POLICY.jsonpolicy:no-index-v1标记存在且无清单时BM25 直接读规范文件status报告indexes:[]rebuild不创建任何东西健康检查把这个明确状态报告为健康的no-index-v1——不为证明未采用索引而遍历或哈希整个语料。清单与标记双双缺失时状态是歧义的仅告警index-evidence-missing标记格式错误是 critical。合法的lifeos-cortex-index/v1清单规范 SHA-256、索引路径与哈希、indexed_at优先于 no-index 标记实际字节被逐一验证任何不匹配为 CRITICAL。采纳门槛写进基准vector_config当前为null采纳向量或混合索引的前提是一份带标签报告证明了相对渐进式 BM25 的检索质量提升且索引可规范重建、磁盘与进程边界单独文档化。仅仅降低 token 用量不构成采纳向量索引的证据。命令速查所有命令均接受--memory-root dir与可选--adapter claude|hermes|codex|subagent未知选项、重复选项、缺值一律被拒绝而非被忽略退出码 4。命令形态读/写要点statusstatus只读报规范根、记录数、mode:local-read-only、indexes:[]不接受位置参数searchsearch query [过滤项]只读BM25 精确过滤--expand ID --max-nodes N --max-tokens N沿related做有界 BFS默认 10 节点/2,000 token上限 100/50,000timelinetimeline --anchor ID_OR_DATE只读before/after默认 5、范围 0–100按created排序、同刻按 IDgetget ID [ID ...]只读最多 100 个 ID返回完整净化记录all-or-nothingexportexport ID [ID ...]只读规则同get序列化为lifeos-cortex-export/v1输出到 stdout不建文件rebuildrebuild --from-canonical只读对规范视图与重建视图分别算 SHA-256报告equivalent不创建索引rememberremember json --adapter A --allow-write写type限 memory/idea/knowledgepayload ≤ 262,144 字节proposepropose json --adapter A --allow-write写type限 proposal治理拒绝 → 退出码 5其余硬上限检索查询 ≤ 2,048 字符且 ≤ 64 个词元get/export≤ 100 个 ID类型化持久化对自由文本字段限 65,536 字符、元数据字符串 1,024 字符、related 链接 64 条。这些是拒绝上限不是目标值。本版本不声明无 MCP 服务器、无网络 API、无跨设备或云端同步无 CMEM、Chroma、SQLite FTS、嵌入或向量索引无外部遥测、无守护进程、无常驻 sidecar无对全部 hook/通道/采集表面的自动采纳无对原生 harness 转录的清洗——harness 文档所述的 30 天保留期超出其控制范围无从搜索结果自动注入完整记录——披露必须经过显式的get/export。适用前提本文以当前仓库LIFEOS/TOOLS/下的实现为准运行环境要求 Bun 运行时与已部署的规范根默认~/.claude/LIFEOS/MEMORY或CORTEX_MEMORY_ROOT指定的目录私有 MEMORY 树中的基准标签、检索日志与索引清单均为操作者本地资产不承诺未来版本行为。延伸阅读Cortex.ts — 八个命令、规范语料加载与 BM25 排序器的实现CaptureEnvelope.ts —privatespan 净化与有效期窗口的实现CortexHealth.ts — 证据收集与 fail-closed 健康评估CortexBenchmark.ts — 基准方法与lifeos-cortex-benchmark/v1报告 schema【免费下载链接】LifeOS⛰️ LifeOS — The universal AI Harness designed to move you from Current to Ideal state in both life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考