Prerequisites

• 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

Getting Started

[!IMPORTANT] Databases created with sqlite-memory versions earlier than 1.0.0 must be rebuilt before use with 1.0.0+, because the internal schema changed.

Example: Building an AI Agent with Memory

```python import sqlite3

One-time setup. Later connections reuse the saved provider/model and lazily

Building

```bash

Build (full build with local + remote engines)

make

Build Configurations

• 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:

```bash

Custom build with specific options

make OMIT_LOCAL_ENGINE=1 OMIT_REMOTE_ENGINE=0 OMIT_IO=0 ```

---

Quick Start

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

Working Example

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.

Use Cases

• 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

Configuration

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

Clone with submodules

git clone --recursive https://github.com/sqliteai/sqlite-memory.git cd sqlite-memory

Run parser/core unit tests + extension loading smoke test

make test

Run the full SQL extension unit suite

make test DEFINES="-DTEST_SQLITE_EXTENSION" ```