file-memory

面向 Linux 的智能体记忆提取与精准遗忘机制

file-memory 是一个为 Codex、Claude Code 和 Qwen Code 提供持久记忆的本地插件。它在会话生命周期的各个节点自动采集对话，把其中值得留存的内容沉淀成三层记忆，并在下一次会话中重新注入，让智能体记住你的工作习惯和项目上下文，而不需要每次重新解释一遍。

决赛交付与演示

本仓库 master 分支包含源码、可部署演示入口、测试与验证材料及决赛文档。

应用场景

适用于长期软件项目中的验证流程和故障经验复用、同一项目多 Agent 切换、个人工作习惯持续沉淀，以及需要用户隔离和读写审计的 Linux 桌面开发环境。

与常见的应用层记忆方案不同，file-memory 把隐私与安全边界下沉到操作系统：所有原始对话在落盘之前必须经过系统级守护进程脱敏，写入者身份由 BPF LSM 在内核中强制校验，每一次记忆读、写、遗忘都同时进入 journald 与 Linux auditd。遗忘不是「标记删除」，而是一个 11 阶段、可恢复、可审计的事务。

file-memory 总体粗览

核心能力

能力	说明
偏好记忆	LLM 分类器从会话窗口提取输出语言、呈现格式、工作流、代码风格、沟通风格五个维度的偏好；候选池机制过滤一次性要求，跨项目重复出现的偏好晋升为长期记忆
知识记忆	把工作流程、解决方案、故障案例、工具用法沉淀成结构化 Markdown，二阶段决策处理与旧知识的冲突（create / update / noop）
混合检索	SQLite FTS5（字段权重 BM25）与 openKylin 端侧向量库并行检索，加权 RRF 融合返回 Top-5
写前脱敏	Rust `privacyd` 识别身份证、手机号、邮箱、姓名（spaCy 双语 NER）、API Key、Token、密码、私钥及自定义敏感词，命中内容在落盘前替换
内核强制	BPF LSM 挂载 8 个 hook，只允许已登记的 `privacyd` 进程写入受保护的短期记忆文件，其他进程返回 `EPERM`
精准遗忘	自然语言经 skill 转为严格 JSON 意图，preview / confirm / execute 两阶段确认，11 阶段事务状态机，中断后幂等恢复
多用户隔离	每个 UID 拥有独立的系统身份、systemd 服务、cgroup v2 配额、BPF policy 条目和数据目录
全链路审计	`memory.read` / `memory.write` / `memory.forget` 双通道写入 journald 与 auditd USER，auditd watch 规则同时留存真实 `SYSCALL/PATH` 证据

系统架构

系统自上而下分为三层：应用接口层负责与 Codex、Claude Code 和 Qwen Code 交互，记忆管理引擎层负责记忆的提取、组织与检索，OS 机制适配层负责把隐私与安全约束交给 Linux 原生机制强制执行。

file-memory 系统架构总览

应用接口层

这一层是插件与宿主 Agent 之间的全部契约，不包含任何记忆逻辑。

接口	形式	职责
`SessionStart`	Hook（180 s）	恢复中断的遗忘事务、迁移 schema、预热 BPF guard
`UserPromptSubmit`	Hook（30 s）	识别遗忘控制语句；把当前项目的中期偏好与全局长期偏好注入上下文
`Stop`	Hook（60 s）	增量读取 transcript，写入短期记忆；满 5 轮触发中期沉淀
`PreCompact`	Hook（60 s）	上下文压缩前，强制提交尚未落盘的窗口
`knowledge_search`	MCP 工具（stdio JSON-RPC 2.0）	只读知识检索，由宿主 Agent 按需主动调用
`knowledge-search`	Skill	指导 Agent 判断是否需要历史知识、构造一次精确查询并审查召回结果
`precise-forget`	Skill + CLI	把自然语言遗忘请求转成严格 `ForgetIntent` JSON，再交给 CLI 执行

应用接口层：会话生命周期与接口时序

设计上的两个要点：

偏好自动注入，知识按需检索。 偏好体积小、每轮都可能用到，由 Hook 无条件注入；知识体积大，只有 Agent 判断需要历史项目经验时才调用 MCP，避免污染上下文。
遗忘不接受自然语言。 CLI 只接受结构化 JSON 意图，自然语言的解释责任完全交给 skill，避免 CLI 层对「删除什么」做任何推断。

