sqlite-memory如何为AI智能体构建持久化、可搜索的记忆系统？（附Markdown优化）

一个为 AI 智能体提供持久化、可搜索记忆的 SQLite 扩展，专为 Markdown 内容优化。具备混合语义搜索结合向量相似度搜索和全文搜索的技术，提高检索的准确性和智能性。（向量相似度 + FTS5全文搜索）、Markdown 感知分块根据 Markdown 文档结构进行智能分块，保留语义边界的技术。以及通过 llama.cpp 实现的本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。功能。

一个为 AI 智能体提供持久化、可搜索记忆的 SQLite 扩展，专为 Markdown 内容优化。具备混合语义搜索结合向量相似度搜索和全文搜索的技术，提高检索的准确性和智能性。（向量相似度 + FTS5全文搜索）、Markdown 感知分块根据 Markdown 文档结构进行智能分块，保留语义边界的技术。以及通过 llama.cpp 实现的本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。功能。

智能体的记忆数据库可以通过 sqlite-sync 使用 离线优先技术 在多个智能体之间同步。每个智能体独立工作，在连接时进行同步，这使其成为分布式 AI 系统、边缘部署和协作式智能体架构的理想选择。

Agent memory databases can be synchronized between agents using offline-first technology via sqlite-sync. Each agent works independently and syncs when connected, making it ideal for distributed AI systems, edge deployments, and collaborative agent architectures.

AI 智能体记忆的未来

现代 AI 智能体需要持久化、可搜索的记忆，以在对话和任务之间保持上下文。受 OpenClaw 记忆架构 的启发，sqlite-memory 实现了我们认为将成为 AI 智能体记忆系统事实标准的方法：将 Markdown 文件作为单一事实来源。

Modern AI agents need persistent, searchable memory to maintain context across conversations and tasks. Inspired by OpenClaw's memory architecture, sqlite-memory implements what we believe will become the de facto standard for AI agent memory systems: markdown files as the source of truth.

在这种范式中：

• Markdown 文件 作为人类可读、可版本控制的知识库。
• 嵌入向量 实现语义理解和检索。
• 混合搜索 结合了全文搜索的精确性和向量相似度的智能性。

In this paradigm:

• Markdown files serve as human-readable, version-controllable knowledge bases.
• Embeddings enable semantic understanding and retrieval.
• Hybrid search combines the precision of full-text search with the intelligence of vector similarity.

sqlite-memory 连接了这些概念，使得任何基于 SQLite 的应用程序都能够摄取、存储并对知识库进行语义搜索。

sqlite-memory bridges these concepts, allowing any SQLite-powered application to ingest, store, and semantically search over knowledge bases.

为什么选择 sqlite-memory？

对于 AI 智能体开发者

• 持久化记忆：为您的智能体提供在重启后依然存在的长期记忆。
• 语义回忆：基于含义而非仅仅是关键词检索相关上下文。
• 上下文隔离：按上下文（项目、对话、主题）组织记忆。
• 本地优先：完全在设备上运行，使用本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。模型——无需 API 成本、无延迟、数据不出系统。

• Persistent Memory: Give your agents long-term memory that survives restarts.
• Semantic Recall: Retrieve relevant context based on meaning, not just keywords.
• Context Isolation: Organize memories by context (projects, conversations, topics).
• Local-First: Run entirely on-device with local embedding models - no API costs, no latency, no data leaving your system.

对于应用程序开发者

• 零基础设施：无需部署向量数据库服务器——它只是 SQLite。
• 单一文件：您的整个知识库都存储在一个便携的 .db 文件中。
• SQL 接口：使用熟悉的 SQL 查询您的语义记忆。
• 可嵌入性：在任何 SQLite 可以运行的地方工作——移动端、桌面端、边缘、WASM。

• Zero Infrastructure: No vector database servers to deploy - it's just SQLite.
• Single File: Your entire knowledge base lives in one portable .db file.
• SQL Interface: Query your semantic memory using familiar SQL.
• Embeddable: Works anywhere SQLite works - mobile, desktop, edge, WASM.

技术优势

