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

本项目面向 OS Agent 的本地记忆管理场景，提供多源记忆统一接入、偏好提取与版本管理、关键词与多语言向量混合检索、RAG 上下文构建、安全授权及精准遗忘能力。项目以 FastAPI、SQLite FTS5、Multilingual E5 和 NumPy 向量索引为主要技术组件，可在离线环境中完成记忆写入、检索、偏好更新、遗忘预览、确认删除和审计查询的完整闭环。

项目已在 macOS 开发环境和 openKylin 2.0 SP2（x86_64）环境完成运行与自动化测试。

一、已完成能力

1. 多源记忆统一接入

• 使用统一的 MemoryEvent 数据结构管理记忆编号、用户、正文、来源、时间、主题、敏感等级、状态和扩展元数据。
• 支持 JSON、CSV、TXT 三种文件批量导入。
• 支持会话、工具执行结果、手动配置等来源通过 source 和 metadata 字段统一入库。
• 导入时执行字段校验、UTF-8 文本处理、重复编号更新和逐条错误统计。
• 单个上传文件上限为 5 MB。

2. 偏好提取与版本管理

• 从有效记忆中提取工具选择、操作习惯、输出风格和安全策略四类偏好。
• 显式偏好可直接生效，隐式偏好需要多条独立证据后生效。
• 相同取值只强化证据和置信度，不重复创建版本。
• 偏好变化时保留旧版本、版本号、证据来源和有效时间区间。
• 支持查询完整版本历史，并通过回滚生成新的活动版本。
• 删除源记忆时同步清理相关偏好证据，并按剩余证据重新确定有效版本。

3. 混合检索与 RAG 上下文

• 使用 SQLite FTS5 完成关键词检索。
• 使用 Multilingual E5 完成中英文及跨语言语义检索。
• 使用加权 RRF 融合关键词结果和向量结果。
• 支持按用户、主题、来源和记忆状态过滤，防止跨用户结果混入。
• 使用 E5 原始相似度进行低相关查询拒答，RRF 分数用于结果排序。
• 生成带来源编号、条数限制和估算 token 预算的 RAG 上下文。
• 提供确定性的 Hash Embedding 后备模式，用于无模型环境下的接口联调和流程验收。

4. 精准遗忘与审计

• 遗忘操作采用“预览—明确确认—执行”的两阶段流程。
• 预览结果具有 15 分钟有效期，执行请求必须携带唯一幂等键。
• 固定执行安全授权、向量与缓存删除、持久层删除、偏好派生数据清理、审计回执和删除后验证。
• 同一幂等键重复提交不会重复删除。
• 支持查询审计回执，并对部分失败的目标进行定向重试。
• 删除后会同步检查 SQLite 数据、FTS5 索引、NumPy 向量索引和检索缓存。

5. 安全持久化适配器

• 支持允许执行者和敏感数据特权执行者配置。
• 支持用户隔离和跨用户删除拒绝。
• 当前规则可识别邮箱、手机号、中国大陆身份证号、银行卡号、常见凭据字段和病历类文本。
• 支持依据记忆声明的敏感等级进行授权控制。
• 使用 SQLite 事务完成持久层删除，并保存可查询的 security-audit: 审计引用。
• 对同请求重试和目标已不存在的情况提供幂等回执。

二、系统结构

JSON / CSV / TXT / API
          │
          ▼
统一模型与数据校验 ──────► SQLite 持久化（WAL）
          │                       │
          ├────────► 偏好提取与版本管理
          │
          └────────► FTS5 关键词索引
                     + E5 / Hash 向量索引
                              │
                              ▼
                   Hybrid RRF + 拒答门控
                              │
                              ▼
                      RAG 上下文构建

精准遗忘：
结构化选择器
  → 预览匹配范围
  → 明确确认与幂等校验
  → 安全授权
  → 向量、缓存与持久层删除
  → 偏好派生数据清理
  → 审计回执与删除后验证

最终集成入口为 app.final_main:app，它同时装配应用底座、检索模块、RAG 上下文、安全持久化适配器和精准遗忘编排器。

三、运行环境

已验证环境

环境	验证情况
macOS，Python 3.13	完整自动化测试通过
openKylin 2.0 SP2，x86_64，Python 3.12.2	服务启动、健康检查、遗忘契约和自动化测试通过

