sqlite-graphrag - SKILL.md Agent Skill

name: sqlite-graphrag description: This skill MUST activate for sqlite-graphrag CLI operations including persistent memory, GraphRAG, entity graph, hybrid search, recall, remember, ingest, enrich, deep-research, LLM embedding, backend selection (codex claude opencode), OAuth-only enforcement, preflight validation, FTS5, BLOB-backed cosine similarity, CWD isolation, namespace management, migration, maintenance. Activates on keywords memory RAG GraphRAG SQLite one-shot OAuth offline persistent graph entity embedding codex claude opencode remember recall hybrid-search ingest enrich forget purge link

When This Skill Activates

ACTIVATE when the user asks to remember, save, recall, retrieve, search, or persist anything across sessions
ACTIVATE for long-term context, knowledge graph, GraphRAG, RAG, entity linking, memory management
ACTIVATE when sqlite, sqlite-graphrag, embedding, FTS5, hybrid-search, or LLM memory is mentioned
NEVER ACTIVATE for one-off ephemeral data, simple file I/O, or tasks unrelated to persistent context

LLM Prompt Instruction Rules

WHEN user says "remember this", "save this", "persist this" → EXECUTE remember --force-merge with --graph-stdin including curated entities and canonical relations
WHEN user asks "what do you know about X", "recall X", "search X" → EXECUTE hybrid-search "X" --k 10 --json FIRST, then EXPAND top results with read --name <name> --json
WHEN user asks "how is X related to Y" → EXECUTE graph traverse --from X --depth 2 --json or related X --hops 2 --json
WHEN user asks "deep research on X" → EXECUTE deep-research "X" --k 20 --max-hops 3 --json
BEFORE creating ANY memory → EXECUTE hybrid-search "<name>" --k 5 --json to CHECK duplicates; if found, USE --force-merge to UPDATE
AFTER creating or updating memory → VERIFY with read --name <name> --json | jaq '{name, description, body_length}'
AFTER EVERY turn with new findings → EVALUATE whether to persist via remember --force-merge; if nothing new, DECLARE "No new findings to persist"
WHEN exit code is non-zero → READ JSON error envelope from stdout via jaq '{code, message, error_class}', REPORT remediation steps
WHEN exit code 9 (duplicate) → RETRY with --force-merge
WHEN exit code 19 (SHUTDOWN) → RETRY MANDATORY; partial work discarded
WHEN exit code 75 (singleton locked) → WAIT and retry; NEVER increase concurrency
WHEN exit code 16 (preflight) → FIX MCP config; NEVER bypass with SKIP_PREFLIGHT
ALWAYS parse JSON output with jaq (NEVER jq)
ALWAYS pass --json flag on every sqlite-graphrag invocation
ALWAYS use --llm-backend codex --llm-model gpt-5.4-mini OR --llm-backend claude --llm-model claude-sonnet-4-6 OR --llm-backend opencode --llm-model opencode/big-pickle for embedding commands
ALWAYS use canonical relations ONLY: applies-to, uses, depends-on, causes, fixes, contradicts, supports, follows, related, mentions, replaces, tracked-in
ALWAYS map non-canonical relations BEFORE persisting: adds|creates → causes, implements → supports, blocks → contradicts, tested-by → related, part-of → applies-to
ALWAYS normalize entity names to kebab-case ASCII lowercase BEFORE passing to CLI
NEVER use MCP Serena or .md memory files for persistence
NEVER write MEMORY.md or any file-based memory
NEVER start or reference daemon (REMOVED)
NEVER pass ANTHROPIC_API_KEY or OPENAI_API_KEY in environment
PREFER remember --force-merge over edit for updates to ensure re-indexation
PREFER --graph-stdin with curated entities over --enable-ner for extraction quality
LIMIT graph entities to domain-specific concepts: projects, tools, people, decisions, files, incidents
REJECT generic words, pronouns, UUIDs, hashes, timestamps as entity names

