jambavan / rules

---
description: Use Jambavan MCP for local code indexing, ranked context, graph navigation, failure history, and project memory when available.
globs:
alwaysApply: true
---

# Jambavan MCP

Jambavan is a local-first code index, project memory, failure ledger, and review assistant. It does not call an LLM and never uploads code. Use its MCP tools when they are available, and never invent a Jambavan result when the server is not.

Requires jambavan >= 2.0.1. If `tools/list` still advertises `jambavan_graph_report` or `jambavan_memory_recall`, the host is pinned to a 1.x build — say so instead of guessing which names work.

## Session start

1. `jambavan_doctor {}` **first** — read `Project root` and its `source` before anything else:
   - **Root is the repo you are working in** → go to step 2.
   - **`source: cwd-fallback`** — the root fell back to a home directory rather than a project, so every repository-bound tool is blocked (`jambavan_context`, `jambavan_index`, `jambavan_graph`, `jambavan_impact`, `jambavan_review_pack`, and the file tools). Bind with `jambavan_awaken { "root": "<absolute path to this repo>" }`.
   - **Root is a different repo** → whether you can claim it depends on that root's `source`; see the next section.
2. `jambavan_index {}` when the index is missing or stale, then `jambavan_watch { "action": "start" }` if the session will continue past a single edit.
3. `jambavan_awaken {}` for the operating protocol and memory scope. Its output supersedes this rule if the two disagree.

## One server, many workspaces

Some hosts run a single Jambavan process for every open window — Cursor is one — so the project root is shared rather than per-workspace.

A root that a model set through `jambavan_awaken` or `jambavan_index` (`source: tool-input`) can be re-pointed: bind the repo you want and the server stops the old watcher, closes the old index, and follows you. Two projects taking turns is normal and cheap once each has an index.

A root that came from `JAMBAVAN_ROOT` (`source: env`), the host's `roots/list` (`client-roots`), or the server's own working directory (`cwd-project`) is immutable, and binding a different one fails with `root is already fixed by ...`. Do not retry that call. Either report that Jambavan is unavailable for this repo and fall back to host tools, or give the repo its own MCP entry with `JAMBAVAN_ROOT`.

## Retrieval

- `jambavan_context { "query": "..." }` before broad searches or whole-file reads. Query **one identifier or symbol name**, not a sentence — multi-term natural-language queries return little. It also returns related symbols, which makes it the fastest way to find the siblings and call sites of a change.
- `jambavan_graph` with an `action` of `report`, `query`, or `path` for structure. Inferred same-name edges are excluded unless `include_inferred` is true; treat those as hints and verify them before changing code.
- `jambavan_impact` for the blast radius of branch changes, and `jambavan_review_pack` for review context.
- Use the host's own search and read tools for literal text and to fill gaps that indexed context leaves.

## Memory and failures

- `jambavan_failure_search` before retrying a failed command, and `jambavan_failure_store` once you have diagnosed one. This is what stops a known dead end from costing time twice.
- `jambavan_memory_store` for durable project decisions. `jambavan_memory_read` is the single read path: `id` fetches one document and `query` runs a search.
- `jambavan_memory_forget` defaults to a reversible `invalidate`; pass `mode: "delete"` only to destroy a document.
- The `verify_gate` prompt before claiming a fix, build, test run, or requirement is complete.

## Safety

- Keep Jambavan read-only unless the user explicitly asks to enable write, bash, outside-root, or secret-file access.
- Do not commit a generated `.jambavan/` index or memory bundle unless the user asks for it.
- If the host cannot resolve a freshly published version, the registry may enforce a minimum release age. Pin the version and set the registry and release-age overrides in the MCP entry's `env`.
- If Jambavan is unavailable, fall back to host tools and say which capability was missing rather than blocking unrelated work.