跳到主要内容
AI教程

使用 loci 构建持久化、类型化的 AI 智能体记忆

了解如何安装 loci、存储和检索持久化用户事实、将排序后的记忆注入提示词，并在 MCP、Hermes 和直接 Python 集成之间进行选择。

AI我搜编辑部阅读约 8 分钟
使用 loci 构建持久化、类型化的 AI 智能体记忆

什么是 loci？

loci 是面向 AI 代理的类型化长期记忆层。它从对话中提取持久事实，将其存储在 SQLite 中，为日后召回进行排序，并移除不再有用的信息。

该项目基于这样一个理念：记忆既需要位置，也需要结构。loci 不会将每条已保存的陈述一视同仁，而是区分偏好、截止期限、目标、关系以及其他类型的信息，使它们能够遵循适当的生命周期。

loci 源自 Lima 在生产环境中使用的记忆系统，并经过重写，不再依赖任何特定的宿主应用。

记忆系统的工作方式

类型化记忆

每条记忆属于以下八个类别之一：

  • routine
  • study
  • preferences
  • finance
  • goals
  • relationships
  • constraints
  • ephemeral

记忆还具有四个重要性等级和一个状态生命周期。这种结构使系统能够区别处理长期偏好、临时截止期限和短暂事实。

两种提取路径

提取过程结合了两种机制。基于模型的提取器从对话中理解含义，而正则表达式启发式规则则检测明确支持的措辞。两者的结果会合并，并以模型输出为准。

当模型提供商不可用时，正则表达式路径仍可继续运行。模型调用、提供商 SDK 和 API 密钥都特意留给宿主应用处理，宿主应用可以注入 ModelExtractor。

过滤、排序与衰减

写入过滤器会阻止短暂情绪及类似的短期陈述成为永久的用户画像数据。例如，“今天很累” 可能在几小时内确实为真，但数月后就可能产生误导。

将记忆添加到模型上下文时，loci 会将结果限制为十二条事实。它会先按重要性排序，然后考虑截止期限的临近程度和近期性。此上限可防止提示词无限增长。

每日整合和衰减机制会让存储保持有效：

  • 合并完全重复的记忆。
  • 未经确认的猜测最终会过期。
  • 短暂事实的存活时间为 24 小时。
  • 已完成的目标在 90 天后过期。

选择集成方式

loci 提供一个共享核心和两个适配器。

MCP 服务器

MCP 适配器适用于任何兼容的 MCP 客户端。它提供三个工具：remember、recall 和 forget。

MCP 基于请求与响应，因此没有自动的回合结束钩子。代理必须主动调用 remember。记忆可以按请求召回并注入上下文。

Hermes 插件

Hermes 适配器提供相同的三个工具，同时还支持自动提取，并在每次调用前注入上下文。这是因为 Hermes 提供了 post_llm_call 钩子，可以在模型响应后检查一次交互。

直接集成 Python

当你控制代理循环，并希望自行决定何时进行提取、持久化、召回和上下文注入时，可以直接使用核心库。

安装与设置

安装核心包

pip install mowave-loci

安装 MCP 支持

pip install mowave-loci[mcp]

安装 MCP extra 后，将 loci 添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "loci": {
      "command": "python",
      "args": ["-m", "loci.adapters.mcp_server.server"]
    }
  }
}

重启或重新加载客户端，使其发现 remember、recall 和 forget 工具。

安装 Hermes 插件

hermes plugins install <you>/loci
hermes plugins enable loci

将 <you>/loci 替换为适用于你的安装方式的插件仓库或源。

配置存储

默认情况下，loci 会将记忆存储在 ~/.loci/memory.db 的 SQLite 数据库中。设置 LOCI_DB 环境变量即可使用其他文件。

export LOCI_DB=/path/to/memory.db

无需单独的数据库服务器。

在 Python 中的基本用法

核心工作流是创建存储，提取候选记忆，过滤这些记忆，保存接受的记忆，并将活跃记忆添加到系统提示词中。

from loci import Store, extract, should_persist, context_block

store = Store()

for memory in extract(
    "eu prefiro respostas curtas",
    assistant_text=reply,
):
    if should_persist(memory):
        store.upsert(memory)

system_prompt += "\n\n" + context_block(store.active())

在此示例中，reply 表示与该次交互关联的助手文本。葡萄牙语用户消息表示用户偏好简短回答。

  1. Store() 打开已配置的 SQLite 记忆存储。
  2. extract(...) 从交互中生成候选记忆。
  3. should_persist(memory) 应用写入过滤器。
  4. store.upsert(memory) 插入或更新已接受的记忆。
  5. store.active() 获取活跃记忆。
  6. context_block(...) 将这些记忆格式化，以便注入提示词。

使用 MCP 工具

配置 MCP 服务器后，已连接的代理可以使用三种操作：

  • remember：有意保存应长期保留的事实。
  • recall：在相关时检索已存储的信息。
  • forget：删除不应继续保留的信息。

由于 MCP 适配器不会自动提取记忆，因此代理指令应明确说明代理何时需要调用 remember。不要假设每次完成的对话轮次都会被检查并保存。

高级集成技巧

将提供商逻辑置于核心之外

loci 核心仅使用 Python 标准库。模型调用、API 密钥和提供商 SDK 由你的应用负责。如果语义提取需要模型，请从宿主注入 ModelExtractor，而不是向核心添加提供商依赖。

从宿主运行生命周期任务

loci 定义记忆结构、整合和衰减行为，但不会安排每日任务。使用宿主的 cron、s6、systemd 或等效调度器来触发每日任务。

保留上下文上限

避免将整个数据库添加到每个提示中，从而绕过排序后的上下文块。十二条事实的上限用于控制上下文增长，同时优先保留重要、及时且近期的信息。

使用适当的适配器

  • 当需要在不同 MCP 客户端之间保持可移植性，且可以接受显式记忆操作时，选择 MCP。
  • 当希望在模型调用后自动提取记忆，并在每次调用前注入记忆时，选择 Hermes。
  • 当应用负责代理循环，并需要精确控制持久化和提示构建时，选择 直接 Python API。

由宿主负责传输和会话

代理循环、工具分发、会话、传输和身份验证不属于核心的职责范围。Hermes、OpenClaw 或 Claude Code 等宿主负责管理外围运行时，而适配器负责处理宿主特定的传输和身份验证。

运行测试套件

pytest -q

项目包含 92 个测试，这些测试会针对临时文件中的真实 SQLite 存储运行。存储本身未被模拟，这有助于验证实际部署所使用的同一存储技术上的行为。

结论

loci 为 AI 代理提供了紧凑、类型化且持久的记忆层，无需单独的服务器。其共享核心负责记忆结构和生命周期，而 MCP、Hermes 或你自己的 Python 代理则提供外围运行时。请从适合宿主的适配器开始，明确提取和调度职责，并使用排序后的上下文注入，防止记忆压垮提示。