# HOW TO USE neurographrag
> Ship persistent memory to any AI agent in 60 seconds flat, zero dollars spent
- Read this guide in Portuguese at [HOW_TO_USE.pt-BR.md](HOW_TO_USE.pt-BR.md)
- Return to the main [README.md](../README.md) for command reference
## The Question That Starts Here
### Curiosity — Why Engineers Abandon Pinecone in 2026
- How many milliseconds separate your agent from production memory today
- Why senior engineers in production choose SQLite over Pinecone for LLM memory
- What changes when embeddings, search and graph live inside a single file
- Why twenty one AI agents converge on neurographrag as their persistence layer
- This guide answers every question above in under ten minutes of reading
## Reading Time and Impact
### Investment — Five Minutes to Read Ten to Execute
- Total reading time reaches five minutes for technical readers skimming headings
- Total execution time reaches ten minutes including model download on first run
- Learning curve drops to zero for anyone familiar with standard CLI patterns
- First memory gets persisted in sixty seconds after install completes
- First hybrid search returns ranked hits in under fifty milliseconds locally
- Expected tokens saved per month hit two hundred thousand on a single agent
## Prerequisites
### Environment — Minimum Supportable Baseline
- Rust 1.88 or newer installed via `rustup` across Linux macOS and Windows
- SQLite version 3.40 or newer shipped with your operating system distribution
- Operating systems Linux glibc, Linux musl, macOS 11 plus, Windows 10 plus
- Available RAM of 100 MB free for runtime plus 1 GB during embedding model load
- Disk space of 200 MB for the embedding model cache on first invocation
- Network access required ONLY for first `init` to download quantized embeddings
## First Command in 60 Seconds
### Install — Three Shell Lines You Copy Once
```bash
cargo install --locked neurographrag
neurographrag init
neurographrag remember --name first-note --type user --description "first memory" --body "hello graphrag"
```
- First line downloads, builds and installs the binary into `~/.cargo/bin`
- Second line creates the SQLite database and downloads the embedding model
- Third line persists your first memory and indexes it for hybrid retrieval
- Confirmation prints to stdout, traces route to stderr, exit code zero signals success
- Your next `recall` call returns the note you just saved in milliseconds
## Core Commands
### Lifecycle — Seven Subcommands You Use Daily
```bash
neurographrag init --namespace my-project
neurographrag remember --name auth-design --type decision --description "auth uses JWT" --body "Rationale documented."
neurographrag recall "authentication strategy" --k 5 --json
neurographrag hybrid-search "jwt design" --k 10 --rrf-k 60 --json
neurographrag read --name auth-design
neurographrag forget --name auth-design
neurographrag purge --days 30 --yes
```
- `init` bootstraps the database, downloads the model and validates the `sqlite-vec` extension
- `remember` stores content, extracts entities and generates embeddings atomically
- `recall` performs pure vector KNN search over the `vec_memories` table
- `hybrid-search` fuses FTS5 full-text and vector KNN with Reciprocal Rank Fusion
- `read` fetches a memory by its exact kebab-case name in a single SQL query
- `forget` performs a soft delete preserving the full version history
- `purge` permanently removes memories soft-deleted more than the retention threshold
## Advanced Patterns
### Recipe One — Hybrid Search With Weighted Fusion
```bash
neurographrag hybrid-search "postgres migration strategy" \
--k 20 \
--rrf-k 60 \
--weight-vec 0.7 \
--weight-fts 0.3 \
--json \
- Combines dense vector similarity and sparse full-text matches in one ranked list
- Weight tuning lets you favor semantic proximity against keyword precision per query
- RRF constant `--rrf-k 60` matches the default recommended by the RRF paper
- Pipeline saves eighty percent of tokens compared to LLM-based re-ranking
- Expected latency stays under fifteen milliseconds for databases up to 100 MB
### Recipe Two — Graph Traversal for Multi-Hop Recall
```bash
neurographrag link --source auth-design --target jwt-spec --relation depends-on
neurographrag link --source jwt-spec --target rfc-7519 --relation references
neurographrag related auth-design --hops 2 --json \
- Two hops surface transitive knowledge invisible to pure vector search methods
- Typed relations let your agent reason about cause, dependency and reference chains
- Graph queries run in under five milliseconds thanks to SQLite indexed joins
- Multi-hop recall recovers context that flat embeddings consistently drop out of top-K
- Saves fifteen minutes per debugging session hunting for related architectural decisions
### Recipe Three — Batch Ingestion via Shell Pipeline
```bash
find ./docs -name "*.md" -print0 \
| xargs -0 -n 1 -P 4 -I {} bash -c '
name=$(basename {} .md)
neurographrag remember \
--name "doc-${name}" \
--type reference \
--description "imported from {}" \
--body "$(cat {})"
'
```
- Parallel factor `-P 4` matches the default counting semaphore slots exactly
- Exit code `75` signals slot exhaustion and the orchestrator should retry later
- Exit code `77` signals RAM pressure and the orchestrator must wait for free memory
- Batch throughput reaches 200 documents per minute on a modern laptop CPU
- Saves forty minutes of manual ingestion per 1000 Markdown files processed
### Recipe Four — Snapshot-Safe Sync With Dropbox or iCloud
```bash
neurographrag sync-safe-copy --dest ~/Dropbox/neurographrag.sqlite
ouch compress ~/Dropbox/neurographrag.sqlite ~/Dropbox/neurographrag-$(date +%Y%m%d).tar.zst
```
- `sync-safe-copy` checkpoints the WAL and copies a consistent snapshot atomically
- Dropbox, iCloud and Google Drive NEVER corrupt the active database during sync
- Compression via `ouch` reduces snapshot size by sixty percent for archival buckets
- Recovery on a new machine takes one `ouch decompress` plus one `cp` operation
- Protects years of memory from sync-induced corruption that plagues raw SQLite files
### Recipe Five — Integration With Claude Code Orchestrator
```bash
neurographrag recall "$USER_QUERY" --k 5 --json \
| jaq -c '{
context: [.results[] | {name, body, score}],
generated_at: now | todate
}' \
| claude --print "Use this context to answer: $USER_QUERY"
```
- Structured JSON flows cleanly into any orchestrator reading from stdin
- Score field enables the orchestrator to drop low-relevance hits before prompting
- Determinism of exit codes lets the orchestrator route errors without parsing stderr
- Token cost drops by seventy percent compared to full-corpus context stuffing
- Round-trip latency stays under one hundred milliseconds end to end locally
## Configuration and Namespace Notes
### Namespace Default
- Default namespace is `global` when `--namespace` is omitted
- Configure via `NEUROGRAPHRAG_NAMESPACE` env var to override globally
- Use `namespace-detect` to inspect the resolved namespace before running bulk operations
### Score Semantics
- JSON output uses `score` field (cosine similarity, higher is more relevant)
- Results are sorted by `score` descending so the best match always appears first
- Always prefer `--json` in pipelines to get the raw `score` for precise filtering
### Language Flag Aliases
- `--lang en` forces English output regardless of system locale
- `--lang pt`, `--lang pt-BR`, `--lang portuguese`, and `--lang PT` all force Portuguese
- Env var `NEUROGRAPHRAG_LANG=pt` overrides system locale when `--lang` is absent
- All aliases resolve to the same two internal variants: English and Portuguese
### JSON Output Flag
- `--json` is accepted by every subcommand as a no-op alias for `--format json`
- Canonical form is `--format json`; both forms produce identical output
- Use `--json` in pipelines for brevity; use `--format json` in config files for clarity
### DB Path Discovery
- All commands accept `--db <PATH>` flag in addition to `NEUROGRAPHRAG_DB_PATH` env var
- CLI flag takes precedence over environment variable
- Use `--db` when operating multiple isolated databases in parallel processes
### Concurrency Cap
- `--max-concurrency` is capped at `2×nCPUs`; higher values return exit 2
- Exit code 2 signals invalid argument; reduce the value and retry immediately
- Default of 4 slots is optimal for most laptops running two to four cores
## Reference — Subcommands Not Covered in Quick Start
### Using cleanup-orphans
- Removes entities that have no memories attached and no graph relationships
- Run periodically after bulk `forget` operations to keep the entity table lean
```bash
neurographrag cleanup-orphans --dry-run
neurographrag cleanup-orphans --yes
```
- Prerequisites: none — works on any initialized database
- `--dry-run` prints the count of orphan entities without deleting them
- `--yes` skips the interactive confirmation prompt for scripted pipelines
- Exit code 0: cleanup succeeded (or nothing to clean)
- Exit code 75: slot exhausted, retry after a short backoff
### Using edit
- Alters the body or description of an existing memory in-place creating a new version
- Use `--expected-updated-at` for optimistic locking in concurrent agent pipelines
```bash
neurographrag edit --name auth-design --body "Updated rationale after RFC review"
neurographrag edit --name auth-design --description "New short description"
neurographrag edit --name auth-design \
--body-file ./updated-body.md \
--expected-updated-at "2026-04-19T12:00:00Z"
```
- Prerequisites: the memory must already exist in the target namespace
- `--body-file` reads body content from a file, avoiding shell escaping issues
- `--body-stdin` reads body from stdin for pipeline integration
- `--expected-updated-at` accepts ISO 8601 timestamp; mismatches return exit 3
- Exit code 0: edit succeeded and new version is indexed
- Exit code 3: optimistic locking conflict — the memory was modified concurrently
### Using graph
- Exports the full entity-relationship snapshot in JSON, DOT or Mermaid format
- DOT and Mermaid formats enable visualization in Graphviz, VSCode or mermaid.live
```bash
neurographrag graph --format json
neurographrag graph --format dot --output graph.dot
neurographrag graph --format mermaid --output graph.mmd
```
- Prerequisites: at least one `link` or `remember` call must have created entities
- `--format json` (default) emits `{"nodes": [...], "edges": [...]}` to stdout
- `--format dot` emits a Graphviz-compatible directed graph for offline rendering
- `--format mermaid` emits a Mermaid flowchart block for Markdown embedding
- `--output <PATH>` writes directly to a file instead of stdout
- Exit code 0: export succeeded
### Using history
- Lists all immutable versions of a named memory in reverse chronological order
- Use the returned `version` integer with `restore` to roll back to any prior state
```bash
neurographrag history --name auth-design
```
- Prerequisites: the memory must exist and have at least one stored version
- Output is a JSON array with fields `version`, `updated_at`, and a truncated `body`
- Versions start at 1 and increment with each successful `edit` or `restore` call
- Exit code 0: history returned
- Exit code 4: memory not found in the target namespace
### Using namespace-detect
- Resolves and prints the effective namespace for the current invocation context
- Use to debug `--namespace`, `NEUROGRAPHRAG_NAMESPACE`, and auto-detect conflicts
```bash
neurographrag namespace-detect
neurographrag namespace-detect --namespace my-project
```
- Prerequisites: none — works without a database present
- Output JSON with fields `namespace`, `source`, `cwd`, `project_config_path`, and `projects_mapping_path`
- Precedence order: `--namespace` flag > `NEUROGRAPHRAG_NAMESPACE` env > auto-detect
- Exit code 0: resolution succeeded
### Using rename
- Renames a memory preserving its full version history and entity graph connections
- Use `--name`/`--old` and `--new-name`/`--new` interchangeably (aliases from v2.0.1)
```bash
neurographrag rename --name old-name --new-name new-name
neurographrag rename --old old-name --new new-name
```
- Prerequisites: the source memory must exist; the target name must be available
- `--expected-updated-at` enables optimistic locking to prevent concurrent rename conflicts
- History entries remain linked to the original name for audit trail integrity
- Exit code 0: rename succeeded
- Exit code 3: optimistic locking conflict
- Exit code 4: source memory not found
### Using restore
- Creates a new version of a memory based on an older version body without overwriting history
- Use `history` first to discover available version numbers before calling `restore`
```bash
neurographrag history --name auth-design
neurographrag restore --name auth-design --version 2
```
- Prerequisites: the memory must exist and the target version number must be valid
- Restore does NOT overwrite history — it appends a new version with the old body
- `--expected-updated-at` enables optimistic locking for concurrent pipeline safety
- Exit code 0: restore succeeded and the new version is indexed
- Exit code 4: version number not found in the history table
### Using unlink
- Removes a specific typed edge between two entities from the graph
- Use `--from`/`--source` and `--to`/`--target` interchangeably (aliases from v2.0.1)
```bash
neurographrag unlink --from auth-design --to jwt-spec --relation depends-on
neurographrag unlink --source auth-design --target jwt-spec --relation depends-on
```
- Prerequisites: the edge must exist; all three of `--from`, `--to`, and `--relation` are required
- Valid `--relation` values: `applies-to`, `uses`, `depends-on`, `causes`, `fixes`, `contradicts`, `supports`, `follows`, `related`, `mentions`, `replaces`, `tracked-in`
- Exit code 0: edge removed
- Exit code 4: edge not found
## Additional Notes on Core Commands
### Note on link
- Prerequisite: entities must exist in the graph before creating explicit links
- The `remember` command auto-extracts entities from the `--body` text during ingestion
- Create the memories that reference the entities first, then call `link` to type the edges
- Use `--from`/`--source` and `--to`/`--target` interchangeably (aliases from v2.0.1)
- JSON output: `{action, from, source, to, target, relation, weight, namespace}`
- Both `from` and `source` carry the same value; both `to` and `target` carry the same value
```bash
neurographrag remember --name auth-design --type decision --description "..." --body "Uses JWT and OAuth2."
neurographrag remember --name jwt-spec --type reference --description "..." --body "RFC 7519 defines JWT."
neurographrag link --from auth-design --to jwt-spec --relation depends-on
```
### Note on forget
- `forget` performs a soft delete; the memory disappears from `recall` and `list` results
- JSON output: `{forgotten, name, namespace}`
- Run `purge` later to hard-delete soft-deleted rows and reclaim disk space
### Note on optimize and migrate
- `optimize --json` returns `{db_path, status}`
- `migrate --json` returns `{db_path, schema_version, status}`
- Run `migrate` after every binary upgrade to apply pending schema changes safely
### Note on cleanup-orphans
- JSON output: `{orphan_count, deleted, dry_run, namespace}`
- Run `--dry-run` first to confirm the count before passing `--yes` in automation
### Note on graph nodes schema
- `graph --format json` emits `{"nodes": [...], "edges": [...]}`
- Node fields: `{id, name, namespace, kind, type}` where `kind` and `type` carry the same value
- Edge fields mirror the `link` schema with `from`, `source`, `to`, `target`, `relation`, `weight`
### Note on remember
- `--force-merge` updates an existing memory body instead of returning exit code 2 on duplicate name
- Use `--force-merge` in idempotent pipeline loops where the same key may appear multiple times
```bash
neurographrag remember --name config-notes --type project \
--description "updated config" --body "New body content" --force-merge
```
## Integration With AI Agents
### Twenty One Agents — One Persistence Layer
- Claude Code from Anthropic consumes JSON via stdin and orchestrates via exit codes
- Codex from OpenAI reads hybrid-search output to ground generation in local memory
- Gemini CLI from Google parses `--json` output to inject facts into prompts
- Opencode open source harness treats neurographrag as a native MCP-style backend
- OpenClaw agent framework uses `recall` as its long-term memory tier natively
- Paperclip research assistant persists findings across sessions via `remember` atomically
- VS Code Copilot from Microsoft invokes the CLI through integrated terminal tasks
- Google Antigravity platform calls the binary inside its sandboxed worker runtime
- Windsurf from Codeium routes indexed project memories through `hybrid-search` queries
- Cursor editor hooks `recall` into its chat panel for context-aware completions
- Zed editor invokes neurographrag as an external tool in its assistant channel
- Aider coding agent queries `related` for multi-hop reasoning over commit history
- Jules from Google Labs uses exit codes to gate automated pull request reviews
- Kilo Code autonomous agent delegates long-term memory to the local SQLite file
- Roo Code orchestrator passes memory context into its planning phase deterministically
- Cline autonomous agent persists tool outputs via `remember` between cycles
- Continue open source assistant integrates via its custom context provider API
- Factory agent framework stores decision logs for auditable multi-agent workflows
- Augment Code assistant hydrates its embeddings cache from `hybrid-search` results
- JetBrains AI Assistant runs neurographrag as a side process for cross-project memory
- OpenRouter proxy layer injects retrieved context before forwarding requests upstream
## Common Errors
### Troubleshooting — Five Failures and Their Fixes
- Error `exit 10` signals database lock, run `neurographrag vacuum` to checkpoint WAL
- Error `exit 12` signals `sqlite-vec` load failure, verify SQLite version is 3.40 plus
- Error `exit 13` signals database busy, lower `--max-concurrency` or raise `--wait-lock`
- Error `exit 75` signals slots exhausted, retry after a short backoff interval
- Error `exit 77` signals low RAM, free memory before invoking the embedding model again
## Next Steps
### Level Up — Where to Go After This Guide
- Read `COOKBOOK.md` for thirty recipes covering search, graph and batch workflows
- Read `INTEGRATIONS.md` for vendor specific configuration of all 21 agents above
- Read `docs/AGENTS.md` for multi-agent orchestration patterns using Agent Teams
- Read `docs/CROSS_PLATFORM.md` to understand target binaries across nine platforms
- Star the repository at github.com/daniloaguiarbr/neurographrag to track releases