记忆管理引擎层

Node.js 实现（52 个 .mjs 模块），是记忆的提取、组织、晋升与检索中枢。所有入口都经过同一把全局互斥锁与召回阻断状态，因此 Hook 写入、MCP 检索、遗忘事务之间不会交叉。

引擎把记忆组织成三个层次，每层的内容、生命周期和读取路径都不同：

层次	内容	触发	位置
短期	脱敏后的原始对话轮次、工具输出、会话摘要	`Stop` 每轮增量写入	`memory/short/sessions/<id>/`
中期	五维偏好记录 + 四类知识文档（含 FTS5 与向量索引）	累计 5 轮触发 LLM 提取	`memory/mid/e-<entity>/`
长期	跨项目稳定偏好快照（不含知识）	原子键在 ≥2 个 entity 出现	`memory/long/preferences/`

三层记忆与检索链路

沉淀方向自下而上收窄：原始对话最多，能被提炼成偏好或知识的少，能跨项目稳定复用的更少。读取方向分成两条链路——偏好由 Hook 自动注入，知识由 Agent 按需通过 MCP 检索。

支撑这套结构的子系统：

子系统	关键实现
偏好流水线	固定 Schema 校验 → 持续性语义规则过滤 → 候选池跨窗口确认 → 确定性补丁写入
知识流水线	Stage 1 提取四类知识候选 → Stage 2 检索 Top-5 旧知识后决策 create / update / noop / review_required
混合检索	BM25 Top-20（标题×3、技术锚点×5、正文×1）+ 向量 Top-20 → 等权 RRF（k=3）→ Top-5
长期晋升	原子偏好键在 ≥2 个不同 entity 出现即写入全局快照
精准遗忘	溯源 DAG 解算级联目标 → preview 摘要校验 → 11 阶段状态机 → 幸存者重提取与派生索引重建
中文支持	nodejieba 分词 + HIT 停用词 + 技术锚点提取，保证中文查询在 BM25 侧可用

项目按 entity 隔离。宿主明确提供 workspace root 时使用其 realpath；否则优先使用当前目录所属 Git 仓库的根目录，非 Git 目录才使用当前目录的 realpath。中期记忆（偏好与知识）绑定 entity，长期偏好全局共享。

OS 机制适配层

这一层是本项目与普通应用层记忆方案的主要区别：安全属性不依赖插件自身的自觉，而由内核和 systemd 强制。

机制	作用
BPF LSM	8 个 LSM hook + auth map（leader TGID + `start_ticks`）+ policy map（device + inode + kind），逐文件判定写入授权。`messages.jsonl`、`tool_results.jsonl`、`tools/turn-N.md` 及其 `.tmp` 只允许已登记的 `privacyd` 写入
privacyd	以专用系统用户 `okmem-pd-<UID>` 运行的 Rust 守护进程，通过 Unix Socket 提供写前脱敏与原子写；用 `SO_PEERCRED` 校验调用方 UID
systemd	每个 UID 一个 `ok-memory-privacyd@<UID>.service`，`NoNewPrivileges`、空 `CapabilityBoundingSet`、`RestrictAddressFamilies=AF_UNIX`、`InaccessiblePaths` 隔离中长期记忆目录
cgroup v2	统一归属 `okmemory.slice`，CPU / Memory / IO / Tasks 四维计量与配额
journald + auditd	业务事件写 journald（identifier `ok-memory-audit`），同时经 per-UID root-owned helper 写 auditd USER 通道；`perm=rw` 规则留存受管目录的真实读写证据

OS 机制适配层：写入路径的用户态/内核态边界

分工是明确的：敏感内容的识别与替换全部在用户态完成，内核只负责回答「谁可以写」，不在内核中解析正文。任何一环（privacyd、session policy、BPF guard）不可用时，本轮受保护写入直接失败，不会降级为绕过脱敏的直接写入。

评测结果

项目提供知识检索、检索延迟、偏好提取、知识冲突处理、资源占用和敏感信息识别六项模块评测，以及 SWE-bench 编码任务记忆效率对比。