Feature	Description	Key Advantage
Hybrid Search	Combines vector similarity (cosine distance) with FTS5 full-text search	Superior retrieval performance
Smart Chunking	Markdown-aware parsing preserves semantic boundaries	Improved retrieval accuracy
Intelligent Sync	Content-hash change detection	Skips unchanged files, atomically replaces modified ones, cleans up deleted ones
Transactional Safety	Every sync operation runs inside a SAVEPOINT transaction	Fully succeeds or fully rolls back, no risk of partially-indexed content
Efficient Storage	Binary embeddings with configurable dimensions	Storage efficient
Embedding Cache	Automatically caches computed embeddings	Skips redundant API calls and computation when re-indexing the same text
Flexible Embedding	Supports local models (llama.cpp) or remote APIs (e.g., vectors.space)	Adapts to different deployment scenarios and requirements

架构

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
├─────────────────────────────────────────────────────────────┤
│                      sqlite-memory                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Parser    │  │  Embedding  │  │   Hybrid Search     │  │
│  │  (md4c)     │  │ (llama.cpp) │  │ (vector + FTS5)     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                   sqlite-vector                             │
├─────────────────────────────────────────────────────────────┤
│                      SQLite                                 │
└─────────────────────────────────────────────────────────────┘

快速开始

先决条件

组件	描述	备注
SQLite	核心数据库引擎	必需
sqlite-vector	向量扩展	必需
sqlite-sync	同步扩展	仅智能体同步时需要
本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。模型	GGUF 格式的嵌入模型（如 nomic-embed-text）	用于本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。
远程 API 密钥	来自 vectors.space 的免费 API 密钥	用于远程嵌入

Component	Description	Note
SQLite	Core database engine	Required
sqlite-vector	Vector extension	Required
sqlite-sync	Sync extension	Only needed for agent sync
Local Embedding Model	GGUF embedding model (e.g., nomic-embed-text)	For local embeddings
Remote API Key	A free API key from vectors.space	For remote embeddings

快速入门示例

-- 加载扩展（sync 是可选的）
.load ./vector
.load ./sync
.load ./memory

-- 配置嵌入模型（选择一种）：

-- 选项 1：使用 llama.cpp 进行本地嵌入（无需网络）
SELECT memory_set_model('local', '/path/to/nomic-embed-text-v1.5.Q8_0.gguf');

-- 选项 2：通过 vectors.space 进行远程嵌入（需要从 https://vectors.space 获取免费 API 密钥）
-- 提供者名称 'openai' 选择 vectors.space 的 OpenAI 兼容端点。
-- SELECT memory_set_model('openai', 'text-embedding-3-small');
-- SELECT memory_set_apikey('your-vectorspace-api-key');

