SQLite Local AI Memory

🧠 SQLite 本地 AI 记忆

60 秒内，让你的 AI 助手拥有真正且永久的记忆。
无需按月订阅数据库，无需配置 Docker。只需在你的电脑上创建一个私密文件。

---

🛑 问题：为什么你的 AI 总是忘事？

如果你使用 AI 编码助手或聊天机器人（Claude Desktop、Cursor、Antigravity 等），你一定熟悉这种令人沮丧的体验：

1. 彻底失忆： 一旦关闭聊天窗口或开启新窗口，AI 就会忘记你是谁、你的技术栈、服务器 IP 和个人偏好。
2. 复制粘贴地狱： 你不得不一遍又一遍地重新解释相同的上下文，或者在每条提示词中粘贴巨大的文本文件。
3. 浪费金钱，聊天变慢： 每次提示词都塞入大量聊天记录，不仅会耗尽你的 token 预算、让你花真金白银，还会拖慢 AI 并使其容易混淆。

---

✨ 解决方案：一个文件里的私密大脑

sqlite-local-ai-memory 为你的 AI 助手提供一个永久且井然有序的大脑，安全地存储在你自己机器上的一个文件（memoria.db）中。

工作原理（通俗来说）：

• 📝 1. 活页备忘录（当前正在做的事）：
  记录你眼下关注的事项：进行中的任务、当天做出的决定以及后续步骤。明天打开一个新的聊天窗口时，AI 能立即知道你上次进行到哪里。
• 📚 2. 知识宝库（很少变化的事实）：
  存储具体知识，例如你的服务器配置、偏好的编码风格或家庭规则。当某些内容发生变化时（例如 IP 变更），它会更新当前事实，同时保留过去的审计记录。
• 🌙 3. 夜间清理 / AutoDream（让大脑保持整洁）：
  就像人脑会在睡眠期间整理思绪一样，当 AI 空闲时，它会悄悄回顾原始笔记、合并重复内容，并将相关事实整理成清晰的摘要。

---

⚡ 它有何独特之处？（“秘诀”）

与简单的聊天记录或把原始文本丢进黑箱的通用向量数据库不同，本系统采用了 6 种智能认知机制，让 AI 真正理解自己的记忆：

🌙 1. AutoDream 引擎（睡眠周期记忆清理）

AutoDream 不会让数千条聊天消息堆积成一团难以阅读的内容，而是像人脑在快速眼动睡眠期间那样发挥作用：

• 实时仪表板： 持续更新你今天正在构建内容的摘要。
• 永久知识： 自动将关键技术决策提炼成存储在 SQLite 中的精简事实。
• 未完成的工作永不丢失： 如果问题仍未解决或尚未结案，AutoDream 会为其安全归档，并添加 [UNRESOLVED_CASE] 标签，让 AI 几周后仍能继续调试，同时保留历史线索。

🐣 2. 未结案例孵化器与动态记忆窗口

当你需要数天时间排查复杂 Bug 时，正在调查的问题会安全地留在“孵化器”中。AI 最终整合案例时，不会只查看最后一条消息，而是会动态回溯到问题开始的确切时刻，为 AI 提供 100% 的历史上下文，以便编写永久修复方案。

⚖️ 3. 实时矛盾仲裁器（解决 AI 的“时间盲区”）

标准向量数据库完全无法感知时间。如果你告诉 AI “我的服务器 IP 是 .100”，两周后又说 “我们把服务器迁到了 .205”，普通的向量搜索会同时返回两者，导致 AI 产生幻觉。我们的语义仲裁器能即时检测状态矛盾：归档旧 IP，并实时将新 IP 设为当前值。

🚀 4. 100% 嵌入式存储（无需数据库服务器）

