sqlite-graphrag

Persistent memory for AI agents in a single Rust binary with built-in GraphRAG.

Portuguese version available at README.pt-BR.md
Public package and repository are live on GitHub and crates.io
Install the latest published release with cargo install sqlite-graphrag --locked
Upgrade an existing install with cargo install sqlite-graphrag --locked --force
Verify the active binary with sqlite-graphrag --version
See CHANGELOG.md for the full release history
Release-grade validation includes the slow-tests contract suites documented in docs/TESTING.md
Build directly from the local checkout with cargo install --path .

cargo install sqlite-graphrag --locked --force
sqlite-graphrag --version

What is it?

sqlite-graphrag delivers durable memory for AI agents

Stores memories, entities and relationships inside a single SQLite file under 25 MB
Embeds content locally via fastembed with the multilingual-e5-small model
Combines FTS5 full-text search with sqlite-vec KNN into a hybrid Reciprocal Rank Fusion ranker
Stores and traverses an explicit entity graph with typed edges for multi-hop recall across memories
Preserves every edit through an immutable version history table for full audit
Runs on Linux, macOS and Windows natively with zero external services required

Why sqlite-graphrag?

Differentiators against cloud RAG stacks

Offline-first architecture eliminates OpenAI embeddings and Pinecone recurring fees
Single-file SQLite storage replaces Docker clusters of vector databases entirely
Graph-native retrieval beats pure vector RAG on multi-hop questions by design
Deterministic JSON output unlocks clean orchestration by LLM agents in pipelines
Native cross-platform binary ships without Python, Node or Docker dependencies

Superpowers for AI Agents

First-class CLI contract for orchestration

Every subcommand accepts --json producing deterministic stdout payloads
Every invocation can stay stateless, but heavy commands auto-start a persistent daemon for embedding inference, reusing it across calls (this is daemon autostart, separate from automatic entity extraction)
sqlite-graphrag daemon still exists for explicit control, but the common path no longer requires manual startup
Every write is idempotent through --name kebab-case uniqueness constraints
Stdin is explicit: use --body-stdin for body text or --graph-stdin for one {body?, entities, relationships} object; raw entity and relationship arrays use --entities-file and --relationships-file
remember accepts body payloads up to 512000 bytes and up to 512 chunks
Relationship payloads use strength in [0.0, 1.0], mapped to weight in outputs
Stderr carries tracing output under SQLITE_GRAPHRAG_LOG_LEVEL=debug only
--help is English-first by design; use --lang for human-facing runtime messages, not static clap help text
Cross-platform behavior is identical across Linux, macOS and Windows hosts

Graph Schema

Entity types, relation labels and edge strength

entity_type accepts exactly 13 values: project, tool, person, file, concept, incident, decision, memory, dashboard, issue_tracker, organization, location, date
relation (CLI input) accepts exactly 12 hyphenated values: applies-to, uses, depends-on, causes, fixes, contradicts, supports, follows, related, mentions, replaces, tracked-in. JSON output stores them with underscores (e.g., applies_to).
strength is a float in [0.0, 1.0] representing edge weight; mapped to weight in all read outputs
Unlisted entity_type or relation values are rejected at write time with exit code 1
Use sqlite-graphrag graph --format json to inspect the full stored graph at any time

27 AI agents and IDEs supported out of the box

