Memory Kernel

Memory Kernel

Memory Kernel 是一个面向 AI Agent 的轻量本地记忆层。

它可以将决策、约束、任务、事实和笔记等有用信息保存在本地 SQLite 数据库中，然后只为当前任务取回少量相关记忆。

在 PyPI 上发布的包名：amormorri-memory-kernel 安装后的 CLI 命令：memory-kernel

乌克兰语实用指南： docs/OPERATING_GUIDE_UK.md

发行说明： CHANGELOG.md

目录

• 功能介绍
• 5 分钟快速开始
• 典型工作流
• 该使用哪个命令
  • 写入：remember、ingest
  • 读取：search、context、wake-up、stats
  • 查看 / 编辑：list、show、update、delete
  • 生命周期：forget / restore、revise、decay
  • 维护：completion、verify
  • 备份：export、import
• 与大模型配合使用（MCP）
• 工作原理
  • 数据流
  • 组件图
  • 记忆记录架构
  • 乌克兰语词形变化衔接
• 为何保持轻量
• 适用对象
• 项目状态
• 原生加速器
• 反馈

功能介绍

简单来说，Memory Kernel 做 4 件事：

1. 在你的机器上本地存储记忆。
2. 让记忆保持足够清晰的结构，以便发挥作用。
3. 无需繁重的向量技术栈即可查找相关记录。
4. 构建精简的上下文包，而不是把所有内容都塞进提示词。

本项目无意打造神奇的黑盒记忆，而是要创建一个你可以查看、控制、导出并信赖的记忆层。

5 分钟快速开始

如果你只想试试看，请按以下步骤操作：

pip install amormorri-memory-kernel
memory-kernel init
memory-kernel remember --scope my.project --kind decision --title "Keep memory local" --content "We store memory on the user's machine."
memory-kernel search "memory local"
memory-kernel export --format json --output exports\memory.json

刚才发生了什么：

1. init 创建了本地数据库。
2. remember 保存了一条清晰的记忆。
3. search 将它检索出来。
4. export 创建了一个备份文件，你可以之后移动或恢复它。

如果你使用的是代码仓库，而不是 PyPI：

pip install -e .[dev]

典型工作流

大多数人会这样使用：

1. 使用 remember 保存一条精确的记忆。
2. 使用 ingest 输入原始笔记或转录文本。
3. 在 Agent 运行前，使用 search、context 或 wake-up 仅获取相关内容。
4. 使用 show、update 或 delete 查看、修正或删除单条记录。
5. 定期导出数据库以进行备份。
6. 使用 import 在其他位置恢复数据库。

该使用哪个命令

remember

如果你已经确切知道要保存什么，请使用 remember。

适用示例：

• 一项决策
• 一条规则
• 用户偏好
• 项目约束

memory-kernel remember --scope project.alpha --kind decision --title "Use SQLite FTS5" --content "We use SQLite FTS5 for local retrieval."

ingest

如果你有原始文本，并希望系统将其拆分为结构化记忆，请使用 ingest。

适用示例：

• 会议笔记
• 转录文本
• 粗略的规划文档
• Agent 会话日志

memory-kernel ingest --scope project.alpha --file notes.txt --source sprint-review --tags planning transcript

添加 --dry-run，即可预览各个片段以及推断出的类型、标题和标签，而不会写入数据库。在提交较长文件前很有用。

memory-kernel ingest --scope project.alpha --file notes.txt --dry-run
memory-kernel ingest --scope project.alpha --text "..." --dry-run --json

添加 --interactive，即可进入引导流程：系统会提示你输入范围、来源、标签和文本，然后显示预览，并在保存前征求确认。适合初次使用的用户，也适合在终端临时记录内容、又不想记住各个标志名称的情况。

memory-kernel ingest --interactive

search

如果你想针对某个查询查找少量相关的精确记忆，请使用 search。

memory-kernel search "context budget"

context

如果你想为 Agent 提示词生成精简的上下文包，请使用 context。

memory-kernel context "How do we keep memory cheap?" --budget-chars 700

wake-up

如果你想在任务开始前获取一组简短的“热记忆”，请使用 wake-up。

memory-kernel wake-up --budget-chars 500

stats

如果你想查看数据库大小以及原生加速器是否已启用，请使用 stats。

