LifeOS Cortex 本地 CLI 的 8 个子命令：隐私边界、确定性重建与证据门控如何约束一次记忆检索

LifeOS Cortex 本地 CLI 的 8 个子命令隐私边界、确定性重建与证据门控如何约束一次记忆检索【免费下载链接】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 本地 CLILIFEOS/TOOLS/Cortex.ts是构建在文件型记忆系统之上的检索与受控写入工具核心能力是不依赖任何向量索引或网络服务对规范语料做可验证的本地 BM25 检索并把每一次写入放进治理层。三个问题先摆在前面它是什么——一个被调用才启动的本地 Bun CLI它不是什么——没有 MCP 服务、没有守护进程、没有第二套记忆运行时调用方拿到什么——每个子命令恰好一个五字段 JSON 信封加一个语义化退出码。设计立场先列清它不是再谈写权限契约文档 CortexContract.md 把边界写在第一节Cortex v1 不是 MCP 服务器、HTTP 服务、守护进程或云端产品不引入 Chroma、CMEM、外部遥测或向量索引不提供跨设备同步与远程变更不被调用就不启动不产生任何常驻进程。其余 hooks 与通道采集写者仍走原有路径直到被显式集成——系统里不存在通用适配器守护进程。这一负空间清单决定了后文所有设计没有网络面就没有网络攻击面没有常驻进程就没有索引漂移。写权限模型同样前置讲清。随系统发布的进程内适配器工厂 CortexAdapter.ts 只接受claude、hermes、codex、subagent四种身份Cortex.ts 第 13 行的ADAPTERS集合。工厂返回的对象被Object.freeze冻结第 43 行status/search/timeline/get/export天然只读remember/propose虽然挂在接口上但每次调用默认仍按只读路径执行——只有当次显式传入{allowWrite:true}才会追加--allow-write。权限判定函数writePermission第 20–32 行是逐次授予而非身份级授予选项对象一旦出现任何非allowWrite的键判定直接返回null整个调用被当作非法输入拒绝空对象或allowWrite缺失同样不授予写权限。命名一个适配器本身不构成写授权这是身份与授权分离的落地形式。调用契约命令形式、规范根解析与信封基本调用与根目录四级解析所有命令统一以如下形式调用bun LIFEOS/TOOLS/Cortex.ts command [arguments] [options]规范根按四级优先级解析可在 Cortex.ts 第 283 行逐字核对测试/运行时注入的memoryRoot--memory-root命令行选项环境变量CORTEX_MEMORY_ROOT默认值~/.claude/LIFEOS/MEMORY。顶层的规范别名symlink是被允许的pinCanonicalRoot第 136–141 行对根做一次realpath解析、确认目标是目录然后把真实目录钉住为信任边界status会报告这个钉住后的路径。默认的LIFEOS/MEMORY别名指向私有用户数据仓库~/.config/LIFEOS/USER/MEMORY时调用者无需手动解析。但钉住根之下的符号链接一律禁止机制与失败场景见数据与隐私边界章。严格选项表拒绝而非忽略每个命令有固定的允许选项集合第 207–214 行ALLOWED表parseArguments第 215–230 行对未知选项、重复选项、缺值选项、以及命令不适用的选项一律报错进入退出码 4 的invalid_input而不是静默忽略。--adapter必须命中四值之一否则同样拒绝。所有命令都接受--memory-root与可选的--adapter其余选项按命令裁剪例如search有--type/--source/--session/--from/--to/--page/--page-size/--recency/--expand而status与get/export只有两个公共选项。五字段信封与内建自校验每条命令向 stdout 写恰好一个 JSON 对象{schema:lifeos-cortex/v1,ok:true,command:status,data:{},error:null}失败时保持同样的五个顶层字段ok:false、data:nullerror携带{code,message}任何额外顶层字段被禁止。发布版 schema 为 lifeos-cortex-v1.schema.json成功与失败两种形态均声明additionalProperties:false并以oneOf互斥。源码层面同样是硬约束validateCortexEnvelope第 22–38 行校验字段集合恰好为command/data/error/ok/schema、schema常量、ok与error/data的一致性ok(...)与fail(...)第 47–48 行构造结果后都先经过checked()校验器再返回——信封自校验是库内建的不依赖调用方自觉。语义化退出码表退出码常量在第 9 行EXITmain()同时写 stdout 与process.exit(result.exitCode)。调用方必须双读退出码与信封能解析出 JSON 不代表成功。退出码含义典型错误码0成功—1未预期的内部失败internal_error3显式 ID 或扩展根未找到not_found4非法命令、选项、payload、过滤器、边界值或规范完整性问题invalid_input、integrity_error5缺少写授权或既有治理拒绝变更write_refused、governance_refused读侧契约六个只读子命令的统一格式status契约形状不是健康定位报告规范根、记录数、mode:local-read-only与indexes:[]。这是契约/语料形状不测量任何运营健康。命令bun LIFEOS/TOOLS/Cortex.ts status [--memory-root DIR] [--adapter ADAPTER]关键选项不接受位置参数带位置参数直接invalid_input第 278 行。边界完整走一遍规范语料枚举因此语料级上限与完整性检查在此生效。失败形态完整性问题报integrity_error退出 4。search本地 BM25只出卡片定位词法检索返回卡片而非正文。命令bun LIFEOS/TOOLS/Cortex.ts search query \ [--type TYPE] [--source SOURCE] [--session SESSION] \ [--from DATE] [--to DATE] [--page N] [--page-size N] \ [--recency WEIGHT] [--expand ID --max-nodes N --max-tokens N]关键选项--type/--source/--session精确匹配--from/--to对created做闭区间过滤第 255 行--recency必须有限非负按score recency·Date.parse(updated)/1e13加权不替代词法相关性第 291–292 行可选图扩展从显式--expandID 沿related做广度优先不构建也不查询持久化图数据库。边界查询 2,048 字符、64 个词法词元第 289 行扩展预算默认 10 节点、2,000 token上限 100 节点、50,000 token。失败形态查询超限或无词元 → 4扩展根不存在 → 3not_found。BM25 的全部参数化集中在rankBM25第 236–248 行一句话可概括参数取值词元切分小写化后按[a-z0-9]idflog(1 (n-df0.5)/(df0.5))tf 饱和系数 2.5长度归一化b 0.25 0.75·len/avgdl同分排序按 ID 字典序稳定卡片与分页规则检索只返回卡片从不返回正文渐进披露的核心。卡片字段恰好是id、type、created、updated、provenancesource、可空session、相对path、数值score、est_tokens不含content或任何摘录est_tokens 净化后正文长度除以 4 向上取整toCortexCard第 234 行。列表响应带精确过滤后的total、从 1 开始的page、page_size与items默认第 1 页、每页 10 条页大小上限 100第 257 行。timeline锚点驱动的时间窗口定位围绕一个锚点取前后邻域。命令bun LIFEOS/TOOLS/Cortex.ts timeline --anchor ID_OR_DATE [--before N] [--after N]关键选项锚点是活跃记录 ID 或合法日期--before/--after默认各 5、可为 0、上限 100第 233 行nonNegativeInt。边界结果按created排序、同刻按 ID 排序ID 锚点在中心记录仍落在所选过滤器内时包含中心记录本身日期锚点返回请求数量的邻接记录第 297 行。失败形态锚点既非记录也非合法日期 → 3not_found。get 与 export全有或全无的显式取回定位只返回显式选中活跃 ID 的完整净化记录。命令bun LIFEOS/TOOLS/Cortex.ts get ID [ID ...]export形式相同。关键选项无附加选项。边界单次最多 100 个 ID第 282 行。任一请求 ID 缺失、已过期或尚未生效整条命令以退出码 3 失败all-or-nothing第 299 行。失败形态not_found退出 3。export名字像写操作实际只是把选中记录序列化为lifeos-cortex-export/v1payload 打印到 stdout不创建任何文件——它是披露动作不是写动词。rebuild可重建性的只读证明定位证明记录视图可被确定性重建。命令bun LIFEOS/TOOLS/Cortex.ts rebuild --from-canonical关键选项--from-canonical显式必填缺失或带位置参数 → 4。边界规范化记录后分别对规范视图与重建视图计算 SHA-256第 286 行在lifeos-cortex-canonical-rebuild/v1payload 中报告equivalent、记录数与indexes:[]不创建任何索引。失败形态语料完整性问题按 4 处理。摘要相等证明的是Cortex 记录视图可被确定性重建不是源文件的逐字节重写后文证据门章会复用这条证明。写侧契约remember 与 propose 的双重绑定写侧只有两个命令且是全部契约命令中唯一会变更状态的bun LIFEOS/TOOLS/Cortex.ts remember typed-item-json --adapter claude|hermes|codex|subagent --allow-write bun LIFEOS/TOOLS/Cortex.ts propose typed-item-json --adapter claude|hermes|codex|subagent --allow-write授权模型是双重绑定校验发生在 Cortex.ts 第 266–277 行身份与授权分离必须同时给出受识别的显式--adapter与--allow-write只命名适配器不授予写权限缺任何一项即write_refused退出 5第 268 行。命令与条目判别器绑定remember只接受type:memory|idea|knowledgepropose只接受type:proposal不匹配在调用MemorySystem.add()之前就被拒绝第 272–273 行。每条命令恰好接受一个 JSON payload上限 262,144 字节超限是invalid_input而非write_refused校验通过后把一个已授权条目委托给MemorySystem.add()。既有的变更分层、目标钉住、提案审批、审计日志、快照、源所有权与收缩守卫保持权威地位治理层拒绝时是退出码 5 的governance_refused第 275 行不存在部分成功。数据与隐私边界根钉住、privatespan 与有效期根钉住之下的完整性规则checkedRealpathCortex.ts 第 53–59 行对每个遍历到的路径做lstat判符号链接、再校验realpath是否逃逸钉住的根。以下任一命中即integrity_error退出 4根之下的目录/文件符号链接、realpath 逃逸第 73–75、167 行重复的记录 ID第 199 行格式错误的 JSONL第 184 行不可能的时间戳updated早于created、valid_from valid_until、非法日历日期第 107–110 行非常规模块文件symlink、socket 等第 74 行。语料级上限是 fail-closed 的在读取任何内容之前检查CANONICAL_CORPUS_LIMITS第 12 行最多 10,000 个文件、单文件 8 MiB、总量 128 MiB、记录数 50,000 条超限同样报integrity_error。规范源与确定性基础Markdown 与 JSONL 保持规范地位派生索引可丢弃不能成为事实源。默认检索语料是既有KNOWLEDGE/树排除下划线与点号前缀路径规范根下存在根级*_MEMORY.md时一并纳入MEMORY/KNOWLEDGE/布局的 fixture 也受支持canonicalFiles按KNOWLEDGE→MEMORY/KNOWLEDGE→ 根本身三级回退第 142–159 行。缺失 Markdown ID 的记录获得稳定路径派生 IDpath: 相对路径 SHA-256 前 16 位第 132 行provenance 使用相对规范根的路径因此更换绝对根别名不会改变记录摘要。privatespan 的匹配语义显式私有 span 用类 HTML 标签表示public privatenever persist or export this/private public。完整语义在 CaptureEnvelope.ts 的stripPrivateContent第 17–56 行匹配不区分大小写容忍无害空白与属性第 37 行正则的gi标志与\s*结构嵌套 span 整体移除——用深度计数解析边界标签而不是单条正则第 40–54 行孤儿闭合标签作为控制标记移除两侧公开文本保留第 45–48 行未闭合开头标签 fail closed从该位置起抑制字符串剩余部分第 54 行任何归一化后形似 private 开头但格式不良的构造——NUL/控制字符插入、全角 Unicode、丢失右尖括号——都被视为不可信开头并 fail closed第 22–31 行的 NFKC 归一化检查不做宽松的 HTML 恢复。这条边界应用于 reviewer 推断之前、reviewer 调试/错误序列化之前、类型化条目路由、规范词法排序、图扩展、get、export与rebuild之前。规范读路径会再次净化sanitizeContentCortex.ts 第 123–125 行防止旧的已标记内容绕过当前边界。类型化条目的净化是递归的覆盖 content 及承载持久化语义的元数据标题、名称、rationale、session provenance、entries、related slugs剥离后变空的必填文本被拒绝。源中立的CaptureEnvelope携带source、channel、timestamps.captured_at加可选source_at、可选valid_from/valid_until、session_id与content。真正的摄取助手ingestCaptureEnvelope(input, consumer)第 63–65 行先剥离私有内容再把净化后的 envelope 交给 consumerfixture 覆盖 Claude、Hermes、Codex、子代理与一个消息通道。这些 fixture 证明的是助手与 envelope能够表示这些来源不声称所有既有来源或 hook 已被自动迁移——只有显式调用该助手的调用点受边界保护。有效期窗口与原生转录保留valid_from含边界、valid_until不含边界缺失的边界视为开放非法边界 fail closedisEnvelopeValidAtCaptureEnvelope.ts 第 74–81 行中Date.parse产生 NaN 即返回 falsesearch、timeline、get、export 默认排除查询时刻不生效的记录activeCortexRecordsCortex.ts 第 251 行--from/--to是另一维度它们只约束created不覆盖也不替代有效期判定。一项明确限制要照实说明原生 harness 转录可能在文档所述的 30 天保留期内保留private内容这超出 Cortex 的控制范围。Cortex 不触碰转录字节只在 reviewer 推断或持久化/导出之前剥离受控副本。私有标签是持久化与处理边界不是对 harness 转录、终端滚动回显、上游提供方日志或标签到达 Cortex 之前已发送内容的清洗承诺。证据门rebuild 证明、基准测试与向量采纳门槛确定性重建证明rebuild的 SHA-256 等价证明canonicalCorpusDigestCortex.ts 第 259 行按 ID 排序后序列化规范化记录再取摘要。它的用途是证明记录视图可被确定性重建——摘要相等不意味着源文件被逐字节重写也不产生任何索引工件。这条可重建性是后续索引治理的前提任何派生索引必须能被规范重建。基准测试的方法学版本化的带标签查询集是LIFEOS/MEMORY/BENCHMARKS/cortex-retrieval-v1.jsonl。标签文件存放在私有 MEMORY 树由操作者在自己的语料上、首次基准运行之前自行编写不随系统发布。每行 JSONL 提供 query、期望 ID、可选期望时序、可选已知假阳性 ID且必须携带lifeos-cortex-benchmark-label-provenance/v1溯源——期望 ID 来自真实live-cortex-cli执行并经manual-corpus-verification人工语料核验CortexBenchmark.ts 第 7–11、54、59 行。bun LIFEOS/TOOLS/CortexBenchmark.ts \ --labels LIFEOS/MEMORY/BENCHMARKS/cortex-retrieval-v1.jsonl \ --memory-root LIFEOS/MEMORY \ --output LIFEOS/MEMORY/BENCHMARKS/cortex-benchmark-v1-YYYYMMDD.json方法学上有两个关键设计。其一基准导入生产代码——activeCortexRecords、rankBM25、toCortexCard与规范摘要函数第 5 行 import不携带基准专用排序器。其二每条带标签查询运行 25 次第 22 行LATENCY_SAMPLES每个查询/样本只做一次生产排序同一份排序结果在两种披露测量间共享bm25-baseline序列化完整 top-5 记录progressive序列化 top-5 卡片、仅抓取被选中的第一条完整记录第 92–96、170 行。排序质量因此刻意保持完全相同被比较的是披露与注入成本而不是两个检索算法。每个配置报告Recall5、MRR、时序成对排序准确率、假阳性召回、注入 token、p95 延迟、延迟样本数、语料盘上字节数、实测磁盘增长、后代进程数、峰值 RSS、执行路径名第 138 行measure报告还带语料分词次数与排序运行次数防止卡片优先的比较掩盖重复的检索工作。报告 schema 为lifeos-cortex-benchmark/v1第 15 行stdout 始终收到报告持久化输出通过--output显式开启必须位于解析后的MEMORY/BENCHMARKS/之下、文件名匹配cortex-benchmark-vN-*.json第 199–204 行且以wx标志写入——不覆盖已存在的报告第 231 行。报告记录语料/标签摘要、精确命令、时间戳、生产排序器与有效期路径、披露路径、top K 与样本数是针对操作者自己语料与标签的可复现时点测量不是普适性延迟或质量声明。向量索引的采用门槛报告中vector_config当前为null第 15、171 行没有向量基准候选也没有向量索引。采纳向量或混合索引的前提是一份带标签的报告证明了相对渐进式 BM25 的检索质量提升且索引可规范重建、保持在单独文档化的磁盘与进程边界内。仅仅降低 token 用量不构成采纳向量索引的证据。索引策略标记系统发布的 CORTEX_INDEX_POLICY.json 是肯定性的lifeos-cortex-index-policy/v1标记内容policy:no-index-v1。标记存在且无索引清单时BM25 直接读规范文件status报告indexes:[]rebuild不创建任何东西健康检查将此状态报告为健康的no-index-v1——不为证明未采用索引而遍历或哈希整个语料。若清单与标记双双缺失索引状态歧义健康检查仅告警index-evidence-missingCortexHealth.ts 第 98 行标记格式错误是 critical第 179–183 行判定invalid。若存在合法的已采用索引清单它优先于 no-index 标记其规范 SHA-256、索引路径与 SHA-256、indexed_at被逐字节验证第 186–196 行。运营健康status 与健康检查是两回事Cortex.ts status报告契约可用性与语料形状运营健康来自另一个工具bun LIFEOS/TOOLS/MemoryHealthCheck.ts --json机器可读报告包含overall、实测证据、生效阈值、findings以及按 ok/warn/critical 派生的退出码 0/1/2MemoryHealthCheck.ts 第 372–380、404–406 行。核心原则缺失的证据永远不产生绿灯——评估器assessCortexEvidenceCortexHealth.ts 第 82–101 行对每类证据缺失给出 warn 或 critical而不是放行。证据默认阈值越界结果Reviewer 成功新鲜度7 天陈旧时 WARN进行中 reviewer 终行宽限10 分钟CRITICAL 超时检索证据新鲜度24 小时缺失/陈旧时 WARN待审提案积压大于 10WARN可观测性字节数大于 256 MiBWARN最老可观测性日志年龄大于 30 天WARN已采用索引新鲜度大于 7 天WARN阈值常量在 CortexHealth.ts 第 14–22 行DEFAULT_CORTEX_THRESHOLDS可直接核对。判定规则与源码一一对应最新 reviewer 证据优先于历史成功最新一次运行失败、解析失败、超时、格式错误、schema 不完整或无效均为 CRITICAL第 87 行新运行目录在 10 分钟宽限后仍无终行判超时第 125–128 行格式错误的 JSONL 被暴露parse-failed而不是静默跳回上一次成功第 119 行非法或未来时间戳不能证明新鲜度第 90、95 行reviewer-future/retrieval-future提案证据只统计状态恰为pending的行格式错误的提案 JSONL 告警第 211 行可观测性证据递归测量MEMORY/OBSERVABILITY/下全部.jsonl与.log报告字节数、文件数与最老 mtime第 141–155 行检索证据取最新一行有效的memory-retrievals.jsonl。阈值覆盖只接受有限正数值非法值产生 critical 的cortex-threshold-invalidfinding而不是让比较失效MemoryHealthCheck.ts 第 349–353 行。运营覆盖变量CORTEX_RETRIEVAL_STALE_MS、CORTEX_PROPOSAL_BACKLOG、CORTEX_OBSERVABILITY_MAX_BYTES、CORTEX_OBSERVABILITY_MAX_AGE_MS测试/自动化路径变量CORTEX_HEALTH_ROOT、CORTEX_HEALTH_NOW、CORTEX_INDEX_MANIFEST、CORTEX_HEALTH_NO_WRITE、CORTEX_HEALTH_REPORT_PATH第 354–361、384、395 行。每次运行的输出记录的是当前证据不是永久健康保证已验证的缺失清单是健康的no-index-v1词法基线不是把未测量的索引状态称为健康的借口。硬上限速查以下边界合并自 Cortex.ts 第 10–12 行LIMITS/CANONICAL_CORPUS_LIMITS、契约文档资源边界表以及 MemorySystem.ts 第 692–693、789 行的类型化持久化上限表面边界检索查询2,048 字符且 64 个词法词元列表页大小100Timelinebefore/after各自 0–100图扩展100 节点、50,000 估算 token显式get/exportID 数100CLI 写 payload262,144 字节类型化条目自由文本字段65,536 字符类型化元数据字符串1,024 字符提案目标路径4,096 字符热记忆集合48 条、每条 256 字符Related 链接数64规范语料10,000 文件 / 单文件 8 MiB / 总量 128 MiB / 50,000 记录类型化持久化同时拒绝未知字段、非法枚举或字段类型、非有限/越界 confidence、控制字符、frontmatter/注释注入、含糊的 session 元数据、超尺寸数组以及隐私剥离后变空的必填文本。这些数字是拒绝上限而非目标值代表性 1,500 条记录的契约检索在测试中限定 1.5 秒内重复测量由独立的基准测试承担。延伸阅读与适用前提延伸阅读MemorySystem.md — 记忆架构、策展分层、写者与目录清单CortexContract.md — 本契约的权威文档CaptureEnvelope.ts — private span 与有效期的实现CortexAdapter.ts — 进程内读/写适配器工厂CortexBenchmark.ts — 基准方法与lifeos-cortex-benchmark/v1报告 schemaCortexHealth.ts 与 MemoryHealthCheck.ts — 证据收集与 fail-closed 评估。适用前提以上描述以当前仓库LIFEOS/TOOLS/实现为准运行环境要求 Bun 运行时与已部署的~/.claude/LIFEOS/MEMORY或CORTEX_MEMORY_ROOT指定的规范根私有 MEMORY 树中的基准标签、检索日志与索引清单均为操作者本地资产不随开源仓库分发。未列入契约的能力MCP/网络 API、跨设备同步、CMEM/Chroma/SQLite FTS/嵌入/向量索引、外部遥测、常驻 sidecar、自动全表面采纳、转录清洗、搜索自动注入完整记录均不存在也不应被假设存在。【免费下载链接】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），仅供参考