Tentra — Memory for AI Coding Agents

Rank FILES by a composite refactor-priority score: cyclomaticComplexity × (1 + churn30d/100) × (1 − testCoverage/100). High score = complex, frequently changed, poorly tested — the files most likely to break. The canonical "what should I refactor next?" list. Unlike list_god_nodes (which ranks SYMBOLS by graph-coupling degree), this ranks FILES by change-risk math. They answer different questions: list_god_nodes = "what is too connected?", get_quality_hotspots = "what's likely to break on the next change?". Run both for a complete architectural review. Response includes a dataSource field — "…

Return the full code subgraph that belongs to ONE Tentra canvas service: every file mapped to that service, all the symbols in those files, and the edges leaving those symbols (including cross-service edges). Use when the user has an architecture diagram and asks "what code is in the payment_service?", or when you want to reason about one service in isolation. Unlike get_symbol_neighbors (which starts from a single symbol), this starts from a service_id and pulls the whole service at once. Unlike query_symbols (which ignores service boundaries), this is already scoped. Requires a prior set_se…

Mid-implementation alignment check: given files you just changed and a saved architecture, return what the spec says about that work — which services those files belong to (via set_service_mapping), the spec's declared edges in/out of each, ADRs that motivate or constrain them, and drift signals (files outside the model, services with no surviving files). Use proactively DURING implementation, not after — call after each batch of edits to verify the agent stays inside the architectural envelope and surfaces existing decisions before re-litigating them. Unlike sync_architecture (post-hoc, whol…