指标	结果	对照
知识检索 Recall@5（Hybrid）	97.3%	BM25 单路 81.1%，向量单路 86.5%
检索延迟 P95 / P50	284.9 ms / 188.5 ms	120 次测量，设计目标 ≤ 500 ms
偏好提取 F1（闭集）	82.05%	单次 LLM 基线 76.92%（+5.13 pp），12 个会话、17 条标注
偏好提取 Precision / Recall（闭集）	72.73% / 94.12%	基线 68.18% / 88.24%
知识冲突定位准确率	100%（30/30）	三个数据集（23 / 49 / 100 条知识库）
知识冲突端到端正确解决率	73.3%（22/30）	条件性重写准确率同为 73.3%
敏感信息识别 Precision / Recall / F1	78.93% / 82.23% / 80.55%	1009 个样本、7 个类别，严格匹配字符 span 与类别；Token 含原 Session Token
敏感信息样本完全正确率	57.78%（583/1009）	运行错误 0；不与旧数据集成绩直接比较
资源开销 RSS 峰值（ON vs OFF）	+573.3 MiB（2943.3 vs 2370.0）	含 privacyd、AI runtime、向量引擎；CPU 均值 +11.3 pp（16.04% vs 4.74%）
SWE-bench 重复任务效率（20 个 Issue）	在线耗时 −5.82%；Agent Token −29.29%	复用组相对 Baseline；含分类器的合计 Token −17.66%
自动化测试	59 个测试文件，约 275 个用例	—

知识检索召回率柱状图检索响应延迟柱状图

偏好提取准确率柱状图敏感信息识别 F1 柱状图

知识冲突处理正确率（端到端）模块资源占用对比

SWE-bench 三组在线耗时与 Token 对比

各项评测的实验设计、指标口径、运行方式与完整结果见对应文档：知识检索、检索延迟、偏好提取、知识冲突处理、资源占用、敏感信息识别、 SWE-bench 记忆效率。

运行环境

项目	要求
操作系统	openKylin 2.0 SP2（nile），内核 ≥ 6.6.0，需 BPF LSM + BTF + CO-RE
架构	x86_64
Node.js	≥ 24（ES Modules）
Rust	1.97.1（`privacyd` 与 enforce loader）
Python	≥ 3.10（spaCy NER worker）
外部服务	openKylin AI Runtime（端侧向量服务，768 维 GTE-base uint8）
LLM	DeepSeek Flash V4（`deepseek-v4-flash`）API Key

当前部署目标固定为本机环境：openKylin 2.0 SP2 (nile)、x86_64、内核 6.6.0-19-generic。以下安装、构建和验收流程均以这台机器为准。

安装流程

面向普通用户的最短流程只有以下三步：

安装并认证至少一个受支持 Agent（也可以暂时只装 file-memory 核心）
        ↓
bash src/file-memory/install.sh
        ↓
若提示 INSTALL_PENDING_RELOGIN：重新登录同一用户，再执行相同命令

安装完成后重启所选 Agent。无需逐条运行底层 setup-helper，也无需为每个项目重复注册。

安装器同时配置当前用户的 file-memory-background-commit.service。对话完成后先脱敏并保存短期记录，知识提取、更新和索引整理在后台运行；检索和偏好读取仍按当前任务需要执行。后台处理存在短暂延迟，刚完成的对话不一定立即成为可检索知识。

需要在切换 Agent 前确认当前项目的知识已就绪时，可以执行：

file-memory jobs
file-memory wait --timeout-ms 120000

wait 会提交当前项目尚未整理的内容，并等待本次已接收任务完成；超时或任务失败会返回非零退出码。失败任务可用 file-memory retry 重新尝试。用户完全注销时后台服务可能停止，任务保存在磁盘上，下一次登录或启动 Agent 后恢复。多存储部分写入失败会阻断相关记忆召回，不能将其当成已完成；新提交会沿持久化的固定计划核对并补齐，恢复时不重复进行模型判定。若检测到更新的外部修改、遗忘取消或缺少有效计划，则停止恢复，不能强制覆盖或误报成功。