Agent	Vendor	Minimum version	Integration pattern
Claude Code	Anthropic	1.0	Subprocess with `--json` stdout
Codex	OpenAI	1.0	Tool call wrapping `cargo run -- recall`
Gemini CLI	Google	1.0	Function call returning JSON
Opencode	Opencode	1.0	Shell tool with `hybrid-search --json`
OpenClaw	Community	0.1	Subprocess pipe into `jaq` filters
Paperclip	Community	0.1	Direct CLI invocation per message
VS Code Copilot	Microsoft	1.85	Terminal subprocess via tasks
Google Antigravity	Google	1.0	Agent tool with structured JSON
Windsurf	Codeium	1.0	Custom command registration
Cursor	Anysphere	0.42	Terminal integration or MCP wrapper
Zed	Zed Industries	0.160	Extension wrapping subprocess
Aider	Paul Gauthier	0.60	Shell command hook per turn
Jules	Google Labs	1.0	Workspace shell integration
Kilo Code	Community	1.0	Subprocess invocation
Roo Code	Community	1.0	Custom command via CLI
Cline	Saoud Rizwan	3.0	Terminal tool registered manually
Continue	Continue Dev	0.9	Context provider via shell
Factory	Factory AI	1.0	Tool call with JSON response
Augment Code	Augment	1.0	Terminal command wrapping
JetBrains AI Assistant	JetBrains	2024.3	External tool per IDE
OpenRouter	OpenRouter	1.0	Function routing through shell
Minimax	Minimax	1.0	Subprocess invocation
Z.ai	Z.ai	1.0	Subprocess invocation
Ollama	Ollama	0.1	Subprocess invocation
Hermes Agent	Community	1.0	Subprocess invocation
LangChain	LangChain	0.3	Subprocess via tool
LangGraph	LangChain	0.2	Subprocess via node

Quick Start

Install and record your first memory in four commands

cargo install sqlite-graphrag --locked --force
sqlite-graphrag init
sqlite-graphrag remember --name onboarding-note --type user --description "first memory" --body "hello graphrag"
sqlite-graphrag recall "graphrag" --k 5 --json

Required flags for remember: --name, --type, --description. Body via --body "text", --body-file <path>, or --body-stdin (pipe from stdin). Body limit: 500 KB (512000 bytes). Larger inputs are rejected with exit code 6 (limit exceeded); split into multiple memories or trim before sending.

GraphRAG is enabled by default and runs automatically. Every subcommand auto-initializes graphrag.sqlite in the current working directory if it does not exist. remember and ingest extract entities and relationships via local BERT NER on every call (disable per-call with --skip-extraction). recall and hybrid-search auto-spawn the embedding daemon on demand.
sqlite-graphrag init is OPTIONAL but recommended on first use because it pre-downloads the embedding model and warms a smoke-test embedding (subsequent commands are faster). Without init, the first command pays the model-download cost.
graphrag.sqlite is created in the current working directory by default (override with --db <path> or SQLITE_GRAPHRAG_DB_PATH)
For the local checkout, cargo install --path . is enough
Re-run sqlite-graphrag --version after any upgrade to confirm the active binary
After the public release, prefer --locked to preserve the tested MSRV dependency graph

Memory Lifecycle

Runnable sequence: init → remember → recall → forget → purge

# 1. Initialize (once per database)
sqlite-graphrag init

# 2. Store a memory
sqlite-graphrag remember --name my-note --type user --description "demo" --body "first entry"

# 3. Retrieve by semantic similarity
sqlite-graphrag recall "first entry" --k 5 --json

# 4. Soft-delete (reversible)
sqlite-graphrag forget my-note

# 5. Permanently remove soft-deleted memories older than 0 days
sqlite-graphrag purge --retention-days 0 --yes

All five commands above are safe to run in sequence on a fresh database.

Installation

Minimum supported toolchain

Rust 1.88 or newer (rust-version = "1.88" in Cargo.toml); older toolchains will fail with an MSRV error during cargo install.

Multiple distribution channels

Install the latest published release with cargo install sqlite-graphrag --locked
Upgrade an existing published binary with cargo install sqlite-graphrag --locked --force
Pin to a specific version with cargo install sqlite-graphrag --version <X.Y.Z> --locked
Install from the local checkout with cargo install --path .
Build from the local checkout with cargo build --release
Homebrew formula is planned under brew install sqlite-graphrag
Scoop bucket is planned under scoop install sqlite-graphrag
Docker image planned as ghcr.io/daniloaguiarbr/sqlite-graphrag:<version>

Pre-built binaries (GitHub Releases)

