libkylin-mem

文档下载

比赛相关文档（项目说明书、PPT、演示视频、原创承诺书）获取
- （1）见项目初赛提交材料文件夹
- （2）通过百度网盘下载
```
通过百度网盘下载
链接: https://pan.baidu.com/s/16dWBca8vB5L_oohQA_9x7w?pwd=xbhq 
提取码: xbhq
```

项目介绍

面向 openKylin 操作系统智能体（OS Agent）的可插拔记忆系统 —— C11 核心库 + 常驻 daemon + CLI + Python SDK，专为 openKylin 设计并已在 openKylin 2.0 SP2 上完成全量实测。

对外提供两条使用途径：命令行工具 km0ctl 和 Python SDK（kylinmem0），两者都经由常驻 daemon km0d 读写同一份记忆库。

这是什么 / 为什么做

智能体要提供个性化服务，必须”记得住”用户：偏好（操作习惯、输出风格、安全策略）与知识（工作流程、历史案例、可复用模板），还要能随需检索、随令遗忘。但 OS 层面的记忆数据存储、访问、隔离、审计长期缺乏原生机制支撑，敏感信息识别也常停留在应用层正则。libkylin-mem 把这套能力做成嵌入 OS 的记忆底座：

多类型与记忆标签：同一条记忆可同时属于知识、偏好、经历等多个类型；LLM 生成规范化标签，标签与向量候选共同交给 LLM 判断合并、替换、保留或丢弃
用户控制的 Revision：日常变更先累计为作用域 draft，何时保存由用户决定；系统只存版本间正向/反向 delta，可查看、放弃、回溯或清空已保存历史（保留当前 draft 和记忆；无 draft 时建立可保存的新基线草稿）
知识整合与检索：全文 / 向量 / 混合三种检索策略，jieba 中文分词，跨语言语义检索，新旧知识冲突检测与融合
敏感识别与精准遗忘：PII / 凭据 / 自定义三类规则、四种处置模式；自然语言指令驱动的精准遗忘（可审计、不可恢复）
四项 OS 级机制：BPF-LSM 内核访问拦截、cgroup v2 + systemd 用户服务资源管控、journald/auditd 系统审计、UKUI/D-Bus 桌面联动
性能达标：检索响应 P95 ≤ 500ms 全组通过（量化指标见 docs/reports/p6-performance.md）

系统经稳定的 C ABI（include/kylinmem0/kylinmem0.h）对外提供六层可插拔抽象：统一记忆模型、存储后端、嵌入模型、检索策略、抽取策略、编排服务。上层的常驻 daemon km0d 通过 Unix Socket 为多客户端共享服务，km0ctl 为纯命令行客户端，Python SDK 经 ctypes 绑定同一 ABI。

项目架构

libkylin-mem 项目架构

要点：

**核心库 libkylinmem0.so**：全部能力的载体，C ABI 是唯一对外入口，上层组件（daemon、SDK）都构建在其上，也可被任意语言经 FFI 直接嵌入。
**daemon km0d**：推荐的使用方式。作为 systemd 用户服务常驻，所有客户端经 Unix Socket 共享服务——记忆库只开一份、配置（检索模式、敏感处置、审计）统一在 daemon 侧生效，CLI、Python、Web 工作台、桌面面板看到的数据完全一致。
Python SDK 两种模式：daemon 模式（传 daemon_socket，功能全集，含 revision/forget/ingest）与嵌入式直连模式（不传 socket，进程内直接加载 libkylinmem0.so，适合脚本与测试）。

使用途径

途径一：命令行 `km0ctl`

安装后 km0d 已由用户服务拉起，直接发命令即可（未走安装、用源码构建时见下文「手动构建」）：

km0ctl add "我喜欢用中文交流"                     # 写入记忆
km0ctl search "中文"                              # 检索（jieba 中文分词）
km0ctl forget "忘记我上周关于X项目的偏好" --dry-run  # 自然语言精准遗忘（预演）
km0ctl revision save "阶段完成"                    # 保存一个可回溯的版本

途径二：Python SDK

SDK 为 ctypes 绑定、零第三方依赖，源码在 bindings/python/（未发布 pip 包，需加入 PYTHONPATH）：

export PYTHONPATH=<源码目录>/bindings/python
export KYLINMEM0_LIBRARY_PATH=/usr/local/lib/libkylinmem0.so   # 一键安装后建议显式指定

import os
from kylinmem0 import MemoryServiceHandle

sock = os.path.expandvars("$XDG_RUNTIME_DIR/km0/km0d.sock")   # 连 daemon 的 socket
with MemoryServiceHandle(os.path.expanduser("~/.local/share/km0/km0.db"),
                         daemon_socket=sock) as svc:
    svc.add("我喜欢用中文交流", user_id="alice")
    for r in svc.search("中文", user_id="alice", top_k=5):
        print(r.id, r.content)

不传 daemon_socket 即为嵌入式直连模式（无需启动 daemon，功能子集）。SDK 全部接口、C API 与 daemon 协议细则见 docs/user-guide.md。

特性