偏好确认与语义晋升沿用原业务规则，文件和偏好向量更新分别校验并记录完成状态；中断恢复复用已确定的结果，不重复累计来源证据。偏好向量 helper 必须支持类型、维度和来源元数据；不兼容的旧构建会在准备阶段被拒绝，而不是继续发布不完整结果。

完整安装默认启用 enforce。该模式用于 OS 级敏感信息识别与写入保护，启用后会执行以下动作：

宿主 Agent 的 hooks 将当前轮用户文本、助手文本和工具文本提交给系统级 privacyd。
privacyd 识别身份证号、手机号、邮箱、姓名、API Key、Token、密码、私钥和用户配置的敏感词，并在写入前替换命中内容。
每个桌面用户都有独立的专用系统用户 okmem-pd-<UID>，脱敏后的短期记忆由该用户写入 /var/lib/ok-memory/<UID>/memory/short/sessions。
BPF LSM 只允许当前 UID 已登记的 privacyd 进程修改该 UID 的受保护短期记忆文件。同一普通用户下的其他进程也不能绕过识别流程直接写入原文。
privacyd、session policy 或 BPF guard 不可用时，本轮受保护写入失败，不会降级为直接写入。

敏感内容识别和替换由用户态 privacyd 完成；BPF LSM 负责在 OS 层强制写入边界，不在内核中解析正文。

安装命令应以实际运行 Agent 的普通用户执行，不要用 sudo 启动安装器。脚本只在安装系统依赖、系统服务、BPF bundle 或 auditd 配置时自行调用 sudo。

1. 准备宿主 Agent

可以先只安装 file-memory 系统核心，也可以提前安装并完成至少一个宿主的基础认证。统一安装器正式支持 Codex、Claude Code 和 Qwen Code；它会检测已有命令并让用户选择要连接的宿主，不会安装 Agent，也不会替用户创建平台账号。

默认安装者需要拥有 sudo 权限。统一安装器会检查机器级 file-memory 系统运行组件：第一位用户安装时自动准备并发布 privacyd、BPF loader/object、audit helper、向量 helper、spaCy/Python 依赖和 systemd 服务模板；后续用户校验并复用已有版本，不会重复发布。已有版本的升级、回滚和系统维护流程见管理员部署说明。

宿主 Agent 的账号、模型和网络连接由宿主自身管理。file-memory 安装器只配置记忆插件使用的 MCP 与 Hook；安装时输入的 DeepSeek Key 只供 file-memory 分类器使用。

2. 运行统一安装器

从仓库根目录执行。不带参数时，安装器会显示已接入和检测到的宿主，并询问要连接哪些 Agent。首次安装默认不连接宿主；后续运行回车保持现有连接，输入新宿主会追加接入，重复选择已接入宿主只做幂等确认。移除宿主使用 file-memory agent remove <agent>。

bash src/file-memory/install.sh

交互选择示例：

Currently connected: none
Detected on this machine: codex,claude
Supported: codex, claude, qwen, custom-mcp
Agents [none]: codex,claude

输入含义如下：

输入	效果
直接按 Enter	首次安装只安装 file-memory 核心；后续安装保留当前已接入的 Agent
`codex`、`claude` 或 `qwen`	接入一个正式支持的 Agent
`codex,claude,qwen`	一次接入多个 Agent
`none`	不接入 Agent，只安装共享核心
`custom-mcp`	生成通用 stdio MCP 配置模板，供其他 Agent 手动引用

安装器只连接用户选中的 Agent，不会安装 Agent，也不会修改其账号、模型或认证信息。未安装的正式宿主不能被接入；可以先选 none，安装宿主后再执行 file-memory agent add <agent>。

自动连接全部已安装宿主、只安装共享核心，或显式选择宿主也可以使用：

bash src/file-memory/install.sh --agents auto
bash src/file-memory/install.sh --agents none
bash src/file-memory/install.sh --agents claude,qwen
bash src/file-memory/install.sh --agents custom-mcp

custom-mcp 会在 ~/.config/file-memory/custom-mcp.json 生成标准 stdio MCP 模板，供其他支持 MCP 的 Agent 引用；它提供知识检索。自动记忆写入和偏好注入仍需为该宿主实现生命周期 Hook Adapter。

2.1 接入自定义 Agent

