sqlite-graphrag

Persistent memory for AI agents in a single Rust binary with built-in GraphRAG. Current release: v1.0.79 — LLM-Only and one-shot. Every build embeds through claude -p or codex exec (OAuth, no MCP, no hooks). No daemon, no ONNX runtime, ~6 MB binary. The embedding-legacy feature was REMOVED in v1.0.79; there is no local-model build path.

• Read this document in Portuguese (pt-BR).

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

• Upgrading from v1.0.74 / v1.0.75? See docs/MIGRATION.md for the v1.0.76 / v1.0.77 / v1.0.78 migration procedure

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
• Build (v1.0.79): LLM-only and one-shot — embeddings are generated by spawning claude -p or codex exec with OAuth; no local model, no daemon, no ONNX runtime, ~6 MB binary
• Legacy build: REMOVED in v1.0.79 — the embedding-legacy feature and the local fastembed/ONNX path no longer exist
• Combines FTS5 full-text search with pure-Rust cosine similarity 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 (default build needs claude or codex CLI on PATH)

Why sqlite-graphrag?

Differentiators against cloud RAG stacks

• OAuth-only LLM flow — no API keys ever in the environment; the spawn ABORTS if ANTHROPIC_API_KEY or OPENAI_API_KEY is set (defence in depth since v1.0.69)
• No recurring embedding fees — embeddings come from your existing Claude Pro / Max or ChatGPT Pro subscription
• 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 (default build needs only claude or codex CLI)

Superpowers for AI Agents

First-class CLI contract for orchestration

• Every subcommand accepts --json producing deterministic stdout payloads
• v1.0.76 is one-shot by default — no background process; each embedding call spawns a fresh claude -p or codex exec
• 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 any kebab-case or snake_case string. 12 canonical values are well-known: applies-to, uses, depends-on, causes, fixes, contradicts, supports, follows, related, mentions, replaces, tracked-in. Custom values (e.g., implements, tested-by, blocks) are accepted with a tracing::warn!. JSON output normalizes to 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 values are rejected at write time with exit code 1. Custom relation values are accepted since v1.0.49.
• 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 (21 catalogued + 6 community)

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. Windows users (G29): v1.0.68 is the first release since v1.0.65 that successfully compiles via cargo install on Windows. If you must stay on v1.0.66 or v1.0.67, see docs/CROSS_PLATFORM.md for the manual workaround.

• GraphRAG is enabled by default and runs automatically. Every subcommand auto-initializes graphrag.sqlite in the current working directory if it does not exist. Entity/relationship extraction comes from the LLM backend (--extraction-backend llm, the default) or from curated graph input (--graph-stdin, --entities-file).

Automatic extraction (--enable-ner)

• Pass --enable-ner or set SQLITE_GRAPHRAG_ENABLE_NER=1 to activate automatic extraction on remember and ingest

• Since v1.0.79 this runs URL-regex extraction ONLY — the local GLiNER zero-shot pipeline was removed together with the ner-legacy feature

• --gliner-variant, SQLITE_GRAPHRAG_GLINER_MODEL and SQLITE_GRAPHRAG_GLINER_THRESHOLD are still accepted for compatibility but have NO effect

• Response field extraction_method reports url-regex, regex-only, or none:extraction-failed

• For high-quality entity/relationship extraction prefer ingest --mode claude-code/--mode codex (LLM-curated) or pass curated entities via --graph-stdin

• --skip-extraction is deprecated since v1.0.45 and has no effect

• sqlite-graphrag init is OPTIONAL but recommended on first use because it creates the database, applies migrations and validates that a claude or codex CLI is reachable on PATH (there is no model download since v1.0.76 — embeddings come from the LLM subprocess).

• 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

Version Highlights