Architecture and Principles

INVOKE always as subprocess; READ stdout for JSON/NDJSON; READ stderr for logs; CHECK exit code BEFORE parsing
KNOW BUILD is LLM-only one-shot; binary has NO daemon, NO ONNX runtime, NO model cache
KNOW COSINE similarity is pure Rust over BLOB-backed memory_embeddings, entity_embeddings, chunk_embeddings
KNOW SCHEMA is v15 after init or migrate on fresh database
ENFORCE OAUTH-ONLY: spawn ABORTS exit 1 if ANTHROPIC_API_KEY or OPENAI_API_KEY is set
KNOW ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, OPENAI_BASE_URL are PRESERVED for custom providers (OpenRouter, Bedrock)
KNOW hardening flags are ALWAYS passed to claude -p and codex exec subprocesses
KNOW subprocess CWD is ISOLATED to temp dir via apply_cwd_isolation; CLAUDE_CONFIG_DIR set to isolation dir
KNOW orphan spawn directories are cleaned via cleanup_isolation_dirs
KNOW 7 preflight guards run BEFORE every LLM subprocess fork: check_argv_size, check_binary_exists, check_mcp_config_inline, check_mcp_config_path, check_walkup_mcp_json, check_output_buffer, check_claude_config_dir
KNOW exit code 16 (EX_CONFIG) is the universal preflight failure code; READ error envelope for variant-specific remediation
SET SQLITE_GRAPHRAG_SKIP_PREFLIGHT=1 ONLY in emergencies
ISOLATE NAMESPACE per project via --namespace <ns> or env; default is global
NEVER expose the binary as MCP server or HTTP service
NEVER write .sqlite file in parallel to the binary or from another tool
USE MOCK LLM CLI for CI: prepend tests/mock-llm to PATH

Backend LLM Selection

PASS --llm-backend codex to spawn Codex CLI headless (DEFAULT backend)
PASS --llm-backend claude to spawn Claude Code headless via embed_via_claude_local (zero-token, OAuth-compatible)
PASS --llm-backend opencode to spawn OpenCode CLI headless (own auth system, NOT OAuth)
PASS --llm-backend codex,claude for codex-first with claude fallback
PASS --llm-backend codex,claude,opencode,none for full fallback chain with null embedding last resort
PASS --llm-model <MODEL> to select embedding model for the active backend
KNOW DEFAULT models: codex=gpt-5.5, claude=claude-sonnet-4-6, opencode=opencode/big-pickle
PASS --llm-fallback-mode <claude|codex|opencode> to swap backend mid-job on rate-limit
PASS --skip-embedding-on-failure ONLY when --llm-backend …,none is active
PASS --dry-run-backend to plan backend operation without executing (idempotent preview)
PARSE backend_invoked field in every embedding envelope to CONFIRM which backend ran
PASS --codex-binary <PATH>, --claude-binary <PATH>, --opencode-binary <PATH> to override binary locations
PASS --opencode-model <MODEL> and --opencode-timeout <SECONDS> for opencode-specific tuning
PASS --mode codex|claude-code|opencode for ingest and enrich extraction pipelines
KNOW opencode NDJSON output has 3 event types: step_start, text, step_finish
KNOW opencode free models: opencode/big-pickle, opencode/deepseek-v4-flash-free, opencode/mimo-v2.5-free, opencode/nemotron-3-ultra-free, opencode/north-mini-code-free
RUN codex login to refresh codex OAuth; refresh claude OAuth when stale
NEVER pass API keys with any backend; spawn ABORTS exit 1

Global Flags Reference