Breadth-first traverse the code graph starting from one symbol to return its local neighborhood: what it calls, what calls it, what it imports, inheritance / implementation relationships. Answers "how does this work?" structurally — grep finds the symbol; get_symbol_neighbors tells you what it actually depends on. Unlike find_references (which only returns direct callers = depth-1 inbound), get_symbol_neighbors walks OUTBOUND by default and can go deeper (up to depth=5) and bidirectional (direction="both"). Unlike explain_code_path (which finds the shortest single path between two given symbo…

Walk a local repo, extract symbols + call/import/reference edges via Tree-sitter (TypeScript, JavaScript, Python, Go, Java, Rust), and upload them to Tentra as a new immutable snapshot. This is what turns a raw checkout into a queryable code graph. WRITE PATH, LONG-RUNNING (seconds on small repos, a few minutes on 10k+ file monorepos). It iterates: walk files → parse with Tree-sitter locally → POST files → POST symbols → POST edges in batches → create a job row. For tier=tier2/both, also returns a first batch of files for the agent to enrich via record_semantic_node; call index_code_continue …

Drive the tier-2 indexing loop forward: check a job's progress and either mark it done (when every file has been processed) or return the remaining file count so the agent knows it should send another batch of record_semantic_node calls. Use ONLY after index_code with tier="tier2" or tier="both" returned a job_id. Typical loop: call index_code → for each file in first_batch, call record_semantic_node with the agent's inferred purpose → call index_code_continue → if done=true, stop; if pending>0, enrich more files and repeat. Unlike get_index_job (pure read), this tool will mark the job "compl…

Attach an EXISTING decision (from record_decision) to one more entity — a service, file, symbol, contract, or domain — with a typed relationship: "motivates" (decision caused this entity to exist), "constrains" (decision limits how it can evolve), "documents" (decision explains it), "implements" (entity is the concrete realization of the decision). Use for post-hoc linking: e.g. a month after recording an ADR you realize it also motivates a new service. Unlike record_decision (which can include initial links via the links[] array in one call), link_decision adds ONE link at a time to an alrea…

Run 8 architecture-quality rules against a saved diagram and return a severity-tagged list of issues (errors / warnings / info). Rules covered: orphan_node, duplicate_connection, dangling_connection (references non-existent service), naming_convention (snake_case IDs), god_service (>6 connections), spof (single non-horizontal database with >1 dependent), missing_database, sync_overload (>5 sync HTTP edges on one service). Use BEFORE updating or exporting an architecture, or when the user asks "is this design OK?" / "what's wrong with X?". Unlike sync_architecture (which compares the diagram …

List every saved architecture in this workspace as a lightweight summary (id + name + version + createdAt + URL), newest first. Use for BROWSING / DISCOVERY — "what have I designed already?", "find an architecture named X". Unlike get_architecture, this does NOT return services or connections; once the user picks one, call get_architecture with the returned id to load the full graph before editing. Prerequisites: Tentra API auth. Read-only. Response: Array of { id, name, version, createdAt } rendered as a human-readable bullet list with share URLs. Empty workspaces receive a hint to call cre…

Return the top-N most coupled symbols in a snapshot — those with the highest fanIn + fanOut — as a ranked list. Surfaces architectural smells: utility modules that "know too much", classes every other class depends on, etc. Unlike get_quality_hotspots (which ranks FILES by churn × complexity × (1 − coverage) — a code-quality lens), list_god_nodes ranks SYMBOLS by raw graph degree — a coupling lens. Use list_god_nodes to find what to DECOMPOSE; use get_quality_hotspots to find what to REFACTOR. Provide either snapshot_id (specific) or repo_id (automatically uses latest snapshot). Test/fixture …

List every code-graph snapshot stored for a given repo, newest first — each row has id, commitSha (when index_code ran inside a git working tree), createdAt, parentSnapshotId, and a stats blob. Use to TIME-TRAVEL through the repo's history: pick a snapshot_id from this list and feed it to any read-path tool (query_symbols, list_god_nodes, get_quality_hotspots, etc.) to inspect the graph as it looked at that point. To compare two points in time, pick two ids and call diff_snapshots. Unlike get_index_job (one job → one snapshot), this lists every snapshot regardless of how it was produced. Pre…

Search the indexed code graph for symbols (functions, classes, methods, interfaces, types, variables) by name or qualified name. The structural-search entry point: returns resolved symbol IDs (with fanIn/fanOut ranking) that every other read-path tool accepts — grep returns text matches, query_symbols returns graph nodes. Two match modes: "trigram" (default, pg_trgm similarity — best for fuzzy / typo-tolerant / unique-symbol lookups), "substring" (ILIKE %q% — best for broad listings like every "Handler" or "Controller" in the repo; results ranked by fanIn + fanOut so central ones float to the…

Persist a service contract — an OpenAPI spec, proto file, GraphQL schema, event schema, Kafka/RabbitMQ topic schema, etc. — as a first-class entity in the code graph, so you can then attach code symbols to it via bind_contract and query it via get_contracts. Use once per contract per version. The contract itself is just metadata + an optional schema JSON payload (record_contract does NOT parse the schema — that's an upstream job). Unlike record_decision (which stores architectural rationale), this stores a TECHNICAL INTERFACE specification. After recording, call bind_contract to link the symb…

Persist an Architecture Decision Record (ADR) — slug + title + status + context + decision + consequences — as a first-class row in the code graph, with support for supersession (auto-marking an older decision "superseded") and immediate entity links (services, files, symbols, contracts, domains). Use when the user documents a real architectural call: "we chose Postgres over Mongo", "we split the monolith into N services", "we deprecated the legacy auth flow". Unlike link_decision (which attaches an existing decision to an entity after the fact), record_decision CREATES the decision and optio…

Persist ONE pre-computed embedding vector for a file or symbol so it becomes searchable via find_similar_code. You must produce the vector yourself (the agent embeds the source_text with whatever model it has access to) — Tentra stores vector + source_text + model identifier but does not call any embedding API on your behalf. Works in both hosted mode (pgvector column on Postgres) and local mode (Float32Array BLOB on SQLite). Request and response shapes are identical across modes. Use in a loop after index_code to seed the vector index: for each file or symbol you care about, embed a represe…

Persist ONE agent-inferred semantic annotation (a one-sentence purpose + domain tags + confidence + optional semantic role) for a single file OR single symbol in an indexing job, and advance that job's progress cursor by 1. This is the write side of tier-2 indexing: after index_code (tier2/both) returns a batch of files with their symbol skeletons, the agent reads each file's source, decides what it does, and calls record_semantic_node per file — Tentra stores the annotation in CodeSemantic and marks the file as tier2-indexed. The job cursor auto-advances so index_code_continue eventually ret…

Return a structured PATCH PLAN for renaming a symbol — definition site + every call site with exact file paths and line ranges — so the calling agent can apply the rewrite with its own Edit/MultiEdit tools. The canonical "rename without breaking hidden callers" tool. Unlike find_references (which only returns callers), safe_rename also returns the symbol's own declaration site (which the agent must also rewrite) and packages everything with a summary + warnings into a plan ready for programmatic application. Unlike a plain grep-and-replace, the call sites come from the resolved code graph — y…

Tag one file, symbol, or service as belonging to a business domain (e.g. "payments", "identity", "fraud"). Supports both AI-inferred (source="ai", lower confidence) and human-confirmed (source="human", confidence 1.0) assignments. Upserts: if the same (domain_id, entity_type, entity_id) tuple already has a membership, it is updated in place rather than duplicated. Use AI-inferred memberships to bootstrap domain maps after indexing, then let a human confirm and flip source to "human". Unlike set_service_mapping (which ties a FILE to a concrete canvas SERVICE, 1:1), domain memberships are many-…

Declare which Tentra canvas service owns which files in a specific snapshot — in one batched call. Each mapping is (relative file path → service id); every matching CodeFile row has its serviceId column updated. This is the bridge between the code graph (files, symbols, edges) and the architecture diagram (services, connections). get_service_code_graph and service-scoped views will return empty arrays until at least one set_service_mapping call has populated the mappings for a snapshot. Unlike set_domain_membership (which tags entities with abstract business domains), set_service_mapping tags…

Diff a saved Tentra architecture against the current state of a local codebase and return a drift report: services added / removed / changed, connections added / removed, plus a 0–100 accuracy score. Use when the user asks "is my diagram still accurate?", "what's drifted?", or after significant refactors. Unlike lint_architecture (which only validates the diagram in isolation), this tool reads the codebase and compares. Unlike analyze_codebase (which creates a new diagram from scratch), this compares to an EXISTING diagram without overwriting it — use update_architecture afterwards if you wan…

Mutate an existing architecture — bump its version, snapshot the prior state as a version record, and replace whichever top-level fields you pass. Use instead of create_architecture whenever you already have an architecture id in context from a previous call, list_architectures, or the URL. Unlike create_architecture (which always makes a brand-new artifact), this preserves identity and lineage: version auto-increments and the old state is kept in the ArchitectureVersion history. Each field is replace-not-merge — if you pass services, you REPLACE the full services array; fields you omit are l…