sqlmem manages SQLite Memory databases backed by Markdown sources. The CLI handles project config, optional PDF conversion cache, watch mode, and MCP. Markdown parsing, chunking, embedding, schema, FTS, and vector search stay inside the sqlite-memory extension.

sqlmem init --model /path/to/nomic-embed-text-v1.5.Q8_0.gguf
sqlmem add ./docs
sqlmem search -q "sqlite vector search" --limit 5

Remote embeddings use vectors.space when an API key is present:

sqlmem init --api-key "$sqlmem_API_KEY" --model text-embedding-3-small

API key precedence is: CLI flag, sqlmem_API_KEY, config.

sqlmem init creates .sqlmem.json in the project root. Edit it manually or use:

sqlmem config
sqlmem config set options.max_results 10

If no config is found, commands fail with:

No .sqlmem.json found. Run `sqlmem init` first.

PDF indexing is disabled by default because it needs a separate conversion/OCR step. Enable it explicitly before adding PDF files:

sqlmem config set pdf.enabled true

PDFs are then converted to Markdown before indexing. The default converter shells out to glm-ocr and stores cache entries under the global PDF cache:

<pdf-cache>/<sha256>/
  source.json
  content.md

Override with --pdf-cache-dir or sqlmem_PDF_CACHE_DIR.

sqlmem add ./docs
sqlmem add ./file.pdf
sqlmem add -s ./docs -s ./file.pdf
sqlmem search -q "query" --json
sqlmem watch
sqlmem mcp --transport stdio
sqlmem mcp --transport http --addr 127.0.0.1:8765
sqlmem status
sqlmem clear
sqlmem reindex
sqlmem remove ./docs
sqlmem reset

Running sqlmem without arguments opens an interactive prompt with command history and arrow-key navigation.

Practical examples for common sqlmem workflows.

Create .sqlmem.json, create the SQLite database, and configure the embedding model.

sqlmem init --model /models/nomic-embed-text-v1.5.Q8_0.gguf

Use a custom extension cache directory:

sqlmem init \
  --extensions-dir ~/.cache/sqlmem/extensions \
  --model /models/nomic-embed-text-v1.5.Q8_0.gguf

When an API key is present, sqlmem configures sqlite-memory for remote embeddings.

sqlmem init \
  --api-key "$sqlmem_API_KEY" \
  --model text-embedding-3-small

You can also set the API key through the environment:

export sqlmem_API_KEY="..."
sqlmem init --model text-embedding-3-small

Precedence is:

1. --api-key
2. sqlmem_API_KEY
3. .sqlmem.json

Add a directory:

sqlmem add ./docs

Add one Markdown file:

sqlmem add ./README.md

Add multiple sources in one command:

sqlmem add ./docs ./notes/project.md

Use repeated --source flags:

sqlmem add -s ./docs -s ./notes/project.md

Attach a context label to added content:

sqlmem add ./docs --context product-docs

PDF indexing is disabled by default because it requires a separate conversion/OCR step. Enable it explicitly first:

sqlmem config set pdf.enabled true

PDF files are then converted to Markdown before indexing.

sqlmem add ./papers/sqlite-memory-overview.pdf

Use a custom PDF cache directory:

sqlmem --pdf-cache-dir ~/.cache/sqlmem/pdf add ./papers/report.pdf

Disable PDF support again:

sqlmem config set pdf.enabled false

Search with a positional query:

sqlmem search "hybrid search with sqlite"

Search with flags:

sqlmem search -q "embedding cache behavior" --limit 5

Return JSON for scripts:

sqlmem search -q "vector extension load order" --limit 10 --json

Pipe JSON to jq:

sqlmem search -q "pdf cache" --json | jq '.[].path'

Watch sources already stored in .sqlmem.json:

sqlmem watch

Watch explicit paths for the current session:

sqlmem watch ./docs ./notes/project.md

Use a shorter debounce window:

sqlmem watch --debounce 200ms

Show database path, source count, embedding selection, PDF cache, and indexed counts:

sqlmem status

Show the full configuration:

sqlmem config

Set the default search limit:

sqlmem config set options.max_results 10

Lower the minimum score:

sqlmem config set options.min_score 0.65

Disable embedding cache:

sqlmem config set options.embedding_cache false

Set supported indexed file extensions:

sqlmem config set options.extensions "md,mdx,txt"

Opt into reStructuredText explicitly:

sqlmem config set options.extensions "md,mdx,txt,rst"

Start the MCP server over stdio:

sqlmem mcp --transport stdio

Start the MCP server over HTTP:

sqlmem mcp --transport http --addr 127.0.0.1:8765

Available MCP tools:

memory_search
memory_add_file
memory_add_directory
memory_add_text
memory_clear
memory_delete
memory_delete_context
memory_reindex
memory_status

Remove a configured source from .sqlmem.json:

sqlmem remove ./docs

Reindex all stored memory:

sqlmem reindex

Clear all memory content:

sqlmem clear

Reset the project by deleting the configured database and .sqlmem.json:

sqlmem reset

Run without a subcommand to open the interactive prompt:

sqlmem

Inside the prompt:

sqlmem> status
sqlmem> search "release notes"
sqlmem> add ./notes
sqlmem> quit

Command history is available with the up and down arrow keys.

Fail if no results are returned:

results="$(sqlmem search -q "database migration" --json)"
count="$(printf '%s' "$results" | jq 'length')"
test "$count" -gt 0

Index all Markdown files changed in the current Git branch:

git diff --name-only main...HEAD -- '*.md' '*.mdx' |
while IFS= read -r file; do
  [ -f "$file" ] && sqlmem add "$file"
done

Create a project-local database name:

sqlmem init --model /models/nomic-embed-text-v1.5.Q8_0.gguf
sqlmem config set database ".cache/project-memory.sqlite"