-- 添加一些知识
SELECT memory_add_text('SQLite is a C-language library that implements a small, fast,
self-contained, high-reliability, full-featured, SQL database engine. SQLite is the
most used database engine in the world.', 'sqlite-docs');

SELECT memory_add_text('Vector databases store data as high-dimensional vectors,
enabling similarity search. They are essential for semantic search, recommendation
systems, and AI applications.', 'concepts');

-- 添加整个文档目录
SELECT memory_add_directory('/path/to/docs', 'project-docs');

-- 语义搜索您的记忆
SELECT path, snippet, ranking
FROM memory_search
WHERE query = 'how do databases store information efficiently';

-- 按语义相似度 + 关键词匹配排序的结果
-- ┌──────────────┬─────────────────────────────────────┬─────────┐
-- │     path     │               snippet               │ ranking │
-- ├──────────────┼─────────────────────────────────────┼─────────┤
-- │ (uuid)       │ SQLite is a C-language library...   │ 0.89    │
-- │ (uuid)       │ Vector databases store data as...   │ 0.82    │
-- └──────────────┴─────────────────────────────────────┴─────────┘

-- Load extensions (sync is optional)
.load ./vector
.load ./sync
.load ./memory

-- Configure embedding model (choose one):

-- Option 1: Local embedding with llama.cpp (no internet required)
SELECT memory_set_model('local', '/path/to/nomic-embed-text-v1.5.Q8_0.gguf');

-- Option 2: Remote embedding via vectors.space (requires free API key from https://vectors.space)
-- The provider name 'openai' selects the vectors.space OpenAI-compatible endpoint.
-- SELECT memory_set_model('openai', 'text-embedding-3-small');
-- SELECT memory_set_apikey('your-vectorspace-api-key');

-- Add some knowledge
SELECT memory_add_text('SQLite is a C-language library that implements a small, fast,
self-contained, high-reliability, full-featured, SQL database engine. SQLite is the
most used database engine in the world.', 'sqlite-docs');

SELECT memory_add_text('Vector databases store data as high-dimensional vectors,
enabling similarity search. They are essential for semantic search, recommendation
systems, and AI applications.', 'concepts');

-- Add an entire documentation directory
SELECT memory_add_directory('/path/to/docs', 'project-docs');

-- Search your memory semantically
SELECT path, snippet, ranking
FROM memory_search
WHERE query = 'how do databases store information efficiently';

-- Results ranked by semantic similarity + keyword matching
-- ┌──────────────┬─────────────────────────────────────┬─────────┐
-- │     path     │               snippet               │ ranking │
-- ├──────────────┼─────────────────────────────────────┼─────────┤
-- │ (uuid)       │ SQLite is a C-language library...   │ 0.89    │
-- │ (uuid)       │ Vector databases store data as...   │ 0.82    │
-- └──────────────┴─────────────────────────────────────┴─────────┘

示例：构建一个具备记忆的 AI 智能体

import sqlite3

# 连接到您的记忆数据库
conn = sqlite3.connect('agent_memory.db')
conn.enable_load_extension(True)
conn.load_extension('./vector')
conn.load_extension('./memory')

# 一次性设置
conn.execute("SELECT memory_set_model('local', './models/nomic-embed-text-v1.5.Q8_0.gguf')")

# 存储对话上下文
def remember(content, context="conversation"):
    conn.execute("SELECT memory_add_text(?, ?)", (content, context))
    conn.commit()

# 检索相关记忆
def recall(query, min_score=0.7):
    cursor = conn.execute("""
        SELECT snippet, ranking FROM memory_search
        WHERE query = ? AND ranking > ?
        ORDER BY ranking DESC
    """, (query, min_score))
    return cursor.fetchall()

# 在您的智能体中使用
remember("User prefers concise responses and uses Python primarily.")
remember("Project deadline is March 15th, focusing on API integration.")

# 稍后，当用户询问项目时...
memories = recall("what's the project timeline")
# 返回关于 3月15日 截止日期的相关上下文

import sqlite3

# Connect to your memory database
conn = sqlite3.connect('agent_memory.db')
conn.enable_load_extension(True)
conn.load_extension('./vector')
conn.load_extension('./memory')

# One-time setup
conn.execute("SELECT memory_set_model('local', './models/nomic-embed-text-v1.5.Q8_0.gguf')")

# Store conversation context
def remember(content, context="conversation"):
    conn.execute("SELECT memory_add_text(?, ?)", (content, context))
    conn.commit()

# Retrieve relevant memories
def recall(query, min_score=0.7):
    cursor = conn.execute("""
        SELECT snippet, ranking FROM memory_search
        WHERE query = ? AND ranking > ?
        ORDER BY ranking DESC
    """, (query, min_score))
    return cursor.fetchall()

# Use in your agent
remember("User prefers concise responses and uses Python primarily.")
remember("Project deadline is March 15th, focusing on API integration.")

# Later, when the user asks about the project...
memories = recall("what's the project timeline")
# Returns relevant context about March 15th deadline

智能同步

所有 memory_add_* 函数都使用内容哈希变更检测来避免冗余工作：

All memory_add_* functions use content-hash change detection to avoid redundant work:

• memory_add_text：计算内容的哈希值。如果相同内容已被索引，则完全跳过。永远不会创建重复的嵌入向量。
• **`

常见问题（FAQ）

sqlite-memory 如何实现 AI 智能体的持久化记忆？

sqlite-memory 是一个 SQLite 扩展，通过将 Markdown 文件作为单一事实来源，结合本地嵌入在本地设备上运行嵌入模型生成向量表示，无需网络连接和数据外传。模型（如 llama.cpp）和 SQLite 数据库，为 AI 智能体提供重启后依然存在的长期记忆存储。

sqlite-memory 的混合搜索有什么优势？

它结合了向量相似度（语义搜索）和 FTS5 全文搜索，既能基于含义智能检索上下文，又能通过关键词精确匹配，从而实现更优的检索效果和准确性。

为什么说 sqlite-memory 适合分布式 AI 系统？

因为它支持通过 sqlite-sync 进行离线优先同步支持代理在离线状态下独立工作，连接时自动同步数据的技术架构。，每个智能体可独立工作并在连接时同步记忆数据库，无需中央服务器，非常适合边缘部署和协作式智能体架构。