using-jambavan

Using Jambavan

Overview

Jambavan is an MCP server that provides AST-aware code indexing, token-budgeted context, durable memory, an inferred code graph, and guarded file/shell tools. It does not call an LLM — it gives you the ground to reason from.

Core principle: Index first, context before reading, memory before repeating, failures before retrying.

Session Protocol

Use this sequence for a new project session:

1. jambavan_doctor {} — read Project root and its source before anything else, along with gates, storage, and index/watcher status. Every repository-bound tool fails closed while the root is an unresolved cwd-fallback.
2. jambavan_awaken {} — loads the protocol and recent project memories. Pass { "root": "/absolute/repo/path" } when the root is unresolved or belongs to another repo. A root a model set earlier (source: tool-input) is re-pointed cleanly — the server stops the old watcher and closes the old index first — which is what lets one shared server process serve several workspaces. A root from JAMBAVAN_ROOT, the host's roots/list, or the server's own working directory is immutable and fails with root is already fixed by ...; do not retry it.
3. jambavan_index {} — builds or refreshes the AST-aware code index; it accepts the same optional root.
4. jambavan_watch { "action": "start" } — keeps the index live while you edit (skip for one-shot tasks).
5. jambavan_context { "query": "<task-specific query>" } — pulls ranked, token-budgeted context before reading unfamiliar code.

Quick Reference

Need	Tool	Key options
Understand unfamiliar code	jambavan_context	query, compress_prose, include_diff, include_tests
Trace callers/callees	jambavan_graph	action: query, query, direction
Find path between symbols	jambavan_graph	action: path, from, to
Graph overview / hotspots	jambavan_graph	action: report
Persist a decision	jambavan_memory_store	title, body, optional scope
Search past decisions	jambavan_memory_read	query, optional scope
Fetch one memory by ID	jambavan_memory_read	id
Wake up with active memories	jambavan_memory_read	optional scope, limit (default 20)
Distill session into memories	jambavan_memory_mine_session	text, optional scope
Retire a memory	jambavan_memory_forget	id; mode defaults to the reversible invalidate, pass delete to destroy
Record a dead end	jambavan_failure_store	command, symptom, optional root_cause
Check before retrying	jambavan_failure_search	query, optional scope
Hand off to next session	jambavan_session_handoff	optional scope, share_safe
Resume from handoff	jambavan_session_handoff	text, optional scope
Prepare review context	jambavan_review_pack	base, max_files
Compress verbose prose (write-enabled sessions)	jambavan_compress_prompt	path, optional in_place, backup
Audit shortcut debt	jambavan_debt_ledger	—
Investigate bug/failure root cause	root_cause prompt	symptom, context, attempts_so_far
Verification gate before completion	verify_gate prompt	claim, type
Sequence multi-step task strategy	strategy_plan prompt	task, constraints, scale
Decompose task to parallel units	decompose_task prompt	task, units, constraints