x86_64-unknown-linux-gnu Linux Intel/AMD 64-bit
aarch64-unknown-linux-gnu Linux ARM 64-bit (Raspberry Pi 4+, AWS Graviton)
aarch64-apple-darwin macOS Apple Silicon (M1/M2/M3/M4)
x86_64-pc-windows-msvc Windows Intel/AMD 64-bit
aarch64-pc-windows-msvc Windows ARM 64-bit

Mac Intel users (x86_64-apple-darwin)

No pre-built binary is published for Intel Macs
GitHub retired the macos-13 runner in December 2025 and Apple discontinued x86_64 support
Build locally via cargo install sqlite-graphrag --locked (Rust 1.88+ required)
Recommended migration path is to Apple Silicon when feasible

Usage

Initialize the database

sqlite-graphrag init
sqlite-graphrag init --namespace project-foo

Without --db or SQLITE_GRAPHRAG_DB_PATH, every CRUD command in that directory uses ./graphrag.sqlite

Remember a memory with an optional explicit entity graph

By default, remember automatically extracts entities and relationships from the body via local BERT NER and stores them in the entity graph
Pass --skip-extraction to disable extraction for that single call

sqlite-graphrag remember \
  --name integration-tests-postgres \
  --type feedback \
  --description "prefer real Postgres over SQLite mocks" \
  --body "Integration tests must hit a real database."

remember JSON response includes urls_persisted (URLs routed to memory_urls table) and relationships_truncated (bool, set when relationships were capped)
URLs are stored in memory_urls via schema V007 and never pollute the entity graph
Sample JSON output illustrating extracted entities and relationships:

{
  "memory": {"id": 42, "name": "audit-note", "type": "project"},
  "extracted_entities": [
    {"name": "OpenAI", "kind": "organization", "saliency": 0.92},
    {"name": "Rust", "kind": "technology", "saliency": 0.85}
  ],
  "extracted_relationships": [
    {"source": "OpenAI", "target": "GPT-4", "relation": "develops"}
  ],
  "urls_persisted": [],
  "relationships_truncated": false
}

Skip BERT NER auto-extraction for faster ingestion

--skip-extraction disables extract_graph_auto for the current call only
Use it when the body is short, when you supply --entities-file upstream, or when CI memory is tight
The extraction_method field is omitted from the JSON response when active

sqlite-graphrag remember \
  --name release-notes-v1 \
  --type document \
  --description "release notes for v1.0.0" \
  --skip-extraction \
  --body-stdin < notes.md

Read, forget, edit and rename using positional name argument

sqlite-graphrag read integration-tests-postgres --json
sqlite-graphrag forget integration-tests-postgres
sqlite-graphrag history integration-tests-postgres --json
sqlite-graphrag edit integration-tests-postgres --body "Updated body text."
sqlite-graphrag rename integration-tests-postgres --new postgres-tests

Positional name is equivalent to --name <name> for read, forget, history, edit and rename

Recall memories by semantic similarity

sqlite-graphrag recall "postgres integration tests" --k 3 --json

Hybrid search combining FTS5 and vector KNN

sqlite-graphrag hybrid-search "postgres migration rollback" --k 10 --json

Inspect database health and stats

sqlite-graphrag health --json
sqlite-graphrag stats --json

Purge soft-deleted memories after retention period

sqlite-graphrag purge --retention-days 90 --dry-run --json
sqlite-graphrag purge --retention-days 90 --yes

Default retention: 90 days. To purge ALL forgotten memories regardless of age, pass --retention-days 0.

Run or control the persistent embedding daemon

sqlite-graphrag daemon --idle-shutdown-secs 600
sqlite-graphrag daemon --ping --json
sqlite-graphrag daemon --stop --json

Daemon auto-spawn behavior

recall, hybrid-search, and other embedding-heavy subcommands automatically spawn a background daemon (sqlite-graphrag daemon) when none is running, to amortise the model warm-up cost across multiple invocations.

Default: auto-spawn enabled (idle timeout 600s).

