limbicdb

v5.0.2

Published

a month ago

Production-grade AI memory infrastructure �?observable, explainable, secure, and LangChain/LlamaIndex ready

0High
0Medium
0Low

ai agent memory langchain llamaindex vector-store observability opentelemetry sqlite debuggable explainable ebbinghaus ai-memory agent-memory

LimbicDB

生产级 AI 记忆基础设施 — 可观测、可解释、安全，并已适配 LangChain / LlamaIndex。— v5.0.2 / python-v0.1.0

English | 简体中文

项目成熟度

状态：Beta — 核心 API 和存储格式已稳定。LimbicDB 拥有 290+ 自动化测试，并已验证 TypeScript 与 Python 的跨语言互操作性。但该项目由个人维护，尚未经过大规模生产环境的检验。
推荐用于：个人智能体、本地工具、研究、原型开发、小团队应用。 需额外测试后再用于：企业记忆层、多用户生产系统、高并发分布式同步。
详见 docs/planning/BETA-ENTRANCE-CRITERIA.md 完整诚信报告。

LimbicDB 是什么？

LimbicDB 是一个 本地优先的结构化 AI 智能体记忆层。它解决了大多数 AI 记忆系统忽略的三个核心问题：

| 问题 | 其他方案 | LimbicDB | |---|---|---| | 不透明 | 记忆是黑盒 | 每次检索决策均可数学化解释 | | 不安全 | 任何智能体都可以读写任何记忆 | Ed25519 签名同步事件 + 命名空间物理隔离 | | 碎片化 | 每个框架各有自己的记忆系统 | LangChain & LlamaIndex 零依赖直接适配 |

系统架构

graph TD
    A["你的智能体 / LLM 逻辑"] -->|"remember() / recall()"| B["LimbicDB 核心"]
    B --> C1[("SQLite\n(.limbic 文件)\n边缘 / 本地")]
    B --> C2[("PostgreSQL\n+ pgvector\n云端 / 企业")]
    B --> D["ExplainEngine\n(认知评分分解)"]
    B --> E["TelemetryProvider\n(兼容 OpenTelemetry)"]
    B --> F["MigrationRunner\n(自动 Schema 版本管理)"]

    A2["LangChain Chain"] -->|"LimbicChatMemory\nLimbicVectorStore"| B
    A3["LlamaIndex Pipeline"] -->|"LimbicReader\nLimbicVectorIndex"| B

    B -->|"wrapWithSigning()"| G["P2P 同步\n(Ed25519 签名)"]
    G --> H["对等节点 A"]
    G --> I["对等节点 B"]

核心特性

🔍 可观测记忆（里程碑 1）

每次检索都有数学化解释。 再也不用猜测为什么记忆系统选错了记忆。

import { open } from 'limbicdb';

const db = open('./agent.limbic');

await db.remember('用户喜欢深色模式');
await db.remember('用户讨厌选项太多的复杂界面');

const result = await db.recall('UI 偏好', { explain: true });

// result.memories[0]._explanation 示例：
// {
//   score: 0.87,
//   breakdown: {
//     semantic:   { score: 0.71, weight: 0.50 },
//     decay:      { score: 0.92, weight: 0.30 },  // 艾宾浩斯遗忘曲线
//     repetition: { score: 1.00, weight: 0.15 },  // Pimsleur/ACT-R 重复加权
//     recency:    { score: 0.85, weight: 0.05 },
//   }
// }

兼容 OpenTelemetry 的追踪链路，未配置时零开销：

import { open, ConsoleTelemetryProvider } from 'limbicdb';

const db = open({
  path: './agent.limbic',
  telemetry: new ConsoleTelemetryProvider(),  // 替换为你的 OTEL tracer
});

🔒 安全多智能体记忆（里程碑 2）

命名空间隔离 — 每个智能体拥有独立的物理 SQLite 文件，通过命名空间名的 SHA-256 哈希派生，完全无交叉污染。

const agentAlice = open({ path: './shared.limbic', namespace: 'agent-alice' });
const agentBob   = open({ path: './shared.limbic', namespace: 'agent-bob' });

await agentAlice.remember('Alice 知道这个秘密');
const results = await agentBob.recall('秘密');
// results.memories.length === 0  ← Bob 无法看到 Alice 的记忆

Ed25519 载荷签名 — P2P 同步中每条事件均经过加密签名和验证：