无需维护任何 Docker 容器。你不必安装 Chroma、运行带有 pgvector 的 PostgreSQL，也无需为 Pinecone 这类云数据库付费。所有功能——关键字索引和向量计算——都运行在一个本地 SQLite 文件中。检索当前笔记的耗时不到 0.1 毫秒，检索深层记忆的耗时不到 1.5 毫秒。

🛡️ 5. 双层噪声防火墙（闲聊拦截器）

保护数据库，避免杂乱信息增加 API 账单：

• 第 1 层（即时过滤，0 ms）： 立即丢弃随口寒暄（“你好”、“谢谢”、“听起来不错”）。
• 第 2 层（智能筛选，10 ms）： 使用小巧快速的模型，在调用更大的模型之前过滤掉非知识类对话。

🔎 6. 双重混合搜索（精确匹配与语义搜索相结合）

同时并行执行两种搜索：

• 精确关键词搜索（FTS5）： 在 < 0.5 ms 内查找精确的 IP 地址、变量名和错误代码。
• 语义向量搜索： 即使你使用完全不同的词语，也能找到相关概念。
  它通过倒数排名评分融合两种搜索结果，每次都能返回准确答案。

🛡️ 7. 离线时优雅降级（永不崩溃）

如果网络中断，或你未配置 API 密钥，系统也不会卡住或崩溃。它会优雅地退回裸机模式：你的 AI 仍可直接保存事实，并通过快速关键词搜索在本地搜索所有内容。

说明

降级说明： 即使没有 LLM，系统也能可靠运行；但要发挥真正的魔力和智能（AutoDream 整合、矛盾仲裁和语义向量搜索），需要连接 AI 模型（Google Gemini 或本地 Ollama）。

---

🔍 诚实透明：哪些在本地，哪些在云端？

我们始终如实说明 AI 记忆的运行方式：

• 你的数据与存储：100% 本地且私密。
  所有记忆、搜索索引和笔记都存储在你硬盘上的一个标准 SQLite 文件中。你无需为云端向量数据库付费（没有 Pinecone、Qdrant，也没有每月 SaaS 账单）。
• AI 推理层（3 种运行模式）：
  要整理笔记、检测矛盾并综合摘要，系统需要 AI 模型：
  • 🟢 模式 1：云端辅助（推荐／默认）： 使用轻量级 Google Gemini API。它能提供完美的 JSON 格式和深度推理能力，成本低至几乎可以忽略（数千条笔记每月不到 $0.50）。
  • 🟡 模式 2：通过 Ollama 实现 100% 离线运行（私有本地 AI）： 如果你希望完全离线运行，并且不向互联网发送任何数据，使用自己的硬件即可开箱即用，支持 Ollama（qwen2.5-coder + nomic-embed-text）。
  • 🔴 模式 3：纯裸机零 LLM（不推荐）： 如果你没有提供 API 密钥，且未安装 Ollama，系统会优雅地退回原始 SQLite FTS5 关键词存储模式，不会崩溃。警告：此模式并不理想。 没有 LLM，你将失去智能噪声过滤、矛盾仲裁、实体提取和 AutoDream 整合功能。此时系统只是一个快速关键词数据库，而非智能认知大脑。

---

🚀 快速入门：选择你的使用场景

功能	场景 1：MCP 服务（推荐）	场景 2：直接使用 Node.js 库
适用对象	90% 的用户： Cursor、Claude Desktop、VS Code	构建自定义 Agent、机器人或后端的开发者
设置时间	60 秒（无需编写代码）	5 分钟（使用标准的 npm install 导入）
工作方式	AI 客户端通过 stdio 工具与记忆交互	进程内原生执行，调用耗时不到 1 毫秒

---

🌟 场景 1：作为 MCP 工具使用（Cursor、Claude Desktop、VS Code）