其他 Agent 只要支持 stdio MCP，就可以先接入 file-memory 的知识检索：

file-memory agent add custom-mcp

该命令生成：

~/.config/file-memory/custom-mcp.json

把其中 file-memory 条目复制到宿主 Agent 的 MCP 配置并重启宿主，即可发现只读工具 knowledge_search。模板不包含 API Key，也不固定项目路径；检索时根据宿主 workspace root 或当前工作目录解析 entity。

3. 安装 UKUI 桌面集成

install-file-memory.sh 会在已安装副本包含 desktop-integration 时自动编译并安装 UKUI 设置中心插件和 Peony 右键菜单插件。安装脚本会自动寻找当前系统的 Qt、Peony 插件目录和 UKUI 配置文件，把 ok-memory 注册到系统模块；其他用户只需要执行同一个安装入口，不需要手动编辑操作系统配置文件。

如果只需要重新安装桌面插件，可以执行：

bash src/desktop-integration/build-and-install.sh

该步骤需要当前用户的 sudo 权限。完成后重启 ukui-control-center，在“系统”分类中打开“AI 记忆”。

4. Agent 生命周期适配与安装检查

MCP 只解决“Agent 主动检索知识”的接口兼容。若自定义 Agent 还需要每轮偏好注入、会话捕获、五轮 Commit 和自动更新记忆，则必须把该宿主的会话开始、用户提交、回答结束和压缩前事件转换为 file-memory 的统一生命周期事件。不同宿主没有统一 Hook 标准，因此安装器不会猜测未知宿主的配置。适配接口与事件字段见项目说明书及 src/file-memory/scripts/agent-hook-adapter.mjs。

安装器依次完成：

检查 openKylin、Node.js、Rust、BPF LSM 和系统依赖；
检查机器级系统版本；完全缺失时准备发布源并通过 sudo 首次发布，已有有效版本时直接复用；
安全读取一次 DeepSeek API Key，仅供 file-memory 的记忆分类、提取和更新使用；
安装当前 UID 的 privacyd、enforce、audit、向量检索和宿主无关共享运行时；
在用户级配置中注册所选宿主的 MCP 与 Hook，不修改宿主自身的模型、账号或认证配置；
完成服务与权限验收。

机器级系统程序位于 /usr/local/libexec/file-memory/。不同用户复用程序，但仍分别拥有 /var/lib/ok-memory/<UID>/、专用服务身份、私有组、审计规则和 BPF policy。统一安装器只在系统布局完全干净时执行首次发布；已有版本无效、旧布局残留或并发安装导致布局变化时会停止，不会覆盖或自动修复。已发布版本也不会由普通安装流程自动升级。

DeepSeek Key 会写入当前用户私有的 file-memory 运行时配置，供分类器使用，不会写入 Qwen 或 Claude 的配置。若当前环境已经设置 DEEPSEEK_API_KEY，或已安装运行时中已有分类器 Key，安装器直接复用且不会再次询问。宿主 Agent 必须在接入前自行完成模型选择和认证。

刷新一次用户组权限

首次安装会创建当前 UID 的私有组 okmem-u<UID>。如果输出 INSTALL_PENDING_RELOGIN，请注销 openKylin 后重新登录同一用户，再执行完全相同的命令。该操作只是让新桌面、VS Code、SSH 和终端继承新增组权限，不会切换用户，也不会清空第一次安装的结果。

临时演示可以在当前终端执行：

newgrp "okmem-u$(id -u)"

然后从新 shell 再运行统一安装命令。成功时结尾会显示 file-memory installation completed，此后重启所选 Agent 即可使用。

完成后可执行以下三条命令检查安装和当前项目：

file-memory agent list
file-memory status
file-memory doctor

status 应显示当前 entity 与启用来源；doctor 应显示 MCP Server、Hook Adapter 均为 OK，并列出已经注册的 Agent。

安装后的共享运行时位于：

~/.local/share/file-memory/current

Codex 被选中时，~/.codex/file-memory-local-marketplace/file-memory 只是指向该共享运行时的宿主接入链接；Claude 和 Qwen 也连接同一份 MCP Server 与 Hook Runtime。