Disable per-invocation via flag:

sqlite-graphrag recall "query" --autostart-daemon=false

Disable globally via env var:

export SQLITE_GRAPHRAG_DAEMON_DISABLE_AUTOSTART=1

The CLI flag takes precedence over the env var.

Explicit lifecycle control:

sqlite-graphrag daemon                   # foreground, default 600s idle timeout
sqlite-graphrag daemon --idle-shutdown-secs 3600
sqlite-graphrag daemon --ping            # health-check
sqlite-graphrag daemon --stop            # graceful shutdown

Daemon convention: uses --ping/--stop/--idle-shutdown-secs FLAGS, not subcommands. Mirrors systemd-style flags more than git's verb-noun pattern.

Bulk-ingest every Markdown file under a directory

sqlite-graphrag ingest ./docs --type document --pattern '*.md' --recursive

Bulk-ingest with low-memory mode (single worker)

# Force single-threaded ingest to reduce RSS pressure (recommended for <4 GB RAM
# environments and container/cgroup constraints). Trade-off: 3-4x longer wall time.
sqlite-graphrag ingest ./docs --type document --pattern '*.md' --low-memory

# Or via env var (CLI flag takes precedence):
SQLITE_GRAPHRAG_LOW_MEMORY=1 sqlite-graphrag ingest ./docs --type document

Rename a memory while keeping its version history

sqlite-graphrag rename old-name --new-name new-name --json

Edit a memory body or description (creates a new version)

sqlite-graphrag edit integration-tests-postgres --body "Updated body."
sqlite-graphrag edit integration-tests-postgres --description "Updated description."

Restore a memory to a previous version

sqlite-graphrag history integration-tests-postgres --json
sqlite-graphrag restore --name integration-tests-postgres --version 2 --json

Apply pending schema migrations

sqlite-graphrag migrate --status --json
sqlite-graphrag migrate --json

Resolve namespace precedence for the current invocation

sqlite-graphrag namespace-detect --json
sqlite-graphrag namespace-detect --namespace project-foo --json

Refresh SQLite query planner statistics

sqlite-graphrag optimize --json

Reclaim disk space and checkpoint the WAL

sqlite-graphrag vacuum --json

Create a typed relationship between two entities

sqlite-graphrag link --from "OpenAI" --to "GPT-4" --relation uses --weight 0.8 --json

Remove a specific relationship between two entities

sqlite-graphrag unlink --from "OpenAI" --to "GPT-4" --relation uses --json

Traverse memories connected via the entity graph

sqlite-graphrag related onboarding-note --max-hops 2 --limit 10 --json

Empty results are normal for memories without graph edges yet — extract entities first via remember or ingest. Edges form when ≥2 entities co-occur in the same memory body.

Export a graph snapshot in json, dot or mermaid

sqlite-graphrag graph --format json --output graph.json
sqlite-graphrag graph stats --json
sqlite-graphrag graph traverse --from "OpenAI" --depth 2 --json
sqlite-graphrag graph entities --entity-type organization --limit 50 --json

Remove orphan entities with no memories and no relationships

sqlite-graphrag cleanup-orphans --dry-run --json
sqlite-graphrag cleanup-orphans --yes --json

Clear cached embedding/NER models from the XDG cache

sqlite-graphrag cache clear-models --yes

List every version of a memory

sqlite-graphrag history integration-tests-postgres --no-body --json

Commands

Core database lifecycle

Command	Arguments	Description
`init`	`--namespace <ns>`	Initialize database and download embedding model
`daemon`	`--ping`, `--stop`, `--idle-shutdown-secs`, `--db`, `--json`	Run or control the persistent embedding daemon
`health`	`--json`	Show database integrity and pragma status
`stats`	`--json`	Count memories, entities and relationships
`migrate`	`--json`	Apply pending schema migrations via `refinery`
`vacuum`	`--json`	Checkpoint WAL and reclaim disk space
`optimize`	`--json`	Run `PRAGMA optimize` to refresh statistics
`sync-safe-copy`	`--dest <path>` (alias `--output`)	Checkpoint then copy a sync-safe snapshot

