为LLM应用与自主代理提供持久化、时序、可治理的记忆引擎

方案简介

LongMemory 是一个面向 LLM 应用与自主代理的认知记忆引擎。它不是简单的 RAG，也不是向量数据库，而是提供持久化、带时序、可治理的记忆能力，本地优先、可自托管。

传统记忆方案本质是检索管道：切分文本、嵌入、返回最近向量，这无法回答某事实在特定时间是否为真、新事实是否取代旧事实、哪个来源权威、谁能看到、为何该结果应进入上下文。LongMemory 直接建模这些问题：记录时间与有效时间分离；内容、向量、哈希与来源在召回中不可被改写；类型化关系图参与召回与解释；按项目/租户/用户/团队/角色/代理/任务/框架范围实施治理；支持确定性衰减、强化、整合、压缩与再整合的生命周期；召回受相关性、矛盾、接地、权限与 token 成本约束。

模型保持无状态，应用不再失忆。适合需要长期记忆、审计与治理的代理应用开发者。

亮点与能力

• Hydrograph 记忆基底：不可变节点、可执行边、世界、实体、切面与痕迹
• 时序推理：时间点真值、事件排序、取代与陈旧证据控制
• 多语言记忆：脚本检测、语码转换、音译与跨语言嵌入
• 项目记忆：架构、决策、任务、约定、失败、交接与代码影响
• 受治理资产：Chat Memory、Skills、LLM-Wiki、CodeGraph，带生命周期与 ACL 策略
• 会话搬运：支持 Claude Code、Codex、OpenCode、Gemini CLI、Copilot Chat、Cline 等日志
• 连接器：仓库、本地文件、Markdown、网页、订阅源、云文档与提供商 API
• 多召回模式：strict/historical/associative/world_grounded
• 可审计基准：LongMemEval、LoCoMo、BEAM、检索质量、时序行为与延迟

组成与分工

• LongMemory：核心 TypeScript 记忆引擎，统一通过 npm、CLI、HTTP、MCP、dashboard 与 VS Code 暴露
• SQLite：本地持久化存储，保存节点、世界、实体、边、时序历史、接地与生命周期状态
• Docker / Docker Compose：以服务方式运行 API、MCP 与 dashboard，数据卷持久化
• MCP：向代理宿主暴露 13 个高级治理工具、可读资源与代理工作流提示
• 嵌入提供商（OpenAI 兼容 API、Gemini、AWS Bedrock、Ollama 等）：提供向量化能力
• n8n / CrewAI / LangGraph / Dify 等：作为代理框架集成宿主使用记忆工具

前置要求

• Node.js 环境（使用 npm 或 pnpm，源码运行需 corepack）
• 无需外部数据库即可内存运行；持久化使用 SQLite
• 可选：Docker 用于服务化部署

安装为库：
bash
npm install longmemory

安装 CLI：
bash
npm install --global longmemory

从源码运行：
bash
git clone https://github.com/CaviraOSS/LongMemory.git
cd LongMemory
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm start

实施步骤

1. 作为库快速上手

bash
npm install longmemory

ts
import { createMemory } from 'longmemory';

const memory = await createMemory();
await memory.ingest({
user_id: 'alice',
text: 'I prefer TypeScript for backend services',
});

const result = await memory.recall({
text: 'What language does Alice prefer?',
mode: 'strict',
});

console.log(result);
await memory.close();

2. 使用 SQLite 持久化

ts
const memory = await createMemory({
store: 'sqlite',
db_path: './longmemory.db',
tenant_id: 'acme',
user_id: 'alice',
});

重新打开同一数据库即可恢复节点、世界、实体、边、时序历史、接地与生命周期状态。

3. 以服务方式运行（Docker）

bash
docker run --rm \
-p 7331:7331 \
-v longmemory-data:/data \
-e LONGMEMORY_API_KEY=change-me \
ghcr.io/caviraoss/longmemory:latest

或使用 Docker Compose：

bash
cp .env.example .env
docker compose up --build -d longmemory

包含 dashboard：

bash
docker compose --profile ui up --build -d

4. 启用 MCP 供代理使用

本地 stdio MCP：

bash
longmemory mcp --db .longmemory/project.db --project current

带认证的 Streamable HTTP MCP：

bash
LONGMEMORY_API_KEY=change-me longmemory serve --mcp-http

使用与配置要点

• API 默认监听 http://127.0.0.1:7331，Dashboard 在 http://127.0.0.1:3000，健康检查在 http://127.0.0.1:7331/health
• CLI 示例：longmemory recall "current project priorities" --mode associative
• 四种召回模式：strict 应用时序、矛盾、契约、置信与接地门控；historical 保留被取代的真值并可用 valid_time 查询历史时间点；associative 跟随语义、词法、实体、激活与图信号；world_grounded 要求当前外部证据
• 项目记忆示例：createProjectMemory 配置 tenant/organization/project 后用 ingestProjectEvent 写入决策事件
• 代理集成：Claude Code 插件、Codex/ChatGPT 桌面插件、Gemini CLI 扩展、n8n 社区节点、Cline/Continue/LibreChat 配置包、Dify/Flowise 原生 MCP 等

注意事项与常见问题

• 工具参数无法覆盖服务器绑定的运行时身份，治理范围在服务端强制执行
• Docker 示例中的 LONGMEMORY_API_KEY=change-me 需替换为真实密钥
• 内存使用不需要服务或外部数据库，但重启后数据不保留，持久化需配置 SQLite store
• 召回结果受相关性、矛盾、接地、权限与 token 成本约束，可能不返回全部相关记忆

优缺点

• ✓ 本地优先可自托管
• ✓ 时序真值与不可变记忆
• ✕ README为英文文档门槛
• ✕ 默认需API密钥配置

出处

本方案挖掘自开源项目 CaviraOSS/LongMemory，方案内容与实施命令均来自其 README 原文。