• v1.0.79: G42 closed — the LLM embedding pipeline is no longer slow, serialized or fragile. (S1) configurable embedding dimensionality, default 64 (--embedding-dim, SQLITE_GRAPHRAG_EMBEDDING_DIM, range [8, 4096]; precedence flag > env > schema_meta.dim > 64; existing 384-dim databases keep working unchanged, ZERO schema change). (S2) batched LLM calls ({items:[{i,v}]} — chunks at 8, entity names at 25 at dim 64, dim-adaptive via clamp(base×64/dim, 1, base) since G44; 39 spawns collapse into 4-5). (S3) real bounded parallelism via Semaphore + JoinSet with the new --llm-parallelism flag on remember (default 4), ingest (default 2) and edit; results stream through a bounded mpsc channel. (S4) codex schema tempfiles are RAII NamedTempFiles; the reaper also removes stale codex-home-{pid} dirs. (S5) SQLITE_GRAPHRAG_CLAUDE_EMBED_MODEL env override. (S6) empty CLAUDE_CONFIG_DIR by default on the embedding path (~40-50s → ~10-15s per call). (S7) actionable codex headless error. (S8) panic-free signal handler (second signal exits 130 with ZERO I/O). (S9) canonical re-embed: enrich --operation re-embed plus edit --force-reembed. (C5) validate_dim errors on divergent vectors instead of silently normalising. Every LLM subprocess uses kill_on_drop plus SQLITE_GRAPHRAG_EMBED_TIMEOUT_SECS (default 300s). Also REMOVED: the daemon infrastructure and the legacy embedding-legacy/ner-legacy/full features with the fastembed/ort/ndarray/tokenizers/hf-hub optional dependencies — every build is LLM-only.
• v1.0.78: G41 fix — migrate --rehash no longer inserts phantom rows for unapplied migrations (V013 was being registered without executing its SQL)
• v1.0.77: G40 fix — the run_rehash INSERT now writes applied_on (RFC3339); a NULL there blocked every subsequent migration
• v1.0.76: Breaking architectural change — the default build becomes LLM-only and one-shot: no daemon, no ONNX runtime, no local model download; embeddings/NER delegate to claude -p or codex exec headless (OAuth). Migration V013 drops the vec_* virtual tables in favour of BLOB-backed embedding tables with pure-Rust cosine similarity. New migrate --rehash and migrate --to-llm-only --drop-vec-tables upgrade paths. 7 new ADRs (0019-0025) plus ADR-0026 documenting the V002 drift root cause
• v1.0.75: new ExtractionBackend trait (G21) behind the global --extraction-backend llm|embedding|none|both flag; LLM-backed extraction becomes the default
• v1.0.74: --skip-extraction no-op compatibility restored (v1.0.45 promise honored) — the hard validation error introduced in v1.0.67 reverted to tracing::warn!
• v1.0.73: CI fix — clang/mold/lld installed inside the cross container for aarch64-unknown-linux-gnu builds
• v1.0.72: CI fix — mold linker installed on ubuntu-latest runners (12+ jobs failed with invalid linker name in argument)
• v1.0.71: CI fix — Swatinem/rust-cache repinned from the non-existent v2.8 ref to v2.9.1 across 17 call-sites
• v1.0.70: i18n fix — manual POSIX locale precedence LC_ALL > LC_MESSAGES > LANG (the cached system locale ignored runtime env vars)
• v1.0.69: 12 gaps closed (G28-G39) with full OAuth-only enforcement. (OAuth-only behaviour change) claude -p and codex exec spawns now ABORT with AppError::Validation if ANTHROPIC_API_KEY or OPENAI_API_KEY are set; the --bare flag is REMOVED from all executable code. Operators using API keys MUST migrate to OAuth. (G28 CRITICAL) 4 reinforcing fixes for process proliferation: 7 flags hardening in claude_runner::build_claude_command (always passes --strict-mcp-config --mcp-config '{}' --settings '{"hooks":{}}' --dangerously-skip-permissions), SIGTERM on timeout, new src/reaper.rs walking /proc at startup, and src/system_load.rs plus CircuitBreaker integration. (G29) enrich --operation body-enrich now succeeds 100% (was 100% CHECK constraint failure), with audit trail via memory_versions, type-safe MemorySource enum, Jaccard preservation gate (10 tests, default 0.7), and blake3 idempotency skip. (G30) Singleton lock scoped per (job_type, namespace, db_hash) with new --wait-job-singleton and --force-job-singleton flags. (G31+G32+G33) New src/commands/codex_spawn.rs (~700 lines, 11 tests) unifies spawn pipeline, JSONL parser, and ChatGPT Pro OAuth model validation; enrich --mode codex and ingest --mode codex share the same canonical command (was divergent, motivated the ~/.local/bin/codex-clean wrapper). (G34) Worker warning is conditional to mode (Claude > 4, Codex > 16). (G35) --preflight-check, --fallback-mode, --rate-limit-buffer prevent batch loss on Claude rate limit. (G36) optimize pre-checks FTS5 health before rebuilding, plus new --fts-dry-run, --fts-progress, --yes. (G37) --names <NAME> and --names-file <PATH> for selective enrichment. (G38) Backup defaults 25x faster (1000/5ms vs 100/50ms) with 4 new tuning flags. (G39) New vec orphan-list/vec purge-orphan/vec stats subcommand family plus forget hook to prevent new orphans. +53 tests (692 → 745). 7 new ADRs (docs/decisions/adr-0011-0017-*.md) document every architectural decision.
• v1.0.68: 2 CRITICAL fixes for Windows + process proliferation. (G29) cargo install no Windows was breaking with error[E0308] in src/terminal.rs:29 because HANDLE in windows-sys >= 0.59 is *mut c_void (was isize in 0.48/0.52). Replaced with the type-safe idiom !handle.is_null() && handle != INVALID_HANDLE_VALUE, pinned windows-sys to =0.59.0 exact, and added CI job windows-build-check that runs cargo check --target x86_64-pc-windows-msvc on every push. (G28-B) Added lock::acquire_job_singleton per (job_type, namespace) so two parallel enrich/ingest --mode claude-code|codex invocations against the same database now fail fast with the new exit-75 AppError::JobSingletonLocked { job_type, namespace } instead of stacking 4 × N workers × 10 MCP processes (root cause of the 2026-06-03 276-load-average incident). (G28-A) claude_runner::build_claude_command now respects SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR — when set to an empty directory, the subprocess is spawned with CLAUDE_CONFIG_DIR=<that dir>, suppressing user-scoped MCP servers and their 8-10-process fan-out. Deliberately avoids --strict-mcp-config / --mcp-config '{}' because [anthropics/claude-code#10787] documents that Claude Code CLI ignores both flags. (G28-D) retry::CircuitBreaker helper plus a tracing::warn! when --llm-parallelism > 4 (combine with CLAUDE_CONFIG_DIR override to keep subprocess fan-out manageable). Also fixed 3 pre-existing test failures in src/commands/{history,list,read}.rs that were leaking the SQLITE_GRAPHRAG_DISPLAY_TZ env var between parallel tests.
• v1.0.67: 2 NEW commands: remember-batch (NDJSON batch memory creation with --transaction/--force-merge), completions (shell completions for Bash/Zsh/Fish/PowerShell/Elvish); read --id for direct memory_id lookup, enrich --llm-parallelism for parallel LLM workers, health super-hub detection (degree > 50), edit skip-embed optimization via body_hash comparison, rename ghost purge for soft-deleted name conflicts, flag validation in hybrid-search/recall/ingest, V012 relationship timestamps migration, 24 gap fixes total
• v1.0.66: 35 BUG/GAP fixes including 3 CRITICAL (reclassify-relation crash, evidence chain flooding, link weight), edit --type flag, graph_context in deep-research, LLM-friendly aliases for graph/list JSON, full doc audit
• v1.0.65: 3 NEW commands: reclassify-relation (bulk relationship type renames with UNIQUE collision handling), normalize-entities (normalize entity names to kebab-case with auto-merge), enrich (LLM-augmented graph quality: memory-bindings, entity-descriptions, body-enrich); CRITICAL deep-research fixes: per-sub-query embeddings (was sharing one), RRF fusion for KNN+FTS5 (was hardcoded 0.5), directed evidence chains (was flat global dump); new deep-research flags --rrf-k, --graph-decay, --graph-min-score, --max-neighbors-per-hop; entity name normalization on all write paths; health reports relation concentration; --max-entity-degree warning on link/remember
• v1.0.64: NEW deep-research command for parallel multi-hop GraphRAG research via query decomposition (up to 7 sub-queries) with bounded JoinSet + Semaphore fan-out and evidence chain assembly; ingest claude-code disables hooks via --settings for OAuth (was failing 65% of files), detects OAuth and omits misleading cost_usd, validates body size BEFORE LLM extraction (files >512 KB skipped); rename/rename-entity reject same-name with exit 1
• v1.0.63: restore preserves current name after rename (was reverting to version's original name), ingest claude-code/codex normalizes relation strings before DB insertion, edit re-generates vector embeddings when body changes, OAuth-first auth docs
• v1.0.62: 10 bug fixes for ingest --mode claude-code (G01 CRITICAL: recall now works), NEW --mode codex for OpenAI Codex CLI extraction, new flags --codex-binary/--codex-model/--codex-timeout
• v1.0.61: 15 bug fixes for ingest --mode claude-code (B00-B13), new --claude-timeout flag, wait-timeout subprocess management
• v1.0.60: NEW ingest --mode claude-code for LLM-curated extraction via Claude Code CLI, queue DB for resume/retry, 7 new ingest flags
• v1.0.59: rename-entity name validation, unlink schema fix, reclassify description_updated field, contract+schema tests for rename-entity, E2E entity validation tests, doc audit (6 files)
• v1.0.58: FTS5 sync fix (CRITICAL: remember --force-merge was silently corrupting FTS5 index), merge-entities UNIQUE fix for memory_entities, new rename-entity command, entity name validation, memory-entities --entity reverse lookup, reclassify --description, purge response action field, fts help EXAMPLES, health tracing
• v1.0.57: 16 fixes — merge-entities UNIQUE constraint, memory-entities column name, --clear-body validation, WAL checkpoint for fts rebuild/check, degree recalculation for delete-entity/merge-entities adjacents, atomic backup via tempfile-rename, 18 new contract+schema tests
• v1.0.56: 9 new commands (fts, backup, delete-entity, reclassify, merge-entities, memory-entities, prune-ner), 7 new flags, 19 new JSON fields, FTS5 graceful degradation, JSON error envelope
• v1.0.55: Full doc audit — export summary total→exported, list response fields corrected, --tz exit code 1→2, exit 2 added to exit code table, stats legacy aliases documented
• v1.0.54: WAL checkpoint for prune-relations (last missing command), --graph-stdin empty body validation, memory_type JSON field in list/export, Vec::with_capacity in 9 cold paths
• v1.0.53: WAL checkpoint TRUNCATE after every write command for Dropbox/cloud-sync safety, export --json contract fix, Vec::with_capacity in 12 hot paths
• v1.0.52: 12 gaps fixed, new export subcommand, exit code Duplicate 2→9 (breaking), forget not-found no JSON (breaking)
• v1.0.51: Namespace env var fix (8 commands), remember on soft-deleted fix, per-chunk RSS watchdog (--max-rss-mb), daemon test coverage
• v1.0.50: prune-relations subcommand, daemon auto-restart on version mismatch, V011 index, 37 doc gaps fixed
• v1.0.49: Extensible relation vocabulary, V010 migration, 15 doc updates
• v1.0.48: GLiNER NER functional, 5 bug fixes, full doc audit
• v1.0.47: Replace BERT NER with GLiNER zero-shot, 13 custom entity types, --gliner-variant flag
• v1.0.35: Flag aliases (--from/--to, --old/--new, --limit as alias of --k)

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

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 does NOT run automatic URL extraction (off by default)
• Pass --enable-ner to activate URL-regex extraction for that call, or set SQLITE_GRAPHRAG_ENABLE_NER=1 (the GLiNER pipeline was removed in v1.0.79)

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
}

Automatic extraction status (GLiNER removed in v1.0.79)

• The local GLiNER zero-shot NER pipeline was REMOVED in v1.0.79 with the ner-legacy feature; --enable-ner now performs URL-regex extraction only
• For LLM-curated entity/relationship extraction use ingest --mode claude-code or ingest --mode codex
• For exact control pass curated entities via --graph-stdin, --entities-file and --relationships-file
• The extraction_method field in the JSON response reports which path ran

sqlite-graphrag remember \
  --name release-notes-v1 \
  --type document \
  --description "release notes for v1.0.0" \
  --enable-ner \
  --llm-parallelism 4 \
  --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

Deep research with parallel multi-hop query decomposition (v1.0.64)

sqlite-graphrag deep-research "auth architecture decisions and incidents" --k 20 --json

• Decomposes the query into up to 7 sub-queries, runs them in parallel via bounded JoinSet + Semaphore, merges results with cross-query deduplication, and assembles evidence chains from graph traversal
• Defaults calibrated against NovelHopQA, StepChain, HopRAG benchmarks: --k 20, --max-sub-queries 7, --max-hops 3

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.

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

Bulk-ingest with LLM-curated entities via Claude Code (v1.0.61)

# Extract entities and relationships using locally installed Claude Code CLI
sqlite-graphrag ingest ./docs --mode claude-code --recursive --json

# Resume interrupted ingestion
sqlite-graphrag ingest ./docs --mode claude-code --resume --json

# Set budget limit
sqlite-graphrag ingest ./docs --mode claude-code --max-cost-usd 5.00 --json

# Extract entities and relationships using locally installed OpenAI Codex CLI
sqlite-graphrag ingest ./docs --mode codex --recursive --json

Authentication: OAuth is the ONLY accepted credential flow. API keys are PROHIBITED. --mode claude-code reads OAuth from ~/.claude/.credentials.json (Claude Pro/Max/Team). --mode codex reads device auth from codex login (OpenAI ChatGPT). Defining ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment ABORTS the spawn with AppError::Validation and exit code 1. The --bare flag (which would also demand an API key) is REMOVED from all executable code paths. See docs/decisions/adr-0011-oauth-only-enforcement.md for the full rationale. ingest emits NDJSON on stdout: one JSON line per file, then a summary line. Per-file status values: indexed (created), skipped (duplicate or invalid name), failed (error). Duplicates emit status: "skipped" with action: "duplicate" and do not count as failures. Pass --dry-run to preview the name mapping (kebab-cased basenames) without writing anything to the database. Schema: docs/schemas/ingest-file-event.schema.json, docs/schemas/ingest-summary.schema.json.

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

Bulk-delete relationships by type

sqlite-graphrag prune-relations --relation mentions --dry-run --show-entities --json
sqlite-graphrag prune-relations --relation mentions --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

Memory content lifecycle

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

Breaking change in v1.0.44. graph entities JSON output renamed top-level array from items to entities. Update jaq/jq filters: .items[] becomes .entities[]. The list command still uses items.

Graph subcommands

Maintenance

cache subcommands

Environment Variables

Runtime configuration overrides

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

Performance

Measured on a 1000-memory database

• Embedding latency is dominated by the headless LLM round-trip (~1-3 s per batched call); pure reads (read, list, graph) stay in the low milliseconds
• Since v1.0.79 LLM calls are BATCHED (calibration bases of 8 chunks / 25 entity names at dim 64, dim-adaptive — G44) and PARALLEL (--llm-parallelism, bounded Semaphore + JoinSet), so a 39-item memory embeds in 4-5 calls instead of 39 serialized spawns
• --embedding-dim 64 (the default) cuts the LLM output per vector ~6x compared to the old 384-dim payload
• init performs no model download — it only creates the database and validates that a claude/codex CLI is reachable
• Build (v1.0.79): each embedding call spawns claude -p or codex exec — RSS is ~350 MB per LLM worker (the 1100 MB ONNX model load no longer exists in any build)

Memory Requirements

Sizing RAM for ingest and recall workloads

• The CLI itself is lightweight (~6 MB binary); RAM is dominated by the LLM subprocesses at roughly 350 MB RSS per worker (LLM_WORKER_RSS_MB)
• Worker budget: effective parallelism is min(--llm-parallelism, cpus, free_ram × 0.5 / 350 MB, 32) — the concurrency gate adapts to available memory automatically
• Default parallelism increases RSS roughly linearly per worker (--llm-parallelism 4 ≈ 4 × 350 MB of subprocess RSS on top of the CLI)
• 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, at the cost of 3-4x wall time.
• Container/cgroup users: budget MemoryMax for the CLI plus N × 350 MB LLM workers (the old 3 GB ONNX floor no longer exists)

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 float embeddings (default 64-dim since v1.0.79; pre-existing databases keep their recorded dimensionality, e.g. 384), 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 LLM embedding worker (claude -p/codex exec subprocess) consumes roughly 350 MB of RSS — the budget unit used by the concurrency gate since v1.0.79
• 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
• Exit code 130 when interrupted by SIGINT (Ctrl+C)
• Exit code 141 when SIGPIPE fires (stdout closed by downstream consumer in pipeline)
• Exit code 143 when terminated by SIGTERM
• Second signal forces immediate exit without waiting for current operation

Troubleshooting FAQ

Cloud sync safety (Dropbox, iCloud, OneDrive)

• sqlite-graphrag uses WAL mode by default for high-concurrency writes
• Since v1.0.54, every write command runs PRAGMA wal_checkpoint(TRUNCATE) after committing (v1.0.53 covered 11 of 12; v1.0.54 added the missing prune-relations)
• This ensures the .sqlite file is always self-contained when cloud sync tools read it
• If corruption occurs despite the checkpoint, recover with sqlite3 broken.sqlite ".recover" | sqlite3 repaired.sqlite

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
• init is near-instant since v1.0.76 — there is no model download; if it fails, check that a claude or codex CLI is reachable on PATH
• Embedding calls failing with exit 11 usually mean the LLM CLI is missing, unauthenticated (OAuth required) or timing out — raise SQLITE_GRAPHRAG_EMBED_TIMEOUT_SECS (default 300) for slow links
• ORT_DYLIB_PATH/libonnxruntime.so guidance is HISTORICAL (≤ v1.0.75) — no build loads ONNX since v1.0.76
• 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
• 64 schemas cover init, remember, remember-batch (+ summary), recall, hybrid-search, deep-research, list, read, forget, purge, rename, edit, history, restore, link, unlink, prune-relations, health, stats, migrate (+ migrate-rehash + migrate-to-llm-only), vacuum, optimize, cleanup-orphans, sync-safe-copy, backup, graph (+ stats/traverse/entities), related, namespace-detect, debug-schema, entities-input, relationships-input, ingest-file-event (+ ingest-summary), ingest-claude-phase (+ file-event + summary), export-memory-line (+ summary), enrich-phase (+ item-event + summary), fts rebuild (+ fts check + fts stats), vec orphan-list (+ vec purge-orphan + vec stats), codex-models, error-envelope
• 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

• PRD — Product Requirements Document (source of truth for the 31 behavioral contracts)
• Read the full release history in CHANGELOG.md

Acknowledgments

Built on top of excellent open source

• fastembed and sqlite-vec powered the local embedding pipeline up to v1.0.75 (removed since — embeddings now come from claude/codex subprocesses)
• 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