Memory content lifecycle

Command	Arguments	Description
`remember`	`--name`, `--type`, `--description`, `--body` (or `--body-file`/`--body-stdin`), `--entities-file`, `--relationships-file`, `--graph-stdin`, `--skip-extraction`	Save a memory with optional entity graph
`recall`	`<query>`, `-k`/`--k` (alias `--limit` since v1.0.35), `--type`, `--max-hops`, `--max-distance`, `--all-namespaces`, `--no-graph`	Search memories semantically via KNN + graph traversal
`read`	`[name]` or `--name <name>`	Fetch a memory by exact kebab-case name
`list`	`--type`, `--limit`, `--offset`, `--include-deleted`	Paginate memories sorted by `updated_at`
`forget`	`[name]` or `--name <name>`	Soft-delete a memory preserving history
`rename`	`[old]`, or `--name`/`--old`/`--from <NAME>` (since v1.0.35), `--new-name`/`--new`/`--to <NAME>` (since v1.0.35)	Rename a memory while keeping versions
`edit`	`[name]` or `--name`, `--body`, `--description`	Edit body or description creating new version
`history`	`[name]` or `--name <name>`	List all versions of a memory
`restore`	`--name`, `--version`	Restore a memory to a previous version
`ingest`	`<DIR>`, `--type`, `--pattern <GLOB>` (default `*.md`), `--recursive`, `--ingest-parallelism N`, `--low-memory` (env `SQLITE_GRAPHRAG_LOW_MEMORY=1`), `--skip-extraction`, `--fail-fast`	Bulk-ingest every matching file as a separate memory (NDJSON output)
`cache clear-models`	`--yes`	Remove cached embedding/NER models from the XDG cache directory

Memory name validation. Names must match [a-z0-9-]+ (kebab-case, ASCII only). Unicode and uppercase are rejected with exit code 1. Names longer than 60 chars emitted by ingest are truncated to fit; review the WARN log to spot mangled names.

Retrieval and graph

Command	Arguments	Description
`hybrid-search`	`<query>`, `--k`, `--rrf-k`	FTS5 plus vector fused via Reciprocal Rank Fusion
`namespace-detect`	`--namespace <name>`	Resolve namespace precedence for invocation
`link`	`--from`, `--to`, `--relation`, `--weight`	Create an explicit relationship between two entities
`unlink`	`--from`, `--to`, `--relation`	Remove a specific relationship between two entities
`related`	`--name`, `--limit`, `--hops`	Traverse graph-connected memories from a seed memory
`graph`	`--format`, `--output`	Export a graph snapshot in `json`, `dot` or `mermaid`

Graph subcommands

Subcommand	Description	Key flags
`graph traverse --from <ENTITY>`	Walk the entity graph from a starting node using BFS	`--depth` (default 2), `--namespace`
`graph stats`	Print graph statistics (node count, edge count, degree distribution)	`--namespace`
`graph entities`	List entities stored in the graph with optional filters	`--limit` (default 50), `--entity-type`, `--namespace`

Maintenance

Command	Arguments	Description
`purge`	`--retention-days <n>`, `--dry-run`, `--yes`	Permanently delete soft-deleted memories
`cleanup-orphans`	`--namespace`, `--dry-run`, `--yes`	Remove entities that have no memories and no relationships

`cache` subcommands

Subcommand	Description
`clear-models`	Remove cached embedding/NER model files (forces re-download on next `init`)

Environment Variables

Runtime configuration overrides