--db <PATH> — override database location (NOT global; each subcommand accepts independently)
--namespace <ns> — scope operations to a namespace
--lang en|pt — force stderr language
--tz <TIMEZONE> — localize timestamps
--json — structured JSON output (ALWAYS pass)
--low-memory — unitary parallelism for constrained containers
--max-concurrency N — cap concurrent heavy CLI invocations
--wait-lock SECS — widen lock acquisition window
--llm-parallelism N — cap embedding subprocess fan-out (default 4, clamp [1, 32])
--llm-backend <chain> — backend selection with comma-separated fallback
--llm-model <MODEL> — embedding model for active backend
--dry-run-backend — plan backend operation without executing
--llm-fallback-mode <backend> — swap backend mid-job on rate-limit
--llm-fallback <chain> — comma-separated fallback chain tried when primary fails (default codex,claude,none)
--llm-slot-no-wait — fail immediately exit 75 when no LLM slot free (instead of waiting)
--embedding-dim N — embedding dimensionality override [8, 4096] (default 64 MRL)
--graceful-shutdown-secs N — cleanup budget before SIGKILL
--skip-embedding-on-failure — exit 0 on embedding failure (ONLY with fallback ending in none)
--strict-env-clear — preserve only PATH in subprocess for compliance
--codex-binary, --claude-binary, --opencode-binary — override binary paths
--opencode-model, --opencode-timeout — opencode-specific overrides
-v/-vv/-vvv — info/debug/trace logging on stderr

CRUD Write Path (remember, remember-batch, ingest)

INVOKE remember --name <kebab> --type <kind> --description <text> with --body <text> or --body-file <path> or --body-stdin
INVOKE remember --graph-stdin to attach {body, entities, relationships} in single JSON
PASS entities as [{name, entity_type}] in kebab-case ASCII
PASS relationships as [{source, target, relation, strength}] where strength in [0.0, 1.0]
PASS --force-merge for idempotent updates and soft-deleted restoration
PASS --clear-body to wipe body during --force-merge update
PASS --dry-run to validate inputs without persisting
PASS --max-rss-mb <MiB> to abort when RSS exceeds threshold (default 8192)
RESPECT 512000 bytes and 512 chunks limit per body
VALID --type values: user, feedback, project, reference, decision, incident, skill, document, note
USE --enable-ner for URL-regex entity extraction (URL-regex ONLY since NER removal)
INVOKE remember-batch for 10+ memories via NDJSON stdin; EXPECT per-item status and summary line
INVOKE ingest <DIR> --recursive --pattern "*.md" to import directory
PASS --type <kind> to apply same type to all ingested files
PASS --mode codex|claude-code|opencode for LLM-curated entity extraction
USE --auto-describe (default true) to extract description from first body line; opt out via --no-auto-describe
USE --resume to continue from queue after interruption; --retry-failed for failed files only
USE --fail-fast to stop at first per-file failure
USE --max-name-length N to override default name truncation at 60 chars
USE --llm-parallelism N on ingest (default 2); --ingest-parallelism N for per-file parallelism
PASS --claude-model <MODEL> and --claude-timeout <secs> (default 300) for --mode claude-code
PASS --codex-model <MODEL> and --codex-timeout <secs> (default 300) for --mode codex
PASS --rate-limit-wait <secs> (default 60) for initial wait on rate-limit with --mode claude-code
PASS --queue-db <path> for custom queue DB; --keep-queue to preserve it after completion
PASS --low-memory on ingest for single-threaded mode (3-4x slower, <4 GB RAM)
PASS --dry-run on ingest to preview file-to-name mapping without persisting
RESPECT --max-files 10000 cap as all-or-nothing validation
NEVER mix --body, --body-file, --body-stdin, --graph-stdin in single invocation
NEVER pass empty body with no entities via --graph-stdin
NEVER use fd | xargs remember; INVOKE ingest instead
NEVER use --force-merge in ingest (exclusive to remember)

CRUD Read, Update, Delete

