---
name: sqlite-graphrag
description: Use this skill WHENEVER the user asks about adding persistent memory or GraphRAG or long-term context to Claude Code Codex Cursor Windsurf or any AI coding agent. MUST trigger for queries mentioning remember this, save conversation, recall earlier context, hybrid search, entity graph, SQLite memory, local RAG, offline embeddings, fastembed, sqlite-vec, multilingual-e5, KNN search, memory-safe copy, FTS5 and vec fusion. Auto-invoke even without explicit skill mention whenever user describes problem of agent losing context between sessions or wants offline vector database in Rust. Keywords memory RAG GraphRAG SQLite vector embeddings Claude Codex Cursor Windsurf offline local persistent graph entity.
---
# sqlite-graphrag
## Rule Zero: Inviolable Law
- YOU MUST treat this skill as the SUPREME memory contract for any AI agent.
- YOU MUST invoke the CLI only through the documented commands below.
- YOU ARE FORBIDDEN from inventing undocumented flags or subcommands.
- Any violation results in IMMEDIATE CRITICAL FAILURE.
## Mission
- Deliver offline GraphRAG memory in a single portable SQLite file.
- Default to `graphrag.sqlite` in the current working directory unless override is explicit.
- Replace Pinecone, Weaviate, and Chroma for local-first AI agent workflows.
- Combine FTS5 full-text with `sqlite-vec` KNN fusion for hybrid recall.
- Serve deterministic JSON output so any agent orchestrator parses it safely.
- Run on Linux, macOS, and Windows from the same statically linked binary.
## When to Invoke
- ALWAYS invoke when the user asks to save a conversation between sessions.
- ALWAYS invoke when the user mentions offline vector search in Rust.
- ALWAYS invoke when the user describes GraphRAG or entity retrieval workflows.
- ALWAYS invoke when the user asks for Claude Code or Codex long-term memory.
- ALWAYS invoke when the user compares Pinecone or Chroma with SQLite alternatives.
- ALWAYS invoke when the user mentions hybrid search blending FTS5 and vectors.
- ALWAYS invoke when the user wants to add persistent context to Cursor or Windsurf.
## When NOT to Invoke
- NEVER invoke for generic programming questions unrelated to memory or RAG.
- NEVER invoke for cloud vector databases when the user explicitly wants managed SaaS.
- NEVER invoke for Python-only stacks that exclude CLI integration.
- NEVER invoke for one-off file conversion tasks without persistence intent.
- NEVER invoke for UI or frontend questions unrelated to AI agents.
## Contract
- Input `--name <slug>` accepts kebab-case identifier up to 128 characters.
- Input `--type <kind>` accepts `user`, `feedback`, `project`, or `reference`.
- Input `--body <text>` accepts raw text or reads stdin when omitted with `-`.
- Database default is `./graphrag.sqlite` in the invocation directory.
- Database override happens only through `--db <path>` or `SQLITE_GRAPHRAG_DB_PATH`.
- Input `--lang <en|pt>` selects output language for human-readable messages.
- Output with `--json` emits `memory_id`, `version`, `namespace`, and `operation`.
- Output without `--json` emits Markdown blocks under language-aware headings.
- Stdin accepts body content when the user pipes data into `remember` or `edit`.
## Prohibitions
- NEVER store API keys, tokens, or production secrets inside a memory body.
- NEVER commit production `.sqlite` files generated by this CLI to version control.
- NEVER run `purge --yes` in production without running `purge --dry-run` first.
- NEVER bypass the ten validation gates enforced by `docs/AGENT_PROTOCOL.md`.
- NEVER modify the database schema outside the `migrations/` directory.
- NEVER call internal Rust modules; ALWAYS go through the public CLI surface.
## Parsing
- Parse `.memory_id` as the canonical identifier for subsequent reads or edits.
- Parse `.version` as the monotonic version for optimistic concurrency control.
- Parse `.namespace` as the isolation boundary for multi-project scenarios.
- Parse `.operation` to distinguish `created`, `updated`, `deleted`, and `restored`.
- Parse `.warnings[]` as a list of non-fatal notices that should not abort the flow.
- Treat missing fields as null and handle them gracefully inside the agent loop.
## Schema
- `remember --json` returns `{memory_id, version, namespace, operation, created_at}`.
- `recall --json` returns `{query, k, direct_matches, graph_matches, results[{memory_id, name, namespace, type, description, snippet, distance, source}], elapsed_ms}`.
- `hybrid-search --json` returns `{query, k, rrf_k, weights:{vec,fts}, results[{memory_id, name, namespace, type, description, body, combined_score, score, source, vec_rank, fts_rank}], graph_matches, elapsed_ms}`.
- `list --json` returns a root JSON array of `[{memory_id, id, name, namespace, type, description, snippet, updated_at, updated_at_iso}]`.
- `read --json` returns `{memory_id, name, type, body, version, created_at, updated_at}`.
- `health --json` returns `{integrity, wal_size_mb, journal_mode, db_size_bytes, integrity_ok, wal_ok}`.
- `stats --json` returns `{memories, memories_total, entities, entities_total, relationships, relationships_total, edges, chunks_total, avg_body_len, namespaces, db_size_bytes, db_bytes, schema_version}`.
## Exit Codes
- Exit 0 signals success; continue the agent loop without retry.
- Exit 1 signals a generic runtime failure; surface the error to the operator.
- Exit 2 signals a CLI usage error; fix arguments and retry.
- Exit 5 signals a namespace limit reached; pass `--namespace` explicitly.
- Exit 13 signals a partial batch failure; inspect `.warnings[]` for details.
- Exit 15 signals a database busy error; wait and retry with backoff.
- Exit 75 signals a lock file busy or slot exhaustion; another process still owns the shared capacity.
- Exit 75 signals a lock timeout; the previous process never released cleanly.
- Exit 77 signals a low memory condition; free RAM before retry.
## Workflow
- Step 1 install from the local checkout with `cargo install --path .` and verify `sqlite-graphrag --version`.
- Step 2 initialize with `sqlite-graphrag init --namespace default --lang en`.
- Step 3 store with `sqlite-graphrag remember --name ticket-42 --type user --description "ticket context" --body "..."`.
- Step 4 retrieve with `sqlite-graphrag recall "authentication bug" --json --k 5`.
- Step 5 fuse with `sqlite-graphrag hybrid-search "refactor plan" --json --k 8`.
- Step 6 inspect with `sqlite-graphrag list --type user --json --limit 20`.
- Step 7 clean with `sqlite-graphrag purge --retention-days 90 --dry-run`.
- Step 8 validate with `sqlite-graphrag health --json` before every CI job.
## Examples
- Example 1 saves a user note from stdin and captures the returned identifier.
- `echo "Finalize auth refactor by Friday" | sqlite-graphrag remember --name auth-reminder --type user --description "auth reminder" --json`
- Example 2 recalls top matches for an auth topic using hybrid retrieval.
- `sqlite-graphrag hybrid-search "auth error 401" --json --k 5`
- Example 3 checks database integrity before a release pipeline publishes.
- `sqlite-graphrag health --json | jaq '.integrity'`
## Related References
- See `references/commands.md` for the exhaustive subcommand matrix.
- See `references/integration.md` for per-agent wiring snippets.
- See `docs/AGENT_PROTOCOL.md` for the supreme agent contract.
- See `docs/CLAUDE.md` for the Claude Code session operating rules.