Variable	Description	Default	Example
`SQLITE_GRAPHRAG_DB_PATH`	Path to the SQLite database file override	`./graphrag.sqlite` in the invocation directory	`/data/graphrag.sqlite`
`SQLITE_GRAPHRAG_HOME`	Override base directory for `graphrag.sqlite` (used when `--db` and `SQLITE_GRAPHRAG_DB_PATH` are absent)	unset	`/var/lib/sqlite-graphrag`
`SQLITE_GRAPHRAG_CACHE_DIR`	Directory override for model cache and lock files	XDG cache dir	`~/.cache/sqlite-graphrag`
`SQLITE_GRAPHRAG_LANG`	CLI output language as `en` or `pt` (aliases: `pt-BR`, `portuguese`)	`en`	`pt`
`SQLITE_GRAPHRAG_LOG_LEVEL`	Tracing filter level for stderr output	`info`	`debug`
`SQLITE_GRAPHRAG_LOG_FORMAT`	Tracing output format on stderr (`pretty` or `json`)	`pretty`	`json`
`SQLITE_GRAPHRAG_NAMESPACE`	Namespace override bypassing detection	none	`project-foo`
`SQLITE_GRAPHRAG_DISPLAY_TZ`	IANA timezone for `*_iso` JSON fields	`UTC`	`America/Sao_Paulo`
`SQLITE_GRAPHRAG_DAEMON_FORCE_AUTOSTART`	Force daemon autostart even when guards would skip it	unset	`1`
`SQLITE_GRAPHRAG_DAEMON_DISABLE_AUTOSTART`	Disable daemon autostart entirely (useful in tests/CI)	unset	`1`
`SQLITE_GRAPHRAG_DAEMON_CHILD`	INTERNAL flag set automatically when spawning the daemon child; do not set manually	unset	`1`
`ORT_DYLIB_PATH`	Explicit path to `libonnxruntime.so` for ARM64 GNU dynamic loading	auto-discovery	`/opt/sqlite-graphrag/libonnxruntime.so`

Integration Patterns

Compose with Unix pipelines and tools

sqlite-graphrag recall "auth tests" --k 5 --json | jaq -r '.results[].name'

Feed hybrid search into a summarizer endpoint

sqlite-graphrag hybrid-search "postgres migration" --k 10 --json \
  | jaq -c '.results[] | {name, combined_score}' \
  | xh POST http://localhost:8080/summarize

Backup with atomic snapshot and compression

sqlite-graphrag sync-safe-copy --dest /tmp/ng.sqlite
ouch compress /tmp/ng.sqlite /tmp/ng-$(date +%Y%m%d).tar.zst

Claude Code subprocess example in Node

const { spawn } = require('child_process');
const proc = spawn('sqlite-graphrag', ['recall', query, '--k', '5', '--json']);

Docker Debian build for CI pipelines

FROM rust:1.88-bookworm AS builder
RUN apt-get update && apt-get install -y --no-install-recommends pkg-config libssl-dev ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY . .
RUN cargo install --path .

Exit Codes

Deterministic status codes for orchestration

Code	Meaning	Possible Cause
`0`	Success	Command completed and JSON payload printed when requested
`1`	Validation error or runtime failure	Invalid `--type`, invalid `--relation`, kebab-case violation, generic anyhow error
`2`	Duplicate detected, invalid CLI argument, or concurrency error	Existing `--name`, malformed flag, mutually exclusive options
`3`	Conflict during optimistic update	`edit` or `restore` raced against another writer
`4`	Memory or entity not found	`read`, `forget`, `edit`, `rename`, `restore` or `graph traverse` target missing
`5`	Namespace could not be resolved	No `SQLITE_GRAPHRAG_NAMESPACE`, no flag, no detected default
`6`	Payload exceeded configured limits	`--name` longer than 80 bytes, body over `512000` bytes, more than `512` chunks
`10`	SQLite database error	Corrupted file, schema mismatch, missing migration
`11`	Embedding generation failed	Model load error or daemon embedding RPC failure
`12`	`sqlite-vec` extension failed to load	Missing native extension or unsupported SQLite build
`13`	Batch partial failure	`import`, `reindex` or stdin batch with at least one failing record
`14`	Filesystem I/O error	Cache or database directory not writable
`15`	Database busy after retries	WAL contention exceeded `with_busy_retry` budget
`20`	Internal or JSON serialization error	Unexpected serde failure or invariant violation
`73`	`EX_NOPERM` memory guard rejected low RAM	Available RAM below safety threshold during slot acquisition
`75`	`EX_TEMPFAIL` lock timeout or all concurrency slots busy	Five-plus concurrent invocations or `flock` waited longer than 300s
`77`	Available RAM below minimum required	Less than 2 GB free RAM detected before model load