INVOKE read --name <kebab> --json for O(1) fetch; read --id <N> for lookup by memory_id
PASS --with-graph to include linked entities and relationships
INVOKE list --type <kind> --limit N --offset N --json to filter and paginate
PASS --include-deleted to include soft-deleted memories
INVOKE history --name <n> --diff --json for version history with character diff stats
INVOKE edit --name <n> --body-file <path> to update body (re-embeds automatically)
USE --description <text> to update description only (no re-embed)
USE --type <kind> to change memory type without recreating
USE --force-reembed to regenerate embedding without body change
USE --expected-updated-at <ts> for optimistic locking; TREAT exit 3 as conflict
INVOKE rename --from <old> --to <new> to rename preserving history
INVOKE restore --name <n> --version <N> to restore old version
INVOKE forget --name <n> for reversible soft-delete; TREAT exit 4 as absent
INVOKE purge --retention-days <N> --yes for hard delete; USE --dry-run first
INVOKE unlink --from <a> --to <b> --relation <type> for edge removal; --entity <name> --all for bulk
INVOKE prune-relations --relation <type> --yes for bulk deletion; --show-entities --dry-run to preview
INVOKE cleanup-orphans --yes after bulk forget; then vacuum --json
NEVER skip optimistic locking in concurrent pipelines
NEVER delete manually via sqlite3 shell

Entity Graph Operations

INVOKE link --from <a> --to <b> --relation <type> --create-missing --weight <float> to create edge
PASS --entity-type <kind> for auto-created entities (default concept)
PASS --max-entity-degree N to warn when entity exceeds N connections
USE --strict-relations to fail on non-canonical relation types
INVOKE graph entities --json to list entities; ACCESS via .entities[] (NOT .items[])
SORT via --sort-by degree|name|created_at; PAGINATE via --limit N --offset N
INVOKE graph stats --json to inspect node_count, edge_count, avg_degree, max_degree
KNOW entity degree is calculated via accurate COUNT query (recalculate_degree)
INVOKE graph traverse --from <root> --depth <N> --json for subgraph traversal
USE --format json|dot|mermaid with --output <path> to export graph
INVOKE memory-entities --name <memory> for forward lookup; --entity <name> for reverse
INVOKE rename-entity, delete-entity --cascade, merge-entities --names "a,b,c" --into <target>
INVOKE reclassify --name <n> --new-type <kind> or --from-type <old> --to-type <new> --batch
INVOKE reclassify-relation --from-relation <old> --to-relation <new> --batch for bulk relation type migration
INVOKE normalize-entities --yes to normalize all names to kebab-case ASCII
INVOKE prune-ner --entity <n> to remove NER bindings; prune-ner --all --yes for all in namespace
VALIDATE entity names: minimum 2 chars, no newlines, no short ALL_CAPS (4 chars or less REJECTED)
CANONICAL relations: applies-to, uses, depends-on, causes, fixes, contradicts, supports, follows, related, mentions, replaces, tracked-in
CANONICAL entity types: project, tool, person, file, concept, incident, decision, memory, dashboard, issue_tracker, organization, location, date
NEVER use mentions as default relation

GraphRAG Search (recall, hybrid-search, related, deep-research, enrich)