memory-kernel stats
memory-kernel stats --since 7d
memory-kernel stats --since 2026-04-01

--since 会添加近期活动计数（截止时间之后创建和更新的记录数），以及该时间段内按类型细分的统计。可使用 7d 这样的相对形式，也可使用 ISO 日期。

list

使用 list 浏览近期记忆（按最近更新时间排序），并可选择筛选条件。

memory-kernel list
memory-kernel list --scope project.alpha --limit 50
memory-kernel list --kind decision --tags rust memory
memory-kernel list --json

默认限制为 20 条。输出会显示 id、kind/scope、title 和时间戳，你可以将这些 ID 传给 show／update／delete。

show

如果你有记忆 ID（由 search、remember --json 或 export 输出），并想查看完整记录，请使用 show。

memory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b
memory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b --json

update

使用 update 修改现有记忆的特定字段，无需重新导入整个数据库。

memory-kernel update --id 9f1e... --title "Renamed memory" --importance 0.95
memory-kernel update --id 9f1e... --tags rust memory acceleration
memory-kernel update --id 9f1e... --tags

只有你传入的字段会发生更改。不带值传入 --tags 可清除标签。传入 --kind、--importance 或 --certainty 可修改受验证约束的字段。

delete

使用 delete 删除误存或已不再适用的记忆。

memory-kernel delete --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b

如果 ID 不存在，该命令会以非零状态码退出；如果要编写相关脚本，请将其包装在 shell 逻辑中。

forget / restore

delete 会永久删除记忆。如果你只想将记忆从召回中移除，但为安全起见予以保留，请使用 forget 进行软归档。归档的记忆不会出现在 search、context、wake-up 和 list 的结果中，但数据仍会保留，使用 restore 即可将其恢复。

memory-kernel forget --id 9f1e...
memory-kernel restore --id 9f1e...
memory-kernel list --include-archived   # see archived/superseded memories

使用 remember／ingest 重新保存同一条记忆，也会自动将其恢复。

revise

当一条新记忆取代旧记忆时，使用 revise 记录这一关系：旧记忆会被标记为已取代（不再参与召回，但会保留在历史记录中，并指向替代它的记忆）。

memory-kernel revise --id <new-id> --supersedes <old-id>

这样可以让记忆自我整理：过时的决定会随着新决定的出现而逐渐淡出召回，避免矛盾的信息不断堆积。

decay

decay 会应用遗忘曲线：自动归档年代久远、很少被召回且价值较低的记忆，让存储和召回内容随着时间推移保持精简。每条记忆都有一个保留分数，该分数根据其重要性、被召回的频率（强化程度）以及上次被查看至今的时间（时间衰减）计算得出。

memory-kernel decay --dry-run          # preview what would fade
memory-kernel decay                    # apply (archives, recoverable)
memory-kernel decay --min-age-days 60 --max-access 0 --scope project.alpha

只有 note 和 fact 记忆符合条件；decision、constraint、task 和 preference 永远不会衰减。归档采用可恢复的软归档方式，因此仍可通过 restore 和 list --include-archived 找到逐渐淡出的记忆。这正是本项目理念的核心：将预算用在重要的事情上，让琐事逐渐淡去。

completion

使用 completion 为 memory-kernel 打印 shell 补全脚本。该脚本根据当前解析器动态生成，因此会随着新增命令保持同步。

memory-kernel completion powershell | Out-File -Encoding utf8 $PROFILE.CurrentUserAllHosts -Append
memory-kernel completion bash > ~/.local/share/bash-completion/completions/memory-kernel

安装后，输入 memory-kernel <Tab><Tab> 可显示所有子命令；输入 memory-kernel remember --<Tab> 可列出该命令的标志；输入 memory-kernel remember --kind <Tab> 可循环切换有效的 kind 值。

verify

使用 verify 检查数据库的内部一致性：架构版本是否为当前版本、派生列（stems_text、fingerprint）是否与源内容匹配，以及 FTS5 索引的行数是否与记忆表一致。

memory-kernel verify
memory-kernel verify --repair
memory-kernel verify --repair --json

如果不带 --repair，数据库状态正常时退出码为 0，发现问题时为 1。如果带上 --repair，则会就地重新计算不匹配项；如果 FTS 索引的行数发生偏差，则会重建该索引。所有问题都修复后，退出码为 0。