Performance

Measured on a 1000-memory database

In-process warm-model latency remains far lower than one-shot subprocess latency
Stateless CLI invocations typically spend about one second reloading the embedding model per heavy command
Warm in-process recall can stay well below the stateless subprocess timing once the model is already resident
First init downloads the quantized model once and caches it locally
Embedding model uses approximately 1100 MB of RAM per process instance after the v1.0.18 daemon-based RSS calibration (52 GiB regression in v1.0.17 reduced to 1.03 GiB peak)

Memory Requirements

Sizing RAM for ingest and recall workloads

Minimum 3 GB RAM recommended (4 GB+ for large corpora). Floor sits around 2 GB just to load ONNX runtime + BERT NER + fastembed multilingual-e5-small models.
Default parallelism (--ingest-parallelism = min(4, cpus/2)) increases RSS roughly linearly per worker. With 4 workers, ingest of 30 files peaks around 4.4 GB.
Low-memory mode: pass --low-memory (or set SQLITE_GRAPHRAG_LOW_MEMORY=1) to force single-threaded ingest. Equivalent to --ingest-parallelism 1 and overrides any explicit value. Reduces peak RSS to about 2.6 GB at the cost of 3-4x wall time.
Container/cgroup users: a cap below 3 GB causes OOM-kill during model load. Use cgroup MemoryMax=4G or higher in production.
Upstream tracking: see https://github.com/microsoft/onnxruntime/issues/22271 for ONNX CPU memory growth across many runs.

Storage Footprint

Expected DB size relative to ingested content

Expected overhead: roughly 8× the total ingested body size (e.g., 7.6 MB of text → ~62.9 MB DB). Overhead comes from 384-dim float embeddings, FTS5 full-text index, and the entities/relationships graph. Run sqlite-graphrag vacuum --json after bulk forget+purge cycles to reclaim reclaimed space.

Safe Parallel Invocation

Counting semaphore with up to four simultaneous slots

Each invocation loads multilingual-e5-small consuming roughly 1100 MB of RAM after the v1.0.18 measurement pass
MAX_CONCURRENT_CLI_INSTANCES remains the hard ceiling at 4 cooperating subprocesses
Heavy commands init, remember, recall, and hybrid-search are clamped lower dynamically when available RAM cannot sustain the requested parallelism safely
Lock files live at ~/.cache/sqlite-graphrag/cli-slot-{1..4}.lock using flock
A fifth concurrent invocation waits up to 300 seconds then exits with code 75
Use --max-concurrency N to request the slot limit for the current invocation; heavy commands may still be reduced automatically
Memory guard aborts with exit 77 when less than 2 GB of RAM is available
SIGINT and SIGTERM trigger graceful shutdown via shutdown_requested() atomic

Troubleshooting FAQ

Common issues and fixes

Default behavior always creates or opens graphrag.sqlite in the current working directory
Database locked after crash requires sqlite-graphrag vacuum to checkpoint the WAL
First init takes roughly one minute while fastembed downloads the quantized model
On aarch64-unknown-linux-gnu, embedding-heavy commands resolve libonnxruntime.so from ORT_DYLIB_PATH, the executable directory, ./lib/, then the model cache directory
If ARM64 GNU embedding commands fail at startup, point ORT_DYLIB_PATH to the exact libonnxruntime.so shipped with the binary
Permission denied on Linux means the cache directory lacks write access for your user
Namespace detection falls back to global when no explicit override is present
Parallel invocations that exceed the effective safe limit receive exit 75 and SHOULD retry with backoff; during audits start heavy commands with --max-concurrency 1