USE canonical three-layer pattern: hybrid-search then read --name then related|graph traverse
INVOKE recall <query> --k N for pure semantic KNN; PASS --no-graph to disable graph expansion
INTERPRET distance increasing as similarity decreasing; score = 1.0 - distance clamped [0.0, 1.0]
INVOKE hybrid-search <query> --k N for FTS5+KNN fusion via RRF
PASS --rrf-k 60 for standard fusion; --weight-vec 1.0 --weight-fts 1.0 for balanced
PASS --type <kind> to filter results by memory type
PASS --fallback-fts-only to skip live embedding and serve FTS5 BM25 only (offline mode)
USE --with-graph --max-hops 2 --min-weight 0.3 for graph expansion; READ BOTH results[] AND graph_matches[]
INVOKE related <name> --hops N for multi-hop traversal from memory
INVOKE deep-research "<query>" --k 20 --max-hops 3 --max-sub-queries 7 --max-results 50 for parallel multi-hop research
PASS --graph-decay <float> (default 0.7) for score decay per hop; --graph-min-score <float> (default 0.05) for minimum threshold
PASS --max-neighbors-per-hop N to limit neighbours per entity per hop
PASS --timeout <secs> (default 30) for per sub-query timeout
PASS --with-bodies to include full memory bodies in results
INVOKE enrich --operation <op> for LLM graph quality: memory-bindings, entity-descriptions, body-enrich, re-embed --limit N --resume
PASS --llm-parallelism N to control concurrent LLM subprocesses
PASS --max-cost-usd N to cap accumulated LLM cost (ignored for OAuth users)
USE --dry-run to preview without spawning LLM
PARSE top fields: recall returns results[].{name, snippet, distance, score, source}; hybrid-search returns results[].{name, combined_score, vec_rank, fts_rank}
PARSE deep-research returns sub_queries[], results[], evidence_chains[], graph_context, stats
NEVER confuse distance with combined_score in ranking
NEVER increase --hops without inspecting graph stats first

Exit Codes and Retry Strategy

EXIT 0: success; EXIT 1: validation error; EXIT 2: argument parsing; EXIT 3: optimistic lock conflict (reload and retry)
EXIT 4: not found; EXIT 5: namespace error; EXIT 6: payload too large; EXIT 9: duplicate (use --force-merge)
EXIT 10: database error (run vacuum + health); EXIT 11: embedding failure (check backend + OAuth)
EXIT 13: partial batch failure (reprocess failed only); EXIT 14: I/O error; EXIT 15: database busy (widen --wait-lock)
EXIT 16: preflight failure (fix MCP config, NEVER treat as transient)
EXIT 19: SHUTDOWN (RETRY MANDATORY, partial work discarded); PARSE envelope {error, code, signal, graceful, message}
EXIT 20: internal error; EXIT 75: slots exhausted or job singleton locked (respect cooldown, NEVER retry immediately)
EXIT 77: RAM pressure (wait for free memory)
NEVER ignore non-zero exit; NEVER reprocess full batch after exit 13; NEVER confuse exit 1 with exit 9

Concurrency and Parallelism

RESPECT hard ceiling 2 x nCPUs for heavy commands: init, remember, ingest, recall, hybrid-search
SET --llm-parallelism N default 4 on remember/edit, default 2 on ingest (clamp [1, 32])
USE --llm-max-host-concurrency N to cap cross-process LLM subprocesses
USE --llm-slot-wait-secs N to wait for slot or --llm-slot-no-wait to abort
KNOW JOB SINGLETON: enrich, ingest --mode claude-code|codex|opencode acquire per-namespace singleton
USE --wait-job-singleton SECS or --force-job-singleton to break stale lock
ENABLE SQLITE_GRAPHRAG_LOW_MEMORY=1 for unitary parallelism (3-4x slower)
NEVER run enrich in parallel against same database

Maintenance and Diagnostic Subcommands