import { open, wrapWithSigning, generateSyncKeyPair } from 'limbicdb';
import { LocalP2PSyncProvider } from 'limbicdb';

const { privateKey, publicKey } = generateSyncKeyPair();

const db = open({
  path: './agent.limbic',
  sync: wrapWithSigning(new LocalP2PSyncProvider('./sync-hub'), {
    privateKey,
    trustedPeers: { 'peer-A': peerAPublicKey },
  }),
});

🔗 生态系统集成（里程碑 3）

零额外依赖。 鸭子类型适配器 — 仅在需要时安装 langchain 或 llamaindex。

LangChain

import { open } from 'limbicdb';
import { LimbicChatMemory, LimbicVectorStore } from 'limbicdb/integrations/langchain';
import { ConversationChain } from 'langchain/chains';
import { ChatOpenAI } from 'langchain/chat_models/openai';

const db = open('./agent.limbic');

// 持久化对话记忆 — 进程重启后依然有效
const chain = new ConversationChain({
  llm: new ChatOpenAI(),
  memory: new LimbicChatMemory({ db, sessionId: 'user-session-42' }),
});

// RAG 向量存储
const store = new LimbicVectorStore({ db });
await store.addDocuments([{ pageContent: 'LimbicDB 文档...', metadata: {} }]);
const docs = await store.similaritySearch('记忆架构', 5);

LlamaIndex

import { open } from 'limbicdb';
import { LimbicVectorIndex } from 'limbicdb/integrations/llamaindex';

const db = open('./agent.limbic');
const index = new LimbicVectorIndex({ db });

await index.insert('LimbicDB 让 AI 记忆变得可观测');

const engine = index.asQueryEngine();
const response = await engine.query('LimbicDB 是如何工作的？');

🛠️ Schema 自动迁移（里程碑 3）

每次 open() 时 Schema 自动升级，零手动操作。

import { MigrationRunner, MIGRATIONS } from 'limbicdb/migrations';

const runner = new MigrationRunner(sqliteDb, MIGRATIONS);
const applied = await runner.getAppliedMigrations();
// [{ id: 1, name: 'add_meta_column', applied_at: '...', duration_ms: 2 }, ...]

🐘 PostgreSQL 后端（里程碑 4）

云端/企业级存储，支持连接池和 pgvector 原生向量搜索。

# 安装 pg 驱动（peerDependency — 仅在使用 PostgreSQL 时需要）
npm install limbicdb pg

# 使用 Docker 快速启动（已包含 pgvector）
docker run -d --name pgvector -e POSTGRES_PASSWORD=mypassword -p 5432:5432 pgvector/pgvector:pg16

import { PostgresStore } from 'limbicdb/adapters/postgres';

const store = new PostgresStore({
  host: 'localhost',
  port: 5432,
  user: 'postgres',
  password: 'mypassword',
  database: 'postgres',
  schema: 'my_agent',          // 自动创建；隔离生产数据
  embeddingDimensions: 1536,    // 匹配你的嵌入模型
});

await store.init();  // 自动创建 schema + 所有表

// 底层存储 API（与 SQLiteStore 接口相同）
const now = Date.now();
await store.saveMemory({
  id: 'mem-1',
  content: '用户偏好深色模式',
  kind: 'preference',
  tags: ['ui'],
  meta: {},
  strength: 0.8,
  baseStrength: 0.8,
  createdAt: now,
  accessedAt: now,
  accessCount: 0,
  scope: 'project',
});

const results = await store.searchMemories({ query: 'dark mode', limit: 5 });
console.log(results[0].content); // "用户偏好深色模式"

// 向量相似度搜索（需要 pgvector 扩展和嵌入向量）
const similar = await store.searchMemoriesByVector(myEmbedding, 10);

await store.close();

SQLite vs PostgreSQL：使用 SQLiteStorageAdapter 进行嵌入式、本地优先、离线可用的部署。当需要多进程访问、水平扩展或共享云存储时，使用 PostgresStore。

快速开始

CLI

# 全局安装
npm install -g limbicdb

# 存储记忆
limbic remember "用户偏好 TypeScript 而非 Python"
limbic remember "会议定于周五下午 3 点"

# 智能检索
limbic recall "编程语言偏好"

# 检测矛盾
limbic conflicts

# 时间线视图
limbic timeline

Node.js API

npm install limbicdb