适用于从手动备份恢复后、使用原始 SQL 编辑数据库后，或在 CI 中定期进行健全性检查时。

export

使用 export 进行备份、迁移或检查。

memory-kernel export --format json --output exports\memory.json
memory-kernel export --scope project.alpha --format jsonl --output exports\project-alpha.jsonl

import

使用 import 恢复先前导出的数据。

memory-kernel import --file exports\memory.json
memory-kernel import --file exports\project-alpha.jsonl

对于相同的导出记录，import 是幂等的，因为它会根据记忆 id 执行插入或更新。

与大模型搭配使用（MCP）

Memory Kernel 提供了一个 MCP 服务，让大模型可以在会话期间自行保存和回忆记忆。它通过 stdio 与 Claude Desktop、Claude Code、Cursor 以及任何其他 MCP 客户端配合使用。

安装 MCP 附加组件：

pip install "amormorri-memory-kernel[mcp]"

直接运行，检查是否能正常启动：

memory-kernel-mcp --db .memory-kernel\memory.db
# or via the main CLI:
memory-kernel serve-mcp --db-path .memory-kernel\memory.db

然后在客户端中注册该服务。对于 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "memory-kernel": {
      "command": "memory-kernel-mcp",
      "env": { "MEMORY_KERNEL_DB": "C:\\Users\\you\\.memory-kernel\\memory.db" }
    }
  }
}

对于 Claude Code / Cursor（项目根目录中的 .mcp.json）：

{
  "mcpServers": {
    "memory-kernel": {
      "command": "memory-kernel-mcp",
      "args": ["--db", "${workspaceFolder}/.memory-kernel/memory.db"]
    }
  }
}

该服务提供七个工具：

工具	用途	只读
memory_remember	保存一条精确的记忆	否（去重合并，不具破坏性）
memory_ingest	将原始文本拆分为结构化记忆	否
memory_forget	软归档一条记忆（可恢复）	否（可撤销）
memory_search	查找相关记忆（支持乌克兰语词形转换）	是
memory_build_context	为提示词生成受预算限制的上下文包	是
memory_wake_up	为会话启动生成热记忆包	是
memory_list	浏览近期记忆	是
memory_stats	存储统计信息	是

之所以提供 memory_forget，是因为它可撤销——Agent 可以让过时的记忆逐渐淡去，而人类可以通过 CLI 将其 restore。真正具有破坏性的编辑（delete、update、revise）则刻意不通过 MCP 提供：Agent 可以添加、回忆和软删除记忆，但只有你能永久改写或移除记忆。

工具采用扁平参数，因此模型可以直接看到 scope、kind、title 等参数。随时运行 python scripts/mcp_smoke.py，验证整个协议往返过程；要查看可在真实模型上运行的手动测试脚本，请参阅 docs/REAL_AI_TEST.md。

工作原理

核心思路很简单：

1. 在本地存储原文。
2. 使用 SQLite 和 FTS5 进行低成本搜索。
3. 以确定性而非模糊的方式对结果排序。
4. 返回一个有严格字符预算限制的小型上下文包。

这就是 Memory Kernel 如何同时减少模糊性和开销。

数据流

flowchart TD
    A[Raw input: note, transcript, command] --> B{Entry mode}
    B -->|remember| C[One validated memory]
    B -->|ingest| D[Split into memory candidates]
    D --> E[Infer kind, title, summary, tags, importance, certainty]
    E --> F[Duplicate-aware upsert]
    C --> F
    F --> G[(SQLite + FTS5)]
    G --> H[Search candidates]
    H --> I[Deterministic ranking]
    I --> J[Top memories]
    J --> K[Context pack with hard size limit]
    K --> L[LLM or AI agent]

组件图

flowchart LR
    U[User or Agent] --> CLI[CLI or Python API]
    CLI --> STORE[MemoryStore]
    STORE --> DB[(SQLite + FTS5)]
    STORE --> ACCEL[Optional Rust accelerator]
    STORE --> PACK[Context pack builder]
    PACK --> MODEL[LLM]

记忆记录架构