SQLite/FTS5 存储 + jieba 中文分词；sqlite-vec 向量检索（cosine）；hybrid = cosine + BM25 融合
直接抽取 + 可选 LLM 事实抽取（提示词运行时从 config/prompts/ 加载，改动免重编译）
记忆融合 merge（写入时语义去重 / 冲突消解）与周期性记忆整理 compact
多源数据接入 ingest：工具执行结果、用户行为、手动配置的统一解析、质检与标准化
审计多 sink：文件 / journald / auditd / 桌面通知，支持逗号分隔叠加
scope 数据隔离（user / project / 多值 memory_types / tags / source）；记忆 ID 库内单调递增 km0_<N>；数据库与审计日志权限 0600

快速开始（openKylin）

1. 磐石模式切换

openKylin 磐石（不可变）模式下 /usr 只读且 apt 被禁用，安装前须先切到维护模式：

mm-cli -s            # 查询当前模式
sudo mm-cli -o       # 重启进入维护模式
# …… 在维护模式下完成安装 ……
# 执行 2. 一键安装
# ============
sudo mm-cli -c -a    # 保存修改并退出维护模式（自动重启）

2. 一键安装

sudo scripts/install.sh

脚本依次完成：apt 安装依赖 → CMake 构建（独立 build-install/，不影响开发构建目录）→ 安装到 /usr/local → 为当前用户安装 km0d systemd 用户服务（随登录自启）→ add / search / delete 冒烟自检。可选项：--with-os-guard（追加 BPF-LSM 内核守护）、--with-demo（追加演示程序依赖）、--skip-deps（跳过 apt）。

3. 装好后三步体验

安装完成后 km0d 已由用户服务拉起，km0ctl 在 /usr/local/bin：

export KM0_DAEMON_SOCKET=/run/user/$(id -u)/km0/km0d.sock
km0ctl add "我喜欢用中文交流"        # 写入一条记忆
km0ctl search "中文"                 # 检索记忆（jieba 中文分词）
km0ctl list                          # 列出全部记忆

其余常用命令各一行：km0ctl update ID 内容、km0ctl revision status、km0ctl revision save "阶段完成"、km0ctl revision rollback 1、km0ctl revision clear、km0ctl forget "忘记我上周关于X项目的偏好" --dry-run、km0ctl sensitive check "文本"、km0ctl ingest 文件。完整命令与环境变量见 docs/user-guide.md 与 docs/部署与使用手册.md。

一键安装时脚本会探测仓库 .env 中的 KM0_EMBEDDING_API_KEY：已配置则服务默认以 --retrieval hybrid（LLM + 向量混合检索）启动，未配置则为纯全文模式。安装后才补充 key 的，往 ~/.local/share/km0/km0d.env 追加 KM0_LLM_API_KEY / KM0_EMBEDDING_API_KEY 等变量（写法见 docs/部署与使用手册.md 6.2/6.4 节），重跑幂等的 scripts/km0d-user-service.sh install --prefix /usr/local 重新生成服务单元，再 systemctl --user restart km0d。

手动构建与测试（开发者）

构建（CMake ≥ 3.16，SQLite ≥ 3.20 且带 FTS5）：

# 默认 LLM 构建（需要 libcurl；赛题功能全集，推荐使用）
cmake -S . -B build-llm -DBUILD_TESTING=ON -DKM0_ENABLE_LLM_EXTRACTION=ON
cmake --build build-llm

# 纯离线构建（不依赖 libcurl，无 LLM/embedding 能力，仅用于离线差异校验）
cmake -S . -B build -DBUILD_TESTING=ON -DKM0_ENABLE_LLM_EXTRACTION=OFF -DKM0_ENABLE_API_EMBEDDING=OFF
cmake --build build

测试：

ctest --test-dir build-llm -j4                       # 全量回归（61 项，只在 LLM 构建上跑）
ctest --test-dir build -L "acceptance|offline"       # 离线构建差异校验（8 项）
python3 -m pytest benchmark/tests -q                 # 评测流水线测试（201 项）

源码目录直接体验（不走安装，LLM 抽取 + 向量混合检索）：

source ./env.sh                  # 导出 KM0_* 环境变量并加载 .env 中的 LLM/embedding 配置，数据集中到 ~/.local/share/km0/
./build-llm/km0d start --daemon --retrieval hybrid
./build-llm/km0ctl add --llm --vector "I prefer Chinese answers"
./build-llm/km0ctl search --hybrid "Chinese"
./build-llm/km0d stop

目录结构：

路径	内容
`include/kylinmem0/`	公共 C ABI 头文件（对外唯一入口）
`src/`	全部 C/C++ 源码：core / storage / retrieval / embedding / extraction / sensitive / forget / ingest / fusion / audit / daemon / cli / transport / ebpf
`config/`	`prompts/`（LLM 提示词，运行时加载）、`schemas/sqlite-v6.sql`、`memory_tags.json`（标签注册表）、`sensitive.json`（敏感规则）
`bindings/python/`	Python SDK（ctypes）
`tests/`	unit / contract / integration / acceptance / cli / llm / live / performance
`benchmark/`	量化评测流水线（召回 / 敏感 F1 / 偏好准确率 / 冲突 / 延迟）
`scripts/`	一键安装与各 OS 机制验证脚本
`packaging/`	systemd unit 模板、ukui-control-center「AI 记忆」面板插件
`demo/web-agent/`	中文记忆智能工作台：对话、三层记忆、记忆治理与评测
`third_party/`	vendored 依赖（见下节）
`docs/`	设计文档、验证与评测报告、使用指南