基本要求

• Python 3.10 或更高版本
• Git
• python3-venv、python3-pip
• 支持 SQLite FTS5 的 Python/SQLite 环境

openKylin 可先安装基础依赖：

sudo apt update
sudo apt install -y git python3 python3-venv python3-pip curl

四、快速开始

1. 获取代码

git clone https://gitlink.org.cn/Ix3quXm7vy/mxokdzntjytqyjzywjz.git openkylin-memory-agent
cd openkylin-memory-agent

2. 创建虚拟环境并安装依赖

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

3. 选择向量模型

正式检索效果使用 Multilingual E5。联网环境可提前准备模型：

python -m scripts.prepare_e5_model --output models/multilingual-e5-small
export MEMORY_E5_MODEL_PATH="$PWD/models/multilingual-e5-small"
export MEMORY_E5_OFFLINE=1

没有 E5 模型时，可使用后备模式完成接口和遗忘流程验证：

export MEMORY_EMBEDDING_BACKEND=hash

Hash Embedding 仅用于联调，不代表正式检索效果。

4. 启动最终集成服务

python -m uvicorn app.final_main:app --host 0.0.0.0 --port 8000

浏览器打开：

• Swagger 接口页面：http://127.0.0.1:8000/docs
• 健康检查：http://127.0.0.1:8000/health

五、主要接口

模块	方法与路径	功能
系统	GET /health	服务健康检查
记忆	POST /memories	新增或更新记忆
记忆	GET /memories	按用户查询记忆
记忆	GET /memories/{memory_id}	查询单条记忆
导入	POST /ingestion/json	批量导入 JSON
导入	POST /ingestion/csv	批量导入 CSV
导入	POST /ingestion/txt	批量导入 TXT
偏好	POST /preferences/extract	提取并更新偏好
偏好	GET /preferences	查询当前偏好或历史版本
偏好	GET /preferences/{preference_id}/history	查询版本链
偏好	POST /preferences/{preference_id}/rollback	回滚到历史版本
检索	POST /retrieval/reindex	同步活动记忆到检索索引
检索	POST /retrieval/search	执行混合检索
检索	POST /retrieval/context	构建带引用的 RAG 上下文
遗忘	GET /forget/contract	查询遗忘接口契约
遗忘	POST /forget/preview	预览遗忘范围
遗忘	POST /forget/execute	明确确认后执行遗忘
审计	GET /forget/audit	查询审计回执列表
审计	GET /forget/audit/{request_id}	查询单次完整回执
审计	POST /forget/audit/{request_id}/retry	重试失败目标

完整字段和错误语义见 docs/API_CONTRACT.md 与 docs/FORGETTING_INTEGRATION_CONTRACT.md。

六、核心流程复验

1. 新增测试记忆

在 Swagger 中调用 POST /memories：

{
  "memory_id": "final-demo-001",
  "user_id": "default",
  "content": "用户偏好使用中文回答，并希望回答尽量简洁。",
  "source": "conversation",
  "created_at": "2026-07-22T20:00:00+08:00",
  "topic": "输出偏好",
  "sensitivity": "normal",
  "status": "active",
  "metadata": {
    "purpose": "final_acceptance"
  }
}

2. 检索与 RAG 验证

依次调用：

1. POST /retrieval/reindex
2. POST /retrieval/search
3. POST /retrieval/context

检索结果应包含 final-demo-001，RAG 上下文应包含来源编号和原始记忆内容。

3. 精准遗忘验证

1. 调用 POST /forget/preview，通过 memory_ids 或主题选择目标。
2. 记录返回的 preview_id 和 matched_ids。
3. 调用 POST /forget/execute，提交 preview_id、confirm=true 和唯一 idempotency_key。
4. 再次查询 GET /memories/final-demo-001，应返回 404。
5. 再次执行检索，结果中不应出现该记忆。
6. 使用返回的 request_id 调用 GET /forget/audit/{request_id}，检查数据库、向量、缓存和审计结果。

七、自动化测试与 openKylin 验证

完整测试

source .venv/bin/activate
python -m pytest -q

openKylin 一键验证

bash scripts/openkylin_verify.sh

脚本会检查系统与提交信息、准备 Python 环境、安装依赖、运行测试、临时启动服务，并验证 /health 和 /forget/contract。

已取得的结果