import { open } from 'limbicdb';

const db = open('./agent.limbic');

await db.remember('用户不喜欢冗长的错误信息');

const { memories, meta } = await db.recall('错误处理偏好');
// meta.executedMode: 'keyword' | 'semantic' | 'hybrid'
// meta.fallback: 若请求语义搜索但未配置嵌入器则为 true

await db.close();

功能矩阵

| 功能 | 状态 | |---|---| | 关键词检索（BM25 风格） | ✅ 稳定 | | 语义检索（余弦相似度） | ✅ 稳定（需嵌入器） | | 混合检索 | ✅ 稳定 | | recall({ explain: true }) — 评分分解 | ✅ 稳定 | | 兼容 OpenTelemetry 的遥测 | ✅ 稳定 | | 命名空间隔离（SHA-256 派生） | ✅ 稳定 | | Ed25519 签名 P2P 同步 | ✅ 稳定 | | Schema 迁移引擎 | ✅ 稳定 | | LangChain 适配器（ChatMemory + VectorStore） | ✅ 稳定 | | LlamaIndex 适配器（Reader + VectorIndex） | ✅ 稳定 | | 冲突检测 | ✅ 稳定 | | SQLite WAL + busy_timeout 并发优化 | ✅ 稳定 | | MCP 服务器（Claude Desktop / Cursor） | ✅ 稳定 | | PostgreSQL 适配器（连接池 + pgvector） | ✅ 稳定 (v5.0.2) | | Python SDK | ✅ 稳定 (v0.1.0) |

安装

# 项目依赖
npm install limbicdb

# 全局 CLI
npm install -g limbicdb

# 通过 npx 快速体验
npx limbicdb@latest remember "我的第一条记忆"

Windows 用户：请参阅 docs/WINDOWS.md。

Python SDK

LimbicDB 提供原生 Python SDK，与 TypeScript 核心 功能完全对等。相同的 .limbic 数据库文件可在两种语言间无缝使用。

from limbicdb import open as ldb_open

with ldb_open("./agent.limbic") as db:
    db.remember("用户偏好深色模式", tags=["ui", "preference"])
    result = db.recall("UI 偏好", explain=True)
    print(result.memories[0].content)
    print(f"score: {result.memories[0].explanation.score:.3f}")

LangChain (Python)

from limbicdb.integrations.langchain import LimbicChatMemory, LimbicVectorStore
from langchain.chains import ConversationChain

memory = LimbicChatMemory(path="./chat.limbic", session_id="user-42")
chain = ConversationChain(llm=your_llm, memory=memory)

LlamaIndex (Python)

from limbicdb.integrations.llamaindex import LimbicQueryEngine

engine = LimbicQueryEngine(path="./agent.limbic", top_k=5)
response = engine.query("用户的偏好是什么？")

完整文档：python/README.md

pip install limbicdb                           # 仅 SQLite
pip install "limbicdb[postgres]"               # + PostgreSQL + pgvector
pip install "limbicdb[langchain,llamaindex]"   # + 框架适配器

文档导航

| 文档 | 说明 | |---|---| | docs/INTEGRATION.md | 完整集成指南（LangChain、LlamaIndex、MCP） | | docs/ARCHITECTURE.md | 系统设计与内部实现 | | docs/TROUBLESHOOTING.md | 常见错误与解决方案 | | docs/ROADMAP.md | 功能路线图 | | docs/SECURITY.md | 安全策略与漏洞披露 | | docs/WINDOWS.md | Windows 安装指南 | | CONTRIBUTING.md | 参与贡献指南 | | CHANGELOG.md | 版本更新历史 |

已知局限

无嵌入器时的语义搜索：若未配置嵌入器，recall({ mode: 'semantic' }) 会自动降级为关键词搜索，result.meta.fallback 为 true。
查询上限：每次 recall() 最多返回 100 条结果。
P2P 同步：当前仅支持本地网络。在线中继服务在路线图中。
pgvector 索引：PostgresStore 默认使用顺序扫描（精确余弦距离）。对于超过 10,000 条记忆的数据集，建议手动创建 IVFFlat 索引：CREATE INDEX CONCURRENTLY ON limbic.memory_embeddings USING ivfflat (vector vector_cosine_ops) WITH (lists = 100);

贡献

欢迎提交 PR 和 Issue，请查阅 CONTRIBUTING.md。