RUN sqlite-graphrag init --namespace <ns> on first use
RUN health --json to verify integrity_ok, schema_ok, schema_version >= 15
RUN migrate --dry-run --json to preview; then migrate --json after binary upgrade
RUN optimize --json to refresh planner stats; includes fts_rebuilt
RUN fts rebuild --json when health.fts_degraded is true; fts check --json for integrity; fts stats --json for row counts
INVOKE backup --output <path> --json for online backup; sync-safe-copy --dest <path> for atomic snapshot
INVOKE export --namespace <ns> --type <kind> --json to export as NDJSON
INVOKE vacuum --json after large purge; INSPECT wal_size_mb in health for fragmentation
INVOKE vec orphan-list --json then vec purge-orphan --yes to clean orphaned vectors; vec stats --json for health
INVOKE debug-schema --json for schema drift troubleshooting
INVOKE completions <bash|zsh|fish|elvish|powershell> for shell completions
INVOKE codex-models --json to inspect codex model whitelist
INVOKE stats --json to show database statistics (counts, sizes, namespace breakdown)
INVOKE namespace-detect --json to resolve namespace precedence for current invocation
INVOKE cache list --json to list cached model files; cache clear-models --yes to force re-download
INVOKE pending list --filter-status queued --json to inspect three-stage checkpoint queue; pending show <id> for detail; pending cleanup --yes for terminal rows
INVOKE pending-embeddings list --json to inspect failed embedding retry queue; pending-embeddings process --json to reprocess with next backend
INVOKE slots status --json to inspect host-wide semaphore; slots release --slot-id <N> --yes to reap orphan slots
INVOKE embedding status --json for aggregate counts by status; embedding list --json for per-entry inspection
SCHEDULE weekly: purge then cleanup-orphans then prune-relations --relation mentions then vacuum then optimize then sync-safe-copy
KNOW every write runs PRAGMA wal_checkpoint(TRUNCATE) after commit
IF corruption: sqlite3 broken.sqlite ".recover" | sqlite3 repaired.sqlite

Environment Variables Reference

SQLITE_GRAPHRAG_DB_PATH — persistent database path override
SQLITE_GRAPHRAG_NAMESPACE — persistent namespace
SQLITE_GRAPHRAG_LLM_BACKEND — persistent backend (codex|claude|opencode|none|auto)
SQLITE_GRAPHRAG_LLM_MODEL — persistent model override
SQLITE_GRAPHRAG_CODEX_BINARY / SQLITE_GRAPHRAG_CODEX_EMBED_MODEL — codex binary and embed model
SQLITE_GRAPHRAG_CLAUDE_BINARY — claude binary path override
SQLITE_GRAPHRAG_OPENCODE_BINARY / SQLITE_GRAPHRAG_OPENCODE_MODEL / SQLITE_GRAPHRAG_OPENCODE_EMBED_MODEL / SQLITE_GRAPHRAG_OPENCODE_TIMEOUT — opencode overrides
SQLITE_GRAPHRAG_EMBEDDING_DIM — embedding dimension [8, 4096] (default 64 MRL)
SQLITE_GRAPHRAG_LOW_MEMORY — enable unitary parallelism
SQLITE_GRAPHRAG_STRICT_ENV_CLEAR — compliance mode
SQLITE_GRAPHRAG_DISPLAY_TZ — persistent timezone
SQLITE_GRAPHRAG_LOG_FORMAT — json for log aggregators
SQLITE_GRAPHRAG_SKIP_PREFLIGHT — bypass preflight (EMERGENCIES ONLY)
SQLITE_GRAPHRAG_IGNORE_SHUTDOWN — CI test harnesses ONLY

Ready-to-Use CLI Formulas

