LimbicDB

跨会话的本地 AI 可调试记忆库 • v3.0.0

English | 简体中文

🎯 什么是 LimbicDB？

LimbicDB 让矛盾的记忆可见。

大多数 AI 记忆系统会静默地扁平化记忆矛盾，而 LimbicDB 会将它们主动暴露出来。它不是将记忆视为黑盒，而是让你清楚地看到：

• ✅ 准确记住了什么
• ✅ 什么数据响应了查询
• ✅ 在哪里发生了记忆冲突
• ✅ 为什么检索系统做出了这样的判断

痛点：AI 智能体（如 OpenClaw, Claude Code, Codex, ChatGPT）在开启新会话时会失去先前的上下文，导致记忆碎片化。

解法：LimbicDB 是一个本地优先的、支持无中心去中心化 P2P 同步的、跨平台运行的记忆存储层。

✨ 核心特性 (v2.0)

• 混合逻辑时钟 (HLC)：实现 P2P 节点的最终一致性。彻底解决设备间时钟不同步（时钟漂移）造成的覆盖问题。
• 增量同步 (Delta Sync)：基于 SQLite 级别的私有 HLC 游标，同步时只拉取新增事件（TimelineEvents），将网络 I/O 复杂度从 O(N) 降为极致的 O(Δ)。
• 瘦长有效载荷 (Slim Payloads)：在 P2P 同步时自动抛弃沉重的 Float32Array 嵌入向量，接收端按需动态重算，使同步网络体积缩小上百倍。
• 无锁竞争保障 (Conflict Guard)：采用 busy_timeout 加固的 SQLite 并发优化，支持多 Agent 在高频并发场景下的读写安全。
• 事件循环防阻塞：在处理大规模记忆余弦相似度计算时引入分片（Chunked Yielding）保护 Node.js 主线程。
• 防越权执行：完全内置极严格的路径与 Payload 内容验证安全层。

🚀 快速开始

5 分钟上手体验：

# 1. 全局安装
npm install -g limbicdb

# 2. 存储两条潜在矛盾的记忆
limbicdb remember "用户更喜欢 TypeScript 而不是 Python"
limbicdb remember "用户讨厌调试 Python 代码"

# 3. 提供主题召回并带有冲突预测
limbicdb recall "编程语言"

# 4. 手动检测冲突
limbicdb conflicts

输出示例：

找到 2 条相关记忆

[检测到冲突]
- 用户更喜欢 TypeScript 而不是 Python
- 用户讨厌调试 Python 代码

📦 安装

Node/npm 环境 (Node.js 18+)

npm install -g limbicdb

Windows 用户配置支持

查看 WINDOWS.md 获取有关在 Windows 机器上编译原生 sqlite3 或 PowerShell 常见报错的设定指南。

🔧 核心 API 用法 (代码集成)

import { open } from 'limbicdb';

// 开启或创建数据库（默认：'./agent.limbic'）
const db = open('./agent.limbic');
await db.init();

// 存储记忆
await db.remember('用户更喜欢 TypeScript 而不是 Python');
await db.remember('用户讨厌调试 Python 代码');

// 召回内容
const result = await db.recall('编程语言');
console.log(result.memories);

// 提取潜在冲突图谱
const conflicts = await db.conflicts();
console.log(conflicts);

await db.close();

🛠 常见错误与排错指南

1. SQLITE_BUSY: database is locked

   • 原因：由于多个高并发的 AI 进程同时抢夺同一个本地 .limbic 文件的写锁导致。
   • 修复：LimbicDB 2.0 默认开启了 WAL 和 5000ms 的退避等待时长。如果依然报错，请检查您的磁盘 IO 性能是否到达瓶颈，或在初始化适配器时设置更长的等待。

2. LimbicError: Query cannot be whitespace only

   • 原因：试图在 recall() 中传入全是空格的废弃字符串如 ' '。
   • 修复：如果你的意图是想要查询列表的全部内容作为兜底，请直接传递绝对空字符串 db.recall('') 或不传参数 db.recall()。

3. LimbicError: Limit too large (1000), maximum is 100

   • 原因：单次 query 请求数量远超过了系统的最高保护上限（默认 max = 100 条）。
   • 修复：尝试收紧你的语义搜索词或标签过滤，又或者期待未来版本的分页系统。

4. LimbicError: Invalid file path

   • 原因：试图在 open() 数据库时使用可能会发生向上穿越的命令如 ../ 以及不合规的非法字符 |, ;。
   • 修复：请传入绝对路径或者清理过的标准化相对路径结构（例：./memories.limbic）。

📖 完整文档

| 文档 | 描述 | |-----|-------------| | INTEGRATION.md | AI 框架继承指南 | | ARCHITECTURE.md | 深入理解系统架构设计与原理 | | WINDOWS.md | Windows 特定装配指南 | | CONTRIBUTING.md | 贡献者必读 | | ROADMAP.md | 项目的未来开发路线图 |