SQLite-Memory

Persistent, searchable memory for AI agents.
Markdown-based memory with semantic search, hybrid retrieval, and offline-first sync between agents. Drop-in memory layer for any LLM workflow.

Free managed instance → · Docs · Website · Blog

Data: Vector · Sync · Columnar · JS
AI: AI · Agent · Memory · MCP

Multiple agents need shared memory? SQLite-Memory syncs locally via CRDTs; pair it with SQLite Cloud (or your own Postgres/Supabase) to coordinate memory across machines, users, and workers. Free tier available.

A SQLite extension that gives AI agents persistent, searchable memory, optimized for markdown content. Features hybrid semantic search (vector similarity + FTS5), markdown-aware chunking, and local embedding via llama.cpp.

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.

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.

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 bridges these concepts, allowing any SQLite-powered application to ingest, store, and semantically search over knowledge bases.

• 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

• 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

• Hybrid Search: Combines vector similarity (cosine distance) with FTS5 full-text search for superior retrieval
• Smart Chunking: Markdown-aware parsing preserves semantic boundaries
• Intelligent Sync: Content-hash change detection skips unchanged files, atomically replaces modified ones, and cleans up deleted ones
• Transactional Safety: Text/file ingests run inside SAVEPOINT transactions, and directory sync uses transactional cleanup plus per-file transactional updates so failed files do not leave partial rows behind
• Efficient Storage: Binary embeddings with configurable dimensions
• Embedding Cache: Automatically caches computed embeddings, so re-indexing the same text skips redundant API calls and computation
• Flexible Embedding: Use local models (llama.cpp) or vectors.space remote API

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

• SQLite
• sqlite-vector extension
• sqlite-sync extension (optional, only needed for agent sync)
• For local embeddings: A GGUF embedding model (e.g., nomic-embed-text)
• For remote embeddings: A free API key from vectors.space

-- Load extensions (sync is optional)
.load ./vector
.load ./cloudsync
.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_apikey('your-vectorspace-api-key');
-- SELECT memory_set_model('openai', 'text-embedding-3-small');

-- Provider/model settings are persisted. New connections reuse them and
-- initialize the engine lazily on first embedding use. Remote API keys are
-- connection-scoped, so call memory_set_apikey() on each remote connection.

-- 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');
-- Paths are stored relative to /path/to/docs, so the database can be materialized elsewhere.

-- 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    │
-- └──────────────┴─────────────────────────────────────┴─────────┘

sqlmem is the Go CLI for managing SQLite Memory projects from the terminal. It creates .sqlmem.json, manages the SQLite database, downloads and loads the SQLite extensions, configures embedding models, indexes Markdown sources, runs hybrid searches, watches files for changes, and exposes the memory tools over MCP.

Use it when you want a project-level workflow around sqlite-memory without writing SQL directly:

cd cli
make build
./sqlmem init --model /path/to/embedding-model.gguf
./sqlmem add ../docs
./sqlmem search -q "how do I configure memory?"

See the sqlmem README for installation, configuration, extension cache paths, PDF support, MCP, and command examples.

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. Later connections reuse the saved provider/model and lazily
# load the engine on first embedding use.
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

By default, all memory_add_* functions use content-hash change detection to avoid redundant work:

• memory_add_text: Computes a hash of the content. If the same content was already indexed, it is skipped entirely. No duplicate embeddings are ever created.
• memory_add_file: Reads the file and hashes its content. If the file was previously indexed with different content, the old entry (chunks, embeddings, FTS) is atomically replaced. Unchanged files are skipped. Absolute file paths are stored as portable logical suffixes, while the original local path is retained only in local metadata.
• memory_add_content: Indexes caller-provided file content without reading from the filesystem, preserving the supplied logical file name/path and optional context.
• memory_add_directory: Performs a full two-phase sync:
  1. Cleanup: Removes database entries for files that no longer exist on disk
  2. Scan: Recursively processes all matching files - adding new ones, replacing modified ones, and skipping unchanged ones. Stored paths are relative to the scanned directory root, with local provenance retained only in local metadata.