安装器在用户级注册 Agent：Claude Code 使用 user-scope MCP 和 ~/.claude/settings.json；Qwen Code 使用 ~/.qwen/settings.json。运行时优先从 Hook 事件取得 workspace root；否则从 MCP/Hook 工作目录解析 Git 项目根或普通目录 entity，不把项目路径固定在 Agent 配置中。

后续安装了新的 Agent，不需要重装系统核心：

file-memory agent detect
file-memory agent add qwen
file-memory agent repair qwen
file-memory agent remove qwen

repair 会恢复 file-memory 管理的 MCP 与 Hook 条目，并保留宿主的其他配置；remove 只解除该 Agent 的 MCP/Hook 连接，不删除已有记忆，也不修改用户原有模型设置。

file-memory 默认在所有项目启用，可按全局或项目覆盖：

file-memory disable --global
file-memory enable --global
file-memory disable --project "$HOME/my-project"
file-memory enable --project "$HOME/my-project"
file-memory inherit --project "$HOME/my-project"

项目开关存放在用户私有配置中，不写进项目仓库。单次会话可使用 FILE_MEMORY_BYPASS_SESSION=1 临时跳过全部自动读写。

底层的 prepare-environment.sh、install-file-memory.sh、finish-file-memory.sh 与各 Agent 配置生成器仍保留用于管理员排障，不再是普通用户需要逐条执行的主流程。

可选：配置自定义敏感词

自定义敏感词用于补充内置规则，例如内部项目名、实验室名称或其他不应进入记忆正文的字面值。编辑 src/file-memory/config/privacy-keywords.txt，每行填写一个非空字面值：

青鸟计划
dbhammer实验室

保存后重新执行统一安装入口：

bash src/file-memory/install.sh --agents auto

敏感词发生变化时，脚本会只刷新当前 UID 的 root-owned 副本和 instance manifest，并重启当前 UID 的 privacyd 使新规则立即生效；不会重启其他 UID 的实例。正常输出包含：

Registered file-memory instance for uid <UID> (<用户名>)
Verified file-memory instance for uid <UID>
System installation completed for plugin uid <UID>

如果文件内容没有变化，则输出 Instance for uid <UID> is already current.，不重启 privacyd。

enforce 模式使用以下固定目录，不应自定义 memory_root 或 state_root：

/var/lib/ok-memory/<当前用户 UID>/memory
/var/lib/ok-memory/<当前用户 UID>/state

可选：在项目目录查看受管数据

软链接只为查看数据提供方便，不改变真实存储位置、文件所有者或 enforce 保护边界。确保项目目录中不存在同名文件或目录后执行：

ln -s /var/lib/ok-memory/$(id -u)/memory memory
ln -s /var/lib/ok-memory/$(id -u)/state state

readlink -f ./memory
readlink -f ./state

正常输出为：

/var/lib/ok-memory/<UID>/memory
/var/lib/ok-memory/<UID>/state

可选：真实 Agent session 验收

收尾脚本只能完成系统和用户服务的基线验收。真实 session 验收用于确认已注册 Agent 的 Hook 已为新 session 创建 policy、登记当前 privacyd 实例并发布 BPF guard 就绪状态。

重启任一已注册 Agent，在目标项目中创建新 session 并至少完成一轮正常交互，然后在另一个终端执行：

bash src/file-memory/setup-helper/verify-live-session.sh

正常输出结尾为：

{"ok":true,"plugin_uid":<UID>,"sessions":<大于 0>,"generations":<大于 0>}
Live Agent session enforce verification passed

出现 ENFORCE_GUARD_NOT_READY 时，确认已重启已注册 Agent、创建新 session 并完成至少一轮交互后再执行。

日常使用

安装完成后不需要额外操作，插件随已注册 Agent 的会话自动工作。

偏好沉淀与注入：正常使用已注册 Agent 即可。每积累 5 轮对话，分类器提取一次偏好；下次会话开始时，当前项目的中期偏好和全局长期偏好被自动注入上下文。

知识检索：宿主 Agent 判断需要过去会话沉淀的项目知识时，自行调用 MCP 工具 knowledge_search。也可以直接要求它检索：

搜一下我们之前是怎么处理向量库重建的

