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 是跑在 LifeOS 文件型记忆系统之上的本地 Bun CLI它是一个可验证检索与受控写入的命令行工具不是 MCP 服务、不是常驻进程、也不是第二套记忆运行时。它被调用才启动不联网、不建向量索引。本文一次讲清这个本地记忆 CLI 的 8 个子命令怎么调、五字段信封与退出码怎么判读、private标签如何 fail-closed 拦住隐私内容以及两条证据链如何度量检索质量与运营健康。读完你可以直接跑命令、看懂结果并精确知道系统明确不提供哪些能力。 定位它是一张契约不是一个平台Cortex v1 的全部边界可以压缩成一句话有文件有契约没有进程没有网络没有第二套存储。维度Cortex v1 是什么它不是什么进程形态本地 CLI调用即启动守护进程、常驻 sidecar、MCP 或 HTTP 服务存储地位既有 Markdown / JSONL 文件型记忆之上的读取与写入入口Chroma、CMEM、SQLite FTS、向量索引或嵌入数据范围本机文件规范根下的记录跨设备/云同步、远程变更、外部遥测它解决的问题很朴素文件型记忆没有统一的验证过的读 受控的写入口Cortex 用一条 CLI 契约补上这个缺口——读默认写逐次授权。随系统发布的进程内适配器工厂位于 CortexAdapter.ts为claude、hermes、codex、subagent四种受识别身份各建一个被Object.freeze冻结的适配器status/search/timeline/get/export永远只读remember/propose虽挂在接口上但写权限逐次授予而非绑定身份——只有当次调用显式传入{allowWrite:true}时才追加--allow-write选项里混入任何其它键都会被权限判定判死并整体拒绝。 上手三步跑通 status再绕开那个符号链接坑调用格式全系统只有一种bun LIFEOS/TOOLS/Cortex.ts command [arguments] [options]根目录按四级优先级解析运行时注入的memoryRoot→--memory-root→ 环境变量CORTEX_MEMORY_ROOT→ 默认~/.claude/LIFEOS/MEMORY。把规范根想成户口登记地址门口贴多少块门牌别名都可以系统认的是登记地址本身。pinCanonicalRoot对根做一次realpath、确认是目录再把真实目录钉住当信任边界status会报告这条被钉住的路径——默认的LIFEOS/MEMORY符号链接借此指向私有数据仓库~/.config/LIFEOS/USER/MEMORY而无需手动解析。第一个坑就藏在这里顶层别名放行钉住根之下的一切符号链接拒收。类比贴封条——进门验完真实地址就封上之后任何再改地址的入口都不碰。实现上每次遍历都lstat判符号链接、校验realpath不越界下列情况一律integrity_error、退出码 4根下目录/文件符号链接、realpath 逃逸、重复记录 ID、格式错误 JSONL、不可能的时间戳updated早于created、valid_from valid_until、非法日历日期、非常规模块如 socket。此外还有语料级上限在读取内容前就检查文件 ≤ 10,000、单文件 ≤ 8 MiB、总量 ≤ 128 MiB、记录 ≤ 50,000超限同样integrity_error。这就是不确定就拒收的 fail-closed 气质。跑一条验证命令退出码 0bun LIFEOS/TOOLS/Cortex.ts statusstatus不接受位置参数返回规范根、记录数、mode:local-read-only与indexes:[]。注意它报告的是契约与语料形状不是运营健康——后者在证据一节单独讲。 判读退出码 信封两条证据都对才算成能解析出 JSON 不等于这次调用成功进程退出码和响应信封必须互相印证。每条命令向 stdout 恰好写一个 JSON 对象顶层字段有且仅有五个{schema:lifeos-cortex/v1,ok:true,command:status,data:{},error:null}失败时结构不变ok:false、data:nullerror装{code,message}多一个顶层字段都不允许。发布版 lifeos-cortex-v1.schema.json 用oneOf互斥约束 success 与 failure 两形态两者都声明additionalProperties:false。源码侧validateCortexEnvelope在每次ok()/fail()构造结果后先自检再返回——信封自校验是库内建的不指望调用方守规矩。退出码速查表退出码语义典型错误码0成功—1未预期的内部失败internal_error3显式 ID 或扩展根未找到not_found4非法命令、选项、payload、过滤器、边界值或规范完整性问题invalid_input、integrity_error5缺写授权或既有治理拒绝变更write_refused、governance_refused选项解析同样是严格表未知选项、重复选项、缺值、命令不适用该选项一律拒绝而不是忽略落到退出码 4 的invalid_input。 命令三组日常只读、一致性验证、唯一的写闸门8 个子命令按使用场景分成三组读比逐个平铺清晰得多。所有命令都接受--memory-root dir和可选的--adapter claude|hermes|codex|subagent。第一组日常只读status / search / timeline / get / export场景是日常查询取证。search基于本地 BM25一种按词频与逆文档频率给文档打分的经典检索算法词元按[a-z0-9]切分idf 取log(1 (n-df0.5)/(df0.5))tf 饱和系数 2.5长度归一化b 0.25 0.75·len/avgdl同分按 ID 字典序定先后。--type、--source、--session是精确匹配--from/--to对created做闭区间过滤--recency须为有限非负数按updated加权score recency·Date.parse(updated)/1e13但不替代词法相关性。bun LIFEOS/TOOLS/Cortex.ts search retrieval eval \ --type memory --from 2026-01-01 --page 1 --page-size 10 \ --expand some-id --max-nodes 10 --max-tokens 2000检索只回卡片从不回正文先给目录要正文再点名。卡片仅含id、type、created、updated、provenancesource、可空session、相对path、数值score、est_tokens净化正文长度除以 4 向上取整。列表响应给精确过滤后的total、从 1 计的page、page_size、items默认第 1 页每页 10 条页大小上限 100。可选的--expand从显式 ID 出发沿规范related做广度优先预算默认 10 节点/2,000 token上限 100/50,000不构建也不查询任何持久化图数据库。timeline用--anchor指定活跃记录 ID 或合法日期--before/--after默认各 5、可为 0、上限 100结果按created排序、同刻按 ID 排ID 锚点在仍落在过滤器内时包含中心记录。get/export只回显式选中且当前生效的 ID 的完整净化记录任一 ID 缺失、过期或未生效整条命令退出码 3all-or-nothing单次最多 100 个 ID。export名字像写操作实际只把记录序列化为lifeos-cortex-export/v1打印到 stdout不创建任何文件——是披露不是写。第二组一致性验证rebuild场景是证明记录视图可被确定性重建bun LIFEOS/TOOLS/Cortex.ts rebuild --from-canonicalflag 必填。它规范化记录对规范视图与重建视图各算 SHA-256在lifeos-cortex-canonical-rebuild/v1里报告equivalent、记录数与indexes:[]不创建任何索引。摘要相等只证明记录视图可确定性重建不证明源文件被逐字节重写。支撑这点的规范源规则值得记住Markdown 与 JSONL 是规范地位派生索引可丢弃、不能成为事实源默认语料是KNOWLEDGE/树排除下划线和点号前缀根级*_MEMORY.md一并纳入MEMORY/KNOWLEDGE/布局供隔离测试。缺失 Markdown ID 的记录获得稳定路径派生 IDpath: 路径 SHA-256 前 16 位provenance 用相对规范根的路径换别名不改摘要规范读会再次净化防止旧的已标记内容绕过当前边界。索引策略方面CORTEX_INDEX_POLICY.json 是lifeos-cortex-index-policy/v1、policy:no-index-v1的肯定性标记有标记无清单时BM25 直读规范文件、rebuild什么都不建、健康检查直接报健康的no-index-v1不为证明没建索引去遍历哈希整个语料标记与清单双缺则状态歧义仅告警index-evidence-missing标记格式错误才是 critical。第三组受控写入remember / propose场景只有一个你真的要把一条新记录落进受治理的持久化路径。bun LIFEOS/TOOLS/Cortex.ts remember typed-item-json \ --adapter claude --allow-write授权是双重绑定。其一身份与权限分离显式--adapter和--allow-write必须同时出现只报身份不送任何写权限其二命令与条目判别器绑定remember只收type:memory、idea、knowledgepropose只收type:proposal不匹配在调用MemorySystem.add()之前就被拒。每条命令恰好收一个 JSON payload≤ 262,144 字节并委托给MemorySystem.add()既有的变更分层、目标钉住、提案审批、审计日志、快照、源所有权与收缩守卫仍握有最终决定权。治理拒绝是退出码 5不存在部分成功。资源边界一览拒绝上限不是目标值检索查询2,048 字符且 64 个词法词元列表页大小100timelinebefore/after各 0–100图扩展100 节点、50,000 估算 tokenget/export显式 ID100CLI 写 payload262,144 字节条目自由文本字段65,536 字符元数据字符串1,024 字符提案目标路径4,096 字符热记忆集合48 条、每条 256 字符related链接64类型化持久化同时拒绝未知字段、非法枚举或字段类型、非有限/越界 confidence、控制字符、frontmatter/注释注入、含糊的 session 元数据、超尺寸数组以及隐私剥离后变空的必填文本。代表性 1,500 条记录的契约检索在测试中限定 1.5 秒内。 可信 标签与拿不准就拒绝防线Cortex 的整套信任设计可浓缩成一句大白话拿不准就拒绝。隐私 span 用类 HTML 标签书写public privatenever persist or export this/private public。匹配不区分大小写容忍无害空白与属性嵌套 span 整体移除按深度计数而非单条正则孤儿闭合标签当控制标记删掉、保留两侧公开文本未闭合的开头标签 fail closed从该位置起抑制整串剩余。更狠的是任何归一化后像 private 开头标签但格式不良的构造——NUL/控制字符插入、全角 Unicode、丢失的右尖括号——都按不可信开头处理并 fail closed而不是尝试宽松 HTML 恢复。这条边界的应用时机在持久化之前reviewer 推断前、reviewer 调试/错误序列化前、类型化条目路由、规范词法排序、图扩展、get、export与rebuild之前。类型化条目的净化是递归的覆盖 content 及承载持久化语义的元数据标题、名称、rationale、session provenance、entries、related slugs剥离后变空的必填字段直接拒绝。源中立的CaptureEnvelope见 CaptureEnvelope.ts携带source、channel、timestamps.captured_at可选source_at、可选valid_from/valid_until、可选session_id与content。真正的摄取助手是ingestCaptureEnvelope(input, consumer)先剥离私有内容再把净化后的 envelope 交给 consumer。fixture 覆盖 Claude、Hermes、Codex、子代理与一个消息通道——这只能证明能表示只有显式调用该助手的调用点受保护不构成所有既有来源已自动迁移的声明也不存在通用适配器守护进程。还要认清一条硬限制原生 harness 转录在其文档所述的 30 天保留期内可能仍留着private内容这超出 Cortex 控制。它不碰转录字节只剥离受控副本私有标签是持久化与处理边界不是对转录、终端回显、上游日志或标签到达前已发送内容的清洗承诺。有效期窗口同样 fail-closedvalid_from含边界、valid_until不含缺失即开放非法边界Date.parse得 NaN直接判无效。search、timeline、get、export默认排除查询时刻不生效的记录--from/--to是另一维度约束的是created不覆盖也不替代有效期判定。 证据两条链分别量检索质量与运营健康这套体系不回答我健康吗只回答证据在哪——缺失的证据永远拿不到绿灯。链一检索基准标签自写生产排序器标签文件LIFEOS/MEMORY/BENCHMARKS/cortex-retrieval-v1.jsonl存放在私有 MEMORY 树由操作者在自己的语料上、首次基准运行前自行编写不随系统发布。每行给 query、期望 ID、可选期望时序与可选已知假阳性 ID并必须携带lifeos-cortex-benchmark-label-provenance/v1溯源证明期望 ID 来自真实live-cortex-cli执行与人工语料核验。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.jsonCortexBenchmark.ts 的关键方法论它导入生产代码activeCortexRecords、rankBM25、toCortexCard与规范摘要函数不携带基准专用排序器。每条带标签查询跑 25 次每个查询/样本只做一次生产排序并把同一份排序结果在两种披露测量间共享bm25-baseline序列化完整 top-5 记录progressive序列化 top-5 卡片、仅抓取被选中的第一条完整记录。排序质量被刻意保持相同真正被比较的是披露与注入成本不是两个检索算法。每个配置报告Recall5、MRR、时序成对排序准确率、假阳性召回、注入 token、p95 延迟、延迟样本数、语料盘上字节数、实测磁盘增长、后代进程数、峰值 RSS、执行路径名外加语料分词次数与排序运行次数防止卡片优先的比较掩盖重复检索工作。报告 schema 为lifeos-cortex-benchmark/v1stdout 恒收报告持久化靠--output显式开启必须落在解析后的MEMORY/BENCHMARKS/下、文件名版本化cortex-benchmark-vN-*.json且不覆盖已有报告。报告记录语料/标签摘要、精确命令、时间戳、生产排序器与有效期路径、披露路径、top K 与样本数——它是对操作者自己语料的可复现时点测量不是普适性的延迟或质量声明。向量采纳门槛同步给出当前vector_config为null。采纳向量或混合索引的前提是一份带标签报告证明检索质量相对渐进式 BM25 有提升且索引可规范重建、保持在单独文档化的磁盘与进程边界内。只省 token 不构成证据。链二运营健康阈值表说了算status报契约形状运营健康来自另一工具bun LIFEOS/TOOLS/MemoryHealthCheck.ts --json。报告含overall、实测证据、生效阈值、findings以及按 ok/warn/critical 派生的健康退出码 0/1/2评估器见 CortexHealth.ts。证据默认阈值越界结果Reviewer 成功新鲜度7 天陈旧 WARN进行中 reviewer 终行宽限10 分钟超时 CRITICAL检索证据新鲜度24 小时缺失/陈旧 WARN待审提案积压大于 10WARN可观测性字节数大于 256 MiBWARN最老可观测性日志年龄大于 30 天WARN已采用索引新鲜度大于 7 天WARN判定规则几条最要紧最新reviewer 证据压过历史成功最新一次失败、解析失败、超时、schema 不完整或无效均为 CRITICAL新运行目录超过 10 分钟宽限仍无终行判超时格式错误的 JSONL 被暴露而非静默跳回上次成功非法或未来时间戳不能证明新鲜度提案证据只数状态恰为pending的行可观测性证据递归测量MEMORY/OBSERVABILITY/下全部.jsonl与.log报字节数、文件数与最老 mtime检索证据取最新一行有效的memory-retrievals.jsonl。对未来索引lifeos-cortex-index/v1清单必须给出规范 SHA-256、索引路径与 SHA-256、indexed_at清单非法、路径违规、索引字节缺失、规范不匹配或索引字节不匹配均为 CRITICAL。已验证的缺失清单是健康的no-index-v1词法基线不是把没测过的索引状态喊成健康的借口。阈值覆盖只接受有限正数值非法值产生 critical 的cortex-threshold-invalidfinding而不是让比较失效。运营覆盖变量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。每次运行给出overall判定与 critical/warn/ok 逐项计数记录的是当前证据不是永久健康保证。 边界明确不提供什么以及继续读哪里契约的另一半是负清单。已实现的这版升级不提供以下任何一项MCP 服务器或网络 API跨设备或云端同步CMEM / CMEM Cloud / Chroma / SQLite FTS / 嵌入 / 向量索引外部 Cortex 遥测Cortex 守护进程或常驻 sidecar所有 hook/通道/采集表面的自动采纳对原生 harness 转录的清洗从搜索结果自动注入完整记录适用前提以上均以当前仓库LIFEOS/TOOLS/实现为准运行需要 Bun 运行时与已部署的规范根~/.claude/LIFEOS/MEMORY或CORTEX_MEMORY_ROOT指定私有 MEMORY 树里的基准标签、检索日志、索引清单都是操作者本地资产不随开源仓库分发。延伸阅读仓库相对路径实现入口Cortex.ts进程内适配器工厂CortexAdapter.ts隐私 span 与有效期CaptureEnvelope.ts基准方法与报告 schemaCortexBenchmark.ts证据收集与 fail-closed 评估CortexHealth.ts响应 Schemalifeos-cortex-v1.schema.json索引策略标记CORTEX_INDEX_POLICY.json记忆架构与写者清单MemorySystem.md、CortexContract.md本地可观测性管线ObservabilitySystem.md【免费下载链接】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），仅供参考