Compatible Rust Crates

Invoke sqlite-graphrag from any Rust AI framework via subprocess

Each crate calls the binary through std::process::Command with --json flag
No shared memory or FFI required: the contract is pure stdout JSON
Pin the binary version in your Cargo.toml workspace for reproducible builds
All 18 crates below work identically on Linux, Apple Silicon macOS and Windows

rig-core

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "project goals", "--k", "5", "--json"])
    .output().unwrap();

swarms-rs

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["hybrid-search", "agent memory", "--k", "10", "--json"])
    .output().unwrap();

autoagents

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["remember", "--name", "task-context", "--type", "project",
           "--description", "current sprint goal", "--body", "finish auth module"])
    .output().unwrap();

graphbit

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "decision log", "--k", "3", "--json"])
    .output().unwrap();

agentai

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["hybrid-search", "previous decisions", "--k", "5", "--json"])
    .output().unwrap();

llm-agent-runtime

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "user preferences", "--k", "5", "--json"])
    .output().unwrap();

anda

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["stats", "--json"])
    .output().unwrap();

adk-rust

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "tool outputs", "--k", "5", "--json"])
    .output().unwrap();

rs-graph-llm

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["hybrid-search", "graph relations", "--k", "10", "--json"])
    .output().unwrap();

genai

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "model context", "--k", "5", "--json"])
    .output().unwrap();

liter-llm

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["remember", "--name", "session-notes", "--type", "user",
           "--description", "session recap", "--body", "discussed architecture"])
    .output().unwrap();

llm-cascade

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "fallback context", "--k", "3", "--json"])
    .output().unwrap();

async-openai

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "system prompt history", "--k", "5", "--json"])
    .output().unwrap();

async-llm

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["hybrid-search", "chat context", "--k", "5", "--json"])
    .output().unwrap();

anthropic-sdk

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "tool use patterns", "--k", "5", "--json"])
    .output().unwrap();

ollama-rs

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "local model outputs", "--k", "5", "--json"])
    .output().unwrap();

mistral-rs

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["hybrid-search", "inference context", "--k", "10", "--json"])
    .output().unwrap();

llama-cpp-rs

use std::process::Command;
let out = Command::new("sqlite-graphrag")
    .args(["recall", "llama session context", "--k", "5", "--json"])
    .output().unwrap();

Contributing

Pull requests are welcome

Read the contribution guidelines in CONTRIBUTING.md
Open issues at the GitHub repository for bugs or feature requests
Follow the code of conduct described in CODE_OF_CONDUCT.md

Security

Responsible disclosure policy

Security reports follow the policy described in SECURITY.md
Contact the maintainer privately before disclosing vulnerabilities publicly

JSON Schemas

Canonical contracts for every subcommand response

Authoritative JSON Schemas for every --json response live under docs/schemas/ and are versioned alongside the crate
30 schemas cover init, remember, recall, hybrid-search, list, read, forget, purge, rename, edit, history, restore, link, unlink, health, stats, migrate, vacuum, optimize, cleanup-orphans, sync-safe-copy, graph (+ stats/traverse/entities), related, namespace-detect, debug-schema
Treat these schemas as the agent contract; SKILL.md documents the same shapes in human-readable form
Validate downstream consumers with any standard JSON Schema validator (e.g. ajv, jsonschema)

Changelog

Release history tracked separately

Read the full release history in CHANGELOG.md

Acknowledgments

Built on top of excellent open source

fastembed provides local quantized embedding models without ONNX hassle
sqlite-vec adds vector indexes directly inside SQLite as an extension
refinery runs schema migrations with transactional safety guarantees
clap powers the CLI argument parsing with derive macros
rusqlite wraps SQLite with safe Rust bindings and bundled build

License

Dual license MIT OR Apache-2.0

Licensed under either of Apache License 2.0 or MIT License at your option
See LICENSE-APACHE and LICENSE-MIT in the repository root for full text

sqlite-graphrag 1.0.41