同一知识检索 MCP 也可以接入 Claude Code 和 Qwen Code。项目提供宿主 Hook 适配器，将各 Agent 的生命周期事件归一化后复用每轮偏好注入、自动写入、五轮 Commit 和审计流程。配置方法和接口边界见项目说明书及本页 Agent 接入说明。

三个宿主在同一项目根目录启动时使用相同 entity，因此共享该项目的 file-memory 记忆；宿主自身的原生记忆目录不属于 file-memory，也不会作为跨 Agent 共享来源。验证共享时，可以先由一个 Agent 完成五轮对话并触发 Commit，再从同一项目根目录启动另一个已注册 Agent，自然询问前述项目决定，最后检查 MCP.knowledge_search 对应的 memory.read 审计事件。

精准遗忘：显式调用 skill，用自然语言描述范围。skill 把自然语言转成严格的 ForgetIntent JSON，先返回 preview，确认后才执行：

$file-memory:precise-forget 忘记这个项目 3 天前之前的所有记忆

支持的范围只有两类：当前项目（current_project）和相对时间/自然日（before / calendar_day）。 CLI 从不接收原始自然语言。

查看审计证据

register-user-instance.sh 已为当前 UID 安装并加载独立的 auditd 规则。完成一次真实记忆读写后，可以分别查看 journald 业务事件、auditd USER 事件和当前 UID 的受管文件访问证据：

journalctl -t ok-memory-audit --since "10 minutes ago"
sudo ausearch -m USER -ts recent -i |
grep -F "app=file-memory"
sudo ausearch -k "ok_memory_data_uid$(id -u)" -ts recent -i
sudo ausearch -k "ok_memory_state_uid$(id -u)" -ts recent -i

更新插件

普通更新用于把仓库中的 Node Hooks、脚本和文档同步到用户共享运行时，并保留已安装配置和数据：

bash src/file-memory/setup-helper/update.sh

共享 binary、Python 依赖、模型、systemd template、privacyd 或 BPF 产物发生变化时，请按照管理员部署说明发布并切换新的共享版本；统一安装器只负责系统布局完全干净时的首次发布，不覆盖或升级现有版本。共享版本切换完成后重新执行统一安装器。只修改自定义敏感词时也使用同一个入口，它会同步当前 UID 的实例配置并按需重启 privacyd：

bash src/file-memory/install.sh --agents auto

普通账户的统一安装器只读取 current 指向的发布版本，不会修改共享版本。用户插件更新完成后重启已配置的 Agent。

禁用和卸载边界

disable.sh 暂时解除已注册 Agent 的 MCP 与 Hook 连接，不删除共享运行时、系统服务或记忆数据：

bash src/file-memory/setup-helper/disable.sh

purge.sh 删除当前用户的共享运行时、Agent 注册和用户级服务配置：

bash src/file-memory/setup-helper/purge.sh

这两个脚本都不会删除 root-owned 系统合同或 /var/lib/ok-memory/<UID>/ 中的数据。要注销当前 UID 的系统实例，由管理员执行：

sudo "$HOME/.local/share/file-memory/current/setup-helper/unregister-user-instance.sh" \
  --plugin-uid "$(id -u)"

正常输出为 Unregistered file-memory instance for uid <UID>; persistent data was retained.。该脚本停止并移除当前 UID 的 service、runtime、BPF generations、配置、两份 sudoers、tmpfiles 和 audit rule，但保留 /var/lib/ok-memory/<UID>/、okmem-pd-<UID>、okmem-u<UID> 及其成员关系，且不移除共享发布版本目录。

如果普通账户已经由系统管理员删除，管理员可以用专用命令永久删除该账户残留的实例数据资产、专用服务身份和注册记录：

sudo bash src/file-memory/setup-helper/remove-deleted-user-instance.sh \
  --plugin-uid "<已删除账户的 UID>" \
  --app-user "<注册表中的账户名>" \
  --confirm-delete-data

该命令会删除 /var/lib/ok-memory/<UID>/（包括向量数据库数据）、BPF generations、实例配置、sudoers、tmpfiles、audit rules、okmem-pd-<UID> 与 okmem-u<UID>，并移除 instances.json 中对应的记录。命令运行前需要普通账户已确认不存在，且管理员在清理期间暂停账户创建与 UID 重新分配。共享发布版本目录保持不变。