INIT namespace: sqlite-graphrag init --namespace <ns>
VERIFY health: sqlite-graphrag health --namespace <ns> --json | jaq '{integrity_ok, schema_version}'
MIGRATE preview: sqlite-graphrag migrate --dry-run --json
MIGRATE apply: sqlite-graphrag migrate --json
REMEMBER codex all flags: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini --codex-binary <path> --llm-parallelism 4 remember --name <n> --type decision --description "desc" --body-file doc.md --force-merge --max-rss-mb 4096 --json
REMEMBER claude all flags: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 --claude-binary <path> --llm-parallelism 4 remember --name <n> --type decision --description "desc" --body "content" --force-merge --json
REMEMBER opencode all flags: sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle --opencode-binary <path> --opencode-timeout 300 --llm-parallelism 4 remember --name <n> --type note --description "desc" --body-stdin --json
REMEMBER graph-stdin: echo '{"body":"text","entities":[{"name":"jwt","entity_type":"concept"}],"relationships":[{"source":"jwt","target":"auth-svc","relation":"uses","strength":0.8}]}' | sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini remember --name <n> --type decision --description "desc" --graph-stdin --force-merge --json
REMEMBER-BATCH: pipe NDJSON to sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini remember-batch --json
FULL FALLBACK CHAIN: sqlite-graphrag --llm-backend codex,claude,opencode,none --skip-embedding-on-failure remember --name <n> --type note --description "desc" --body-file note.md --json
DRY-RUN backend: sqlite-graphrag --llm-backend codex --dry-run-backend recall "query" --k 5 --json
RECALL codex: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini recall "query" --k 5 --no-graph --json
RECALL claude: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 recall "query" --k 5 --json
RECALL opencode: sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle recall "query" --k 5 --json
HYBRID-SEARCH codex all flags: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini hybrid-search "query" --k 10 --with-graph --max-hops 2 --min-weight 0.3 --rrf-k 60 --weight-vec 1.0 --weight-fts 1.0 --type decision --json
HYBRID-SEARCH claude: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 hybrid-search "query" --k 10 --json
HYBRID-SEARCH opencode: sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle hybrid-search "query" --k 10 --with-graph --json
HYBRID-SEARCH fts-only: sqlite-graphrag hybrid-search "query" --k 10 --fallback-fts-only --json
DEEP-RESEARCH all flags: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 deep-research "question" --k 20 --max-hops 3 --max-sub-queries 7 --max-results 50 --with-bodies --graph-decay 0.7 --graph-min-score 0.05 --timeout 30 --max-neighbors-per-hop 10 --json
RELATED: sqlite-graphrag related <name> --hops 2 --relation uses --json
INGEST codex all flags: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini ingest ./docs --mode codex --recursive --pattern "*.md" --type document --auto-describe --resume --max-files 1000 --max-name-length 80 --llm-parallelism 2 --codex-model gpt-5.4-mini --codex-timeout 300 --fail-fast --low-memory --json
INGEST claude all flags: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 ingest ./docs --mode claude-code --recursive --pattern "*.md" --type document --auto-describe --resume --claude-model claude-sonnet-4-6 --claude-timeout 600 --rate-limit-wait 60 --max-cost-usd 5 --queue-db .ingest-queue.sqlite --keep-queue --json
INGEST opencode all flags: sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle ingest ./docs --mode opencode --recursive --pattern "*.md" --type document --auto-describe --opencode-model opencode/big-pickle --opencode-timeout 600 --json
INGEST dry-run: sqlite-graphrag ingest ./docs --dry-run --pattern "*.md" --recursive --json
ENRICH re-embed codex: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini enrich --operation re-embed --limit 100 --resume --llm-parallelism 4 --json
ENRICH memory-bindings claude: sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 enrich --operation memory-bindings --mode claude-code --max-cost-usd 5 --json
ENRICH opencode: sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle enrich --operation entity-descriptions --mode opencode --dry-run --json
READ with graph: sqlite-graphrag read --name <n> --with-graph --json
READ by id: sqlite-graphrag read --id 42 --json
LIST: sqlite-graphrag list --type decision --limit 50 --offset 0 --include-deleted --json
HISTORY: sqlite-graphrag history --name <n> --diff --json
EDIT body codex: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini edit --name <n> --body-file new.md --expected-updated-at "2026-01-01T00:00:00Z" --json
EDIT description only: sqlite-graphrag edit --name <n> --description "new desc" --json
EDIT force-reembed: sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini edit --name <n> --force-reembed --json
RENAME: sqlite-graphrag rename --from <old> --to <new> --json
RESTORE: sqlite-graphrag restore --name <n> --version 2 --json
FORGET: sqlite-graphrag forget --name <n> --json
PURGE preview: sqlite-graphrag purge --retention-days 30 --yes --dry-run --json
LINK all flags: sqlite-graphrag link --from <a> --to <b> --relation uses --weight 0.8 --create-missing --entity-type tool --strict-relations --max-entity-degree 50 --json
UNLINK: sqlite-graphrag unlink --from <a> --to <b> --relation uses --json
UNLINK bulk: sqlite-graphrag unlink --entity <name> --all --json
GRAPH stats: sqlite-graphrag graph stats --json | jaq '{node_count, edge_count, avg_degree}'
GRAPH entities: sqlite-graphrag graph entities --sort-by degree --order desc --limit 20 --json
GRAPH traverse: sqlite-graphrag graph traverse --from <entity> --depth 2 --json
GRAPH export: sqlite-graphrag graph --format <json|dot|mermaid> --output <path>
MERGE entities: sqlite-graphrag merge-entities --names "a,b,c" --into target --json
NORMALIZE entities: sqlite-graphrag normalize-entities --yes --json
RECLASSIFY entity: sqlite-graphrag reclassify --name <n> --new-type concept --json
RECLASSIFY batch: sqlite-graphrag reclassify --from-type tool --to-type concept --batch --json
RECLASSIFY-RELATION: sqlite-graphrag reclassify-relation --from-relation <old> --to-relation <new> --batch --json
PRUNE-NER: sqlite-graphrag prune-ner --entity <n> or prune-ner --all --yes
PRUNE-RELATIONS preview: sqlite-graphrag prune-relations --relation mentions --yes --show-entities --dry-run
CLEANUP pipeline: INVOKE forget --name <n> then cleanup-orphans --yes --json then vacuum --json
PENDING list: sqlite-graphrag pending list --filter-status queued --json
PENDING-EMBEDDINGS: sqlite-graphrag pending-embeddings list --json then pending-embeddings process --json
SLOTS: sqlite-graphrag slots status --json and slots release --slot-id <N> --yes --json
EMBEDDING status: sqlite-graphrag embedding status --json and embedding list --json
FTS: sqlite-graphrag fts rebuild --json and fts check --json and fts stats --json
VEC: sqlite-graphrag vec stats --json and vec orphan-list --json then vec purge-orphan --yes --json
BACKUP: sqlite-graphrag backup --output backup.sqlite --json
SYNC-SAFE-COPY: sqlite-graphrag sync-safe-copy --dest snapshot.sqlite
EXPORT: sqlite-graphrag export --namespace <ns> --type decision --json
OPTIMIZE: sqlite-graphrag optimize --json
VACUUM: sqlite-graphrag vacuum --json
DEBUG-SCHEMA: sqlite-graphrag debug-schema --json
CODEX-MODELS: sqlite-graphrag codex-models --json
COMPLETIONS: sqlite-graphrag completions <bash|zsh|fish|elvish|powershell>
STATS: sqlite-graphrag stats --json
NAMESPACE-DETECT: sqlite-graphrag namespace-detect --json
CACHE list: sqlite-graphrag cache list --json
CACHE clear: sqlite-graphrag cache clear-models --yes
FALLBACK CHAIN: sqlite-graphrag --llm-backend codex --llm-fallback codex,claude,opencode,none --skip-embedding-on-failure remember --name <n> --type note --description "desc" --body-file note.md --json

Active Rules

ALWAYS pass --llm-backend and --llm-model explicitly for embedding commands
ALWAYS parse backend_invoked to confirm which backend ran
ALWAYS run codex login or refresh claude OAuth when backend reports stale OAuth
NEVER pass API keys (OAuth-only, exit 1); NEVER use daemon, --bare, --gliner-variant (REMOVED)
NEVER install with --features embedding-legacy or --features ner-legacy
NEVER run enrich in parallel against same database; NEVER write .sqlite outside the binary
NEVER ignore exit 19 (RETRY MANDATORY) or exit 16 (fix MCP config)
NEVER call migrate --to-llm-only without --drop-vec-tables guard