MemoryRecord
|- scope
|- kind
|- title
|- summary
|- content
|- tags
|- source
|- importance
|- certainty
|- access_count
|- created_at
|- updated_at
\- last_accessed_at

更精简的上下文包

构建 context 或 wake-up 包时，Memory Kernel 会跳过内容与已纳入记忆高度重叠的记忆（令牌重叠度超过阈值）。在相同的字符预算下，这样生成的上下文包就能包含更多不同的信息、减少重复，从而直接降低交给模型的冗余上下文。可通过 dedup_threshold 按次调用调整或禁用（设为 1.0 即可禁用）。

乌克兰语词形转换

搜索通过两个层级支持乌克兰语形态变化：

1. 对查询进行后缀词干提取：将每个词项扩展为较短的词干（вирішили → виріш*）。这样可以找到 вирішили、вирішення、вирішує、вирішена 等所有共享相同前缀的词形。
2. 对已存储内容进行深度词干提取（去除后缀和前缀）：结果存储在 FTS5 索引的独立 stems_text 列中。查询也会对照深度词干进行精确匹配（stems_text:ріш）。这可以跨不同前缀进行匹配，因此搜索 рішення 也能找到 вирішили 和 невирішене——它们都会归并为相同的 ріш 词干。

已存储的标题、摘要、内容和标签保持原样，因此指纹、去重、排序和导出仍是确定性的。只有 FTS5 索引会新增一个派生的 stems_text 列。

禁用方式：

$env:MEMORY_KERNEL_DISABLE_STEMMER=1

禁用只会影响查询侧。写入时仍会填充 stems_text，因此重新启用环境变量后无需重建。

为什么它始终轻量

Memory Kernel 有意保持小巧：

• 使用 SQLite + FTS5，而不是强制要求使用向量数据库
• 使用确定性排序，而不是始终启用模糊检索
• 支持识别重复内容的更新，而不是让记忆无止境增长
• 设置严格的上下文预算，而不是倾倒大量提示词
• 仅在确实有帮助的地方可选使用 Rust 加速

对于嵌入式 Python 用法，MemoryStore 会保留一个长期使用的 SQLite 连接，以提高吞吐量。建议使用 with MemoryStore(...) as store:，或在使用完毕后调用 store.close()。

适用人群

如果你希望实现以下目标，那么它很适合你：

• 在自己的设备上使用本地优先的记忆
• 查看清晰、可检查的记录
• 使用小巧、可预测的检索
• 轻松导出和恢复

如果你希望实现以下目标，那么它可能不太适合你：

• 使用完全托管的托管平台
• 无需进行任何本地设置
• 无需审核即可全自动清理杂乱笔记

项目状态

当前阶段：可用的 Alpha 版本。

已实现：

• 包布局
• CLI
• 测试
• 导出和导入
• 可选的 Rust 加速器
• 不依赖 Rust 的 Python 回退实现

仍在进行：

• 面向主流平台的预构建 wheel
• 更简单的引导式导入流程
• 让非技术用户更轻松地开始使用

原生加速器

Python 实现是稳定的默认选项。

如果你希望降低导入和启发式热点路径的开销，可以构建可选的 Rust 模块：

.\scripts\build_native.ps1

之后，memory-kernel stats 会显示 accelerator: rust 是否已启用。

你可以使用以下命令对当前热点路径进行基准测试：

python .\scripts\benchmark_ingest.py
python .\scripts\benchmark_upsert.py

可通过以下命令使用实验性的原生排序进行性能分析：

$env:MEMORY_KERNEL_EXPERIMENTAL_NATIVE_RANK=1

许可证

Apache License 2.0（参见 LICENSE 和 NOTICE）。截至 0.3.1（含）的版本均以 Unlicense 发布，并继续适用这些条款；之后的所有版本均采用 Apache-2.0 许可证。贡献者需签署 DCO——请参见 CONTRIBUTING.md。

反馈

问题跟踪器： https://github.com/Artem362/memory-kernel/issues

问题模板选择器： https://github.com/Artem362/memory-kernel/issues/new/choose

此外，首次运行反馈模板位于： .github/ISSUE_TEMPLATE/first-run-feedback.yml

最有用的早期反馈包含：

• 你的安装来源
• 你的操作系统和 Python 版本
• 你运行的确切命令
• 你的预期结果
• 实际发生的情况