For virtual-file or editor workflows that need separate logical paths even when content is identical or empty, enable path-preserving storage:

SELECT memory_set_option('preserve_duplicate_paths', 1);

In this mode, dbmem_content.hash identifies the stored entry and is scoped by path.

The same mode supports explicit empty directory markers for virtual filesystems:

SELECT memory_set_option('preserve_duplicate_paths', 1);
SELECT memory_add_content('dirname/', '');

Directory markers are listed as directories, materialized as directories by memory_materialize_files(), and ignored by memory_search.

memory_add_text(), memory_add_file(), and memory_add_content() each run inside a SQLite SAVEPOINT transaction. memory_add_directory() performs its cleanup pass transactionally and then processes each file in its own transaction. If one file fails, that file rolls back cleanly and previously-committed files remain valid; there are no partially-indexed rows or orphaned chunk/FTS entries for the failed file.

This makes all sync functions safe to call repeatedly - for example, on a cron schedule or at agent startup - with minimal overhead.

For interactive workflows (e.g. a dashboard upload) where content should appear immediately and embeddings can be computed later by a background process, enable deferred mode:

-- store content instantly: no embedding model needed, nothing is computed
SELECT memory_set_option('defer_embeddings', 1);
SELECT memory_add_content('docs/api.md', '# API\nUploaded from the dashboard.');

-- pending files are visible right away ("indexed":false in the JSON tree)
SELECT memory_list_files();

-- later, from a background worker: embed in batches and report progress
SELECT memory_embed_pending(10);   -- returns rows processed in this batch
SELECT memory_pending_count();     -- rows still waiting

Deferred content is stored in dbmem_content but is invisible to memory_search until it is embedded. Each file is embedded in its own transaction, so a file is either fully indexed or still pending — an interrupted worker can simply be restarted, and other connections can watch progress while a batch runs.

Multiple agents can share and merge knowledge without any coordination. Each agent works independently with its own local SQLite database, syncing through a shared SQLiteCloud managed database when connectivity is available.

Enable sync on a database connection before ingesting content:

-- Load the sqlite-sync extension
SELECT load_extension('./cloudsync');

-- Enable CRDT sync (optionally scoped to a specific context)
SELECT memory_enable_sync();               -- sync all memory
SELECT memory_enable_sync('project-x');   -- sync only the 'project-x' context

-- Connect to the shared cloud database
SELECT cloudsync_network_init('your-managed-database-id');
SELECT cloudsync_network_set_apikey('your-api-key');

-- Ingest content normally — CRDT tracks every write
SELECT memory_add_text('Agent A findings...', 'research');

-- Push local changes and pull remote ones (call twice for full bidirectional exchange)
SELECT cloudsync_network_sync(500, 3);
SELECT cloudsync_network_sync(500, 3);

-- Refresh hashes and embeddings for any content received or merged from other agents
SELECT memory_reindex();

Each piece of text added to the database is parsed into chunks and tracked by a block-level LWW CRDT algorithm, which merges line-level changes from concurrent agents without conflicts. Only the portable dbmem_content table is synced — embeddings and local filesystem provenance are always local. After a sync merge changes dbmem_content.value, memory_reindex() recomputes stale content hashes and refreshes local embeddings.

The combination of local-first memory and CRDT sync enables agent architectures that are not possible with centralized databases:

• No single point of failure — each agent has a complete, queryable copy of shared memory
• Offline-capable — agents ingest and search without network access; sync catches up when connectivity returns
• Selective sharing — memory_enable_sync('context') limits sync to a named context, so agents can keep private memory separate from shared memory
• Scales to many agents — agents running on different nodes accumulate knowledge in parallel and merge into a single consistent corpus without coordination

test/sync/ contains a full integration test that walks through the entire flow:

• Agent A indexes knowledge about the James Webb Space Telescope
• Agent B indexes knowledge about the Great Barrier Reef
• After sync, both agents can answer questions about both topics — knowledge each agent never directly indexed

See test/sync/README.md for setup instructions, SQLiteCloud account configuration, and how to run the test.

• AI Assistants: Maintain conversation history and user preferences
• Documentation Search: Semantic search over markdown documentation
• Knowledge Bases: Build searchable knowledge repositories
• Note-Taking Apps: Find notes by meaning, not just keywords
• Code Understanding: Index and search code documentation
• Personal Memory: Store and retrieve personal knowledge

Tune the memory system for your needs:

-- Chunking parameters
SELECT memory_set_option('max_tokens', 512);      -- Tokens per chunk
SELECT memory_set_option('overlay_tokens', 100);  -- Overlap between chunks

-- Search behavior
SELECT memory_set_option('max_results', 30);      -- Max search results
SELECT memory_set_option('min_score', 0.75);      -- Score threshold
SELECT memory_set_option('vector_weight', 0.6);   -- Vector vs FTS balance
SELECT memory_set_option('text_weight', 0.4);
SELECT memory_set_option('search_oversample', 4); -- Fetch 4x candidates before merging

-- File processing
SELECT memory_set_option('extensions', 'md,txt,rst');  -- File types to index
SELECT memory_set_option('preserve_duplicate_paths', 1); -- Keep duplicate/empty virtual paths

-- Embedding cache (enabled by default)
SELECT memory_set_option('embedding_cache', 0);        -- Disable cache
SELECT memory_set_option('cache_max_entries', 10000);  -- Limit cache size (0 = no limit)
SELECT memory_cache_clear();                           -- Clear cached embeddings

-- View all memories
SELECT hash, path, context, datetime(created_at, 'unixepoch', 'localtime') as created
FROM dbmem_content;

-- Delete by context
SELECT memory_delete_context('old-project');

-- Delete specific memory by hash
SELECT memory_delete('9e3779b97f4a7c15');

-- Clear all memories
SELECT memory_clear();

For complete API documentation, including all functions and configuration options, see API.md.

# Clone with submodules
git clone --recursive https://github.com/sqliteai/sqlite-memory.git
cd sqlite-memory

# Build (full build with local + remote engines)
make

# Run parser/core unit tests + extension loading smoke test
make test

# Run the full SQL extension unit suite
make test DEFINES="-DTEST_SQLITE_EXTENSION"

• Local Engine: Built-in llama.cpp for on-device embeddings (requires GGUF model)
• Remote Engine: vectors.space API for cloud embeddings (requires free API key)
• File I/O: memory_add_file, memory_add_directory, and memory_materialize_files functions

You can also combine options manually:

# Custom build with specific options
make OMIT_LOCAL_ENGINE=1 OMIT_REMOTE_ENGINE=0 OMIT_IO=0

MIT License - see LICENSE for details.

Need to share agent memory across devices, users, or workers? SQLite Cloud is the managed backend for SQLite-Memory — sync memory across a fleet of agents with auth, ACL, and observability.

Start free →

SQLite-Memory is one piece of a larger ecosystem that turns SQLite into a runtime for intelligent, distributed data:

Data layer

• sqlite-vector — ANN vector search inside SQLite
• sqlite-sync — Offline-first CRDT sync across devices
• sqlite-columnar — Column-oriented analytics for OLAP queries
• sqlite-js — Custom SQLite functions written in JavaScript

AI layer

• sqlite-ai — On-device LLM inference and embeddings
• sqlite-agent — Autonomous AI agents running inside SQLite
• sqlite-memory — Persistent, searchable memory for agents (you are here)
• sqlite-mcp — Call MCP tools directly from SQL queries

Managed platform

• SQLite Cloud — Hosted SQLite with sync, auth, edge functions, and analytics. Free tier →

Built by SQLite AI. Questions? Open a discussion or contact us.