场景	结果
开发环境完整测试	77 passed, 1 warning
openKylin 2.0 SP2 离线验证	72 passed, 5 skipped, 1 warning
openKylin 健康检查	{"status":"ok"}
openKylin 遗忘契约	契约版本 1.0，检索与安全适配器加载成功
openKylin 最终服务	app.final_main:app 在本机端口成功启动

openKylin 环境跳过的 5 项均为需要本地 Multilingual E5 模型文件的效果测试。其余接口、安全、检索和遗忘流程测试正常执行。

八、量化评测结果

检索评测数据集包含 160 条记忆和 100 条查询，覆盖中文、英文、跨语言、精确命令及无答案查询。调参集与验证集独立划分。

检索质量

后端	Recall@1	Recall@5	MRR
SQLite FTS5	0.4091	0.5909	0.4598
Multilingual E5	0.6364	0.6364	0.6364
Hybrid RRF（调参后）	0.6364	0.6818	0.6477

检索延迟

每个后端执行 120 次正式请求，模型加载时间与单次查询时间分开统计。

后端	平均延迟	P95 延迟	QPS
SQLite FTS5	1.682 ms	2.201 ms	594.585
Multilingual E5	16.124 ms	17.631 ms	62.018
Hybrid RRF（调参后）	19.994 ms	22.125 ms	50.016

当前评测中 Hybrid RRF 的 P95 检索延迟为 22.125 ms，低于赛题要求的 500 ms。详细数据、拒答阈值和结果分析见 docs/member_a/retrieval_evaluation/final-report.md。

九、配置项

环境变量	说明	默认值
MEMORY_DB_PATH	SQLite 记忆数据库路径	项目默认数据库路径
MEMORY_EMBEDDING_BACKEND	向量后端：e5 或 hash	e5
MEMORY_E5_MODEL_PATH	本地 E5 模型目录	未设置
MEMORY_E5_OFFLINE	是否禁止联网加载模型	0
MEMORY_E5_DEVICE	E5 推理设备	cpu
MEMORY_E5_REJECTION_THRESHOLD	E5 拒答阈值	0.864102
MEMORY_RETRIEVAL_FTS_PATH	FTS5 索引数据库路径	项目默认路径
MEMORY_SECURITY_ALLOWED_ACTORS	允许执行遗忘的执行者列表	leader,owner,admin,test
MEMORY_SECURITY_PRIVILEGED_ACTORS	可删除敏感记忆的特权执行者列表	owner,admin

十、项目结构

app/          FastAPI 应用入口与最终集成
core/         统一数据模型、SQLite 数据库和公共接口
ingestion/    JSON、CSV、TXT 批量导入
preference/   偏好提取、版本更新和回滚
retrieval/    FTS5、向量索引、混合排序和 RAG 上下文
forgetting/   预览、执行、重试和审计编排
security/     安全授权、敏感规则和事务删除
evaluation/   检索数据集、指标、调参和延迟评测
sample_data/  导入与偏好流程样例数据
scripts/      模型准备、演示和 openKylin 验证脚本
tests/        自动化测试
docs/         接口、部署、集成和评测文档

十一、文档索引

• 赛题原始要求
• 三人协作接口约定
• 精准遗忘接口冻结说明
• 检索、RAG 与遗忘最终集成说明
• openKylin 安装与验证说明
• 检索模块最终评测报告

十二、当前范围与已知限制

• 当前敏感信息识别使用应用层本地规则，尚未实现 LSM Hook、eBPF/BPF LSM 或 UKUI 插件。
• 当前安全审计保存在 SQLite 中，尚未接入 auditd 或 systemd-journald。
• 当前向量索引为内存 NumPy 实现，适合原型和中小规模数据。
• 当前精准遗忘接口接收结构化选择器，尚未提供自然语言指令到选择器的独立解析模型。
• 当前未实现可由用户动态配置的自定义敏感模式。
• 当前未实现完整的短期、中期、长期记忆自动流转和通用知识冲突裁决模块。
• 检索质量结果来自确定性评测数据集，接入真实用户数据或更换模型后需要重新评测并标定拒答阈值。
• Hash Embedding 只用于离线接口联调，不用于正式检索质量结论。

本 README 仅列出已经实现并完成代码测试或环境验证的能力，未完成的系统级机制不计入当前实现范围。