更细的模块划分、容量常量与开发约定见 AGENTS.md。

Demo：记忆智能工作台

demo/web-agent/ 提供面向用户的中文记忆智能工作台。主要能力包括流式智能对话、多会话恢复、短中长期记忆流转、记忆检索与沉淀、自然语言遗忘、Revision 保存/回溯、compact。

Web-Agent 演示了完整的 Agent 记忆闭环：当前会话最近消息作为短期记忆，滚动摘要作为中期任务上下文，稳定事实、偏好与可复用知识经 km0d 抽取并沉淀为可跨会话召回的长期记忆。记忆库页面同时提供作用域隔离、版本草稿、精准遗忘和历史回溯等用户控制能力。

完成上文的 build-llm 构建并安装 Demo 依赖后，一条命令同时拉起 daemon 与 Web-Agent（默认 LLM + 向量混合检索，需 .env 中配置 KM0_EMBEDDING_API_KEY）——脚本自动从 8010 起挑选空闲端口、在终端输出访问地址，Ctrl-C 统一停止：

./scripts/start_demos.sh           # 默认 hybrid 混合检索

如果已有自行管理的 km0d，可只启动 Web-Agent：

source ./env.sh
./build-llm/km0d start --daemon --retrieval hybrid
bash demo/web-agent/scripts/start_demo.sh

单独启动 Web-Agent 时浏览器默认访问 http://127.0.0.1:8000/。未配置 KM0_DEMO_LLM_URL 与 KM0_DEMO_LLM_API_KEY 时页面仍可打开，但智能对话不可用；变量未单独设置时会回退到项目的 KM0_LLM_* 配置。完整启动选项、安全边界和演示流程见 demo/web-agent/README.md。

桌面面板：UKUI 控制中心「AI 记忆」

安装 km0-ukcc-plugin 后（步骤见 docs/部署与使用手册.md §9.1），ukui-control-center「应用」分组出现「AI 记忆」面板，可图形化管理 km0d：上方查看 daemon 状态并启动 / 停止 / 重启（底层即 systemctl --user，无需 root），下方表单读写 ~/.local/share/km0/km0d.env（LLM / Embedding 配置、敏感模式、审计后端、桌面通知），「保存并重启 daemon」一键使配置生效。

「AI 记忆」面板：km0d 未运行

点击「启动」后状态变为「运行中（active）」：

点击「启动」后：km0d 运行中

服务参数表单（保存后文件权限收 0600，未知键与注释原样保留）：

服务参数（km0d.env）表单

openKylin 2.0 SP2 实拍；截图中 Embedding URL 已替换为公共示例地址，API Key 始终以密码掩码显示。更多细节见 docs/部署与使用手册.md §9.1.1。

文档导航

docs/部署与使用手册.md —— 环境依赖、安装步骤、配置项说明
docs/design/概要设计说明书.md —— 系统目标、总体能力与关键取舍
docs/design/详细设计说明书.md —— 模块流程、接口契约与异常语义
docs/design/architecture.md —— 权威架构与 schema v6 记忆数据结构模型
docs/design/web-agent-redesign.md —— Web-Agent 三层记忆、页面与 API 设计
docs/reports/测试报告.md —— 测试环境、用例与量化评测结果
docs/reports/p6-performance.md —— 六项量化指标、性能分档与 benchmark 方法
docs/user-guide.md —— 使用指南（核心概念 / CLI / C API / SDK 细则）
docs/赛题要求.md —— openKylin 社区赛题原始要求
PROGRESS.md —— 当前实现情况与量化指标

第三方组件与开源说明

本项目完全开源。核心层只依赖 C 标准库与 SQLite；以下组件以源码形式 vendored 于 third_party/，各自保留原始许可证（见各子目录）：

third_party/cjieba —— cjieba/cppjieba 中文分词（FTS5 km0_jieba 分词器）
third_party/cJSON-1.7.18 —— cJSON，JSON 编解码
third_party/sqlite-vec —— sqlite-vec，SQLite 向量检索扩展

可选外部依赖（系统包）：libcurl（LLM 抽取 / API embedding）、libsystemd 与 libaudit（journald/auditd 审计 sink）、libbpf（BPF-LSM 守护，默认不启用）。

测试密钥说明

仓库根目录的 .env 内含一个供测试使用的 API Key，仅供本项目功能测试使用（如 LLM 抽取、API embedding 的联调用例），请勿用于任何其他用途。正式部署时请通过 KM0_EMBEDDING_API_KEY 等环境变量配置自己的密钥。