管理员升级时如果注册表里存在已删除账户的残留记录，switch-release.sh 会在停止服务前逐项告警并跳过这些实例，继续升级其他有效实例。告警输出 DELETED_APP_INSTANCE，不会自动删除这些残留数据。

常用路径

仓库配置：src/file-memory/config/runtime.config.json
用户共享运行时：~/.local/share/file-memory/current
Codex 接入链接：~/.codex/file-memory-local-marketplace/file-memory
受管记忆：/var/lib/ok-memory/<UID>/memory
运行时状态：/var/lib/ok-memory/<UID>/state
session policy：/var/lib/ok-memory/<UID>/session-policy.json
guard 状态：/run/ok-memory/uid<UID>/
BPF pins：/sys/fs/bpf/ok-memory/uid<UID>/
共享发布版本目录：/usr/local/libexec/file-memory/releases/<版本>
当前共享发布版本：/usr/local/libexec/file-memory/current
实例注册表：/usr/local/etc/ok-memory/instances.json
当前 UID root 配置：/usr/local/etc/ok-memory/users/<UID>/
root enforce 目录：/usr/local/libexec/file-memory/current/enforce/

文档

文档	内容
项目说明书	系统设计、总体架构、核心模块、部署与评测
项目创新说明	三项主要创新、已有工作、代码位置和验证依据
成员分工及主要贡献说明	A/B/C 匿名分工与实际贡献
人工智能及第三方工具使用说明	工具、依赖、数据、许可证和人工验证责任
管理员部署说明	共享版本发布、系统验收和升级
测试与验证材料	单元测试、七项 benchmark 和评测结果

安装和运行以本 README 及源码中的部署说明为入口；具体接口以当前代码和自动化测试为准。

仓库结构

.
├── README.md
├── src/
│   ├── file-memory/             # 插件、privacyd、BPF、安装器及 test/
│   ├── cli/                     # 向量库诊断工具
│   └── desktop-integration/     # UKUI 和 Peony 桌面集成
├── docs/
│   ├── 项目说明书.pdf
│   ├── 项目创新说明.pdf
│   ├── 成员分工及主要贡献说明.pdf
│   └── 人工智能及第三方工具使用说明.pdf
├── tests/                       # benchmark、固定数据、结果、figures 和回归入口
├── demo/                        # 完整插件与评测的链接入口
├── presentation/                # 决赛 PPT、MP4 和高清网盘链接
└── 作品原创承诺书.pdf

测试

source "$HOME/.nvm/nvm.sh" && nvm use 24
bash tests/run-tests.sh
node --test src/file-memory/test/*.test.mjs

需要 root 的 enforce 用例（smoke-enforce-root、multi-user-enforce）只在已完成系统安装的 openKylin 机器上有效，其余用例可在任意 Node.js 24 环境运行。

源码构建

完整安装会准备工具链和系统依赖并构建各组件；已有开发环境中可单独构建：

npm --prefix src/file-memory ci
bash src/file-memory/setup-helper/build-native-helper.sh "$PWD/src/file-memory"
bash src/file-memory/setup-helper/build-privacyd.sh
bash src/file-memory/setup-helper/build-enforce.sh

共享发布版本、系统验收和升级见管理员部署说明；桌面组件使用安装流程中的 src/desktop-integration/build-and-install.sh。

已知限制

正式部署目标为 openKylin 2.0 SP2、x86_64 及支持 BPF LSM/BTF 的内核；其他平台尚需适配验证。
自动沉淀依赖分类器 API；宿主 Agent 另需有效账号和模型连接。向量服务失败时可降级为 BM25，不能把降级结果视为双路成功。
分类会将经脱敏的窗口发送至远端模型；embedding 与检索在本地进行。敏感识别存在遗漏可能，不替代使用方的数据合规判断。
后台更新为最终一致；立即跨 Agent 使用刚写入的内容时可先执行 file-memory wait。
custom-mcp 提供通用检索接入，完整自动捕获需要宿主生命周期适配。
完整 benchmark 依赖模型、网络及端侧环境，会消耗模型额度；固定数据、口径与运行前提见 tests。