Your first session¶
A first session is complete when your agent can retrieve a source citation and read back a saved decision.
1. Install¶
Use Python 3.10–3.14 and a stable command on PATH:
You can also use uv tool install or pip install. Python-only indexing works
with plain gragdb. Start without embeddings; add them after checking that this
workflow helps. Installation covers Windows native libraries,
first-use downloads and offline preparation.
2. Connect an agent¶
Init detects Claude Code, Cursor, Windsurf or Zed, saves a checkout mapping in
Git-ignored .grag/project.json, and configures an MCP connection and agent guidance.
Use grag init --client cursor or --client claude when choosing explicitly.
grag init --dry-run previews changes before applying.
What init verifies
Init also initializes the written MCP registration, lists its tools, and writes/reads one non-searchable GragSetup:connection record.
It prints the registration, resolved command and selected database. Verification
failure returns a nonzero exit code while preserving the saved configuration.
Use --no-verify for offline configuration preparation; readiness remains unverified.
This checks the connection from your terminal environment. Reconnect the actual
harness too: its environment and permissions can differ.
The default new database is ~/.grag/<project-name>-<checkout-id>.lbdb. Run commands
from anywhere inside the checkout to reuse that mapping. Projects and relocation
explains existing databases, worktrees, configuration backups and removal.
Restart or reconnect the MCP client. The configured proxy starts a shared local
server on first use. grag status prints its address and log location. On Windows,
follow the separate-terminal command if the harness prevents independent startup.
MCP for everyday agent work
Since 0.10.1, the skill, server instructions and generated CLAUDE.md explicitly
prefer MCP for graph reads, memory writes and ingestion. Agents should discover
deferred tools before falling back to the CLI. CLI setup and diagnostics remain
appropriate, as do explicit CLI requests and unavailable or failed MCP connections.
A fallback should explain why and keep the same graph; validation errors or empty
results do not call for switching interfaces. This is guidance, not enforcement.
Upgrading the package does not rewrite installed instructions. Rerun
grag init --client claude (or your client) in the project to refresh its skill
and managed guidance, then reconnect MCP. If you also installed a personal skill,
refresh it with grag init --global-skill --client claude; update every copy used
by your harness. Preview project changes with --dry-run.
3. Index the intended source¶
First-use skill setup in 0.10.0
grag 0.10.0 adds grag init --global-skill --client claude
(use cursor or codex for those harnesses). Install it once to make the
grag skill available in new repositories, then invoke /grag or select the
skill in your harness. The instructions nudge the agent to run
grag init --ingest-if-empty: it maps the current checkout only when the graph
is absent, empty, or contains just the init verification marker. Existing
code, documents or authored memory suppress the automatic setup and scan.
This is agent guidance, so execution still depends on the harness's tool
permissions. Project setup
covers installation, updates and removal.
Ask the agent:
Use grag to index this project's source directory. Describe the schema and show one function's name, source path and line range.
Choose the intended source directory. Grag honors ignore rules
and skips nested worktrees and symlinks. grag init --ingest combines setup and
indexing; CLI ingestion uses the running owner when available.
Code ingestion lists language coverage and scope options.
4. Save something worth retaining¶
Remember a decision we made in this session, including why and its source. Reuse the existing schema, and link it to the relevant code if possible.
Open another session and ask for the decision and source. Confirm that the client
is selecting the same database. This verifies a useful write/read loop; status
alone only tells you about the server, not whether your harness can query it.
For questions about edited code, ask the agent to use freshness="require".
Freshness verifies the registered code scope at the check time; it does not certify
the truth of authored memories. Read freshness and
memory corrections when needed.
Everyday commands¶
For terminal use or an agent's CLI fallback:
grag remember "Use a ten-minute cache" --id cache-policy
grag search "cache"
grag context Memory:cache-policy
grag status # selected database, server address and log
grag doctor # installation diagnostics; see installation guide for release-specific checks
grag stop # clean shutdown of the selected managed server
The graph browser is served at the address printed by status. To connect a
second supported harness, run init --client <client> in the same checkout;
both registrations use the same mapping and shared server.