1. 添加到 MCP 配置（claude_desktop_config.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "sqlite-memory": {
      "command": "npx",
      "args": ["-y", "sqlite-local-ai-memory"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

（更倾向于通过 Ollama 实现 100% 离线运行？将 GEMINI_API_KEY 替换为 ORCHESTRATOR_MODEL=ollama/qwen2.5:1.5b 和 OLLAMA_HOST=http://localhost:11434！）

2. 核心秘诀：将此提示词添加到你的 .cursorrules 或 CLAUDE.md

若要获得真正自主且持久的智能，请将这条指令粘贴到 AI 的规则中：

# 持久记忆协议
你可以使用 `sqlite-memory` MCP 服务。请遵循以下工作周期：

1. 🌅 会话开始：在你的第一个回合中，静默调用 `get_current_state`，加载当前工作看板和任务。
2. 🔎 记忆回顾：在回答你不记得某项技术决策或 Bug 之前，运行 `search_memory("keywords")`。
3. 🔨 里程碑学习：解决 Bug 或做出架构决策时，使用因果语法调用 `save_fact`：
   `[TYPE: BUGFIX|ARCHITECTURE] [CAUSE: <symptom>] -> [DECISION: <fix>] -> [EFFECT: <impact>]`
4. 🌙 会话收尾：结束会话或用户道别时，调用 `consolidate`，整合看板并清理已解决的问题。

---

💻 场景 2：作为直接使用的 Node.js / TypeScript 库

适用于构建独立 Agent、命令行工具或 Discord/WhatsApp 机器人的开发者：

npm install sqlite-local-ai-memory

import { MemoryEngine } from "sqlite-local-ai-memory";

const memory = new MemoryEngine({
  dbPath: "./agent_memory.db",
  userId: "developer_1"
});

// 1. Cold-start: Load active working state in < 0.1 ms
const dashboard = memory.getDashboard("developer_1");

// 2. Just-in-Time RAG: Search hybrid memory in < 1.5 ms
const hits = await memory.search("PostgreSQL port configuration");

// 3. Save atomic causal facts (anti-collision arbiter built-in)
await memory.saveFact("[BUGFIX] [CAUSE: Port conflict] -> [DECISION: Moved to 5433] -> [EFFECT: Resolved]");

// 4. Maintenance: Run AutoDream cognitive consolidation at close
const result = await memory.consolidate("developer_1", "BACKEND_PROJECT");

---

🛠️ AI 可使用的 5 个简单工具

通过 MCP 连接后，你的 AI 助手会自动获得以下 5 条命令：

命令	通俗来说，它的作用是什么
save_fact	“记住我的 PostgreSQL 运行在端口 5432。” 永久保存重要事实，并自动去重。
search_memory	“我们如何部署这个项目？” 通过混合关键词 + 语义搜索查询你的记忆库，耗时不到 2 ms。
get_current_state	“我之前在做什么？” 读取当前项目看板。（注意：需要至少运行一次 consolidate，AI 才能整合出初始看板。）
get_fact_lineage	“这个服务器 IP 随时间发生过怎样的变化？” 查看完整的历史审计记录，以及任何事实此前被取代的版本。
consolidate	“整理我的笔记并了解最新情况。” 回顾近期交互、合并重复内容、归档已解决的任务，并构建当前的 currentState 看板。

---

🔬 需要深入的技术规格？
如需深入了解 Int8 标量量化、倒数排名融合（RRF）、基准测试遥测数据和数据库 PRAGMA，请参阅完整的技术架构参考（README_TECHNICAL.md）。

---

💬 常见问题（FAQ）

问：我的文件存储在哪里？
答：在你电脑上的 ~/.local-ai-memory/memoria.db 中。你可以随时备份、复制或删除它。这是一个标准的 SQLite 文件。

问：我需要 Docker 或复杂的数据库软件吗？
答：不需要！无需 Docker 容器，也无需数据库服务。它直接运行在 Node.js 中。

问：它能保护我的隐私吗？
答：能。你的数据库不会离开你的设备。

---

📄 许可证

MIT 许可证 — 免费且面向所有人的开源软件。