CLAUDE.md

IMPORTANT: Codebase Intelligence Instructions for mcp-ariel-memory

This repository is indexed by Repowise. Use the MCP tools below for orientation, discovery, and enriched context (documentation, ownership, history, decisions). Always verify against actual source files before making changes — the index may be stale.

Last indexed: 2026-08-08 (commit e428650)

Entry Points

• __main__.py
• mcp_server/server.py

Tech Stack

Languages: Python Frameworks: Pydantic

Infra: Docker, Docker Compose### Architectural Layers

Guided Tour (12 steps)

1. README.md
2. server.py
3. __main__.py
4. index.js
5. connection.py
6. config.py ... and 6 more steps

Hotspots (High Churn)

Code health

Three signals: defect risk (the overall score), maintainability (smells that hurt readability/change-cost without predicting bugs), and performance (static performance RISK: I/O-in-loop / N+1 shapes that waste work, high-precision/low-recall). Maintainability and performance are co-equal views, never blended into the defect headline. See docs/CODE_HEALTH.md.

Defect risk, Hotspot health: 4.09/10 (stable) · Average: 6.82/10 · Worst: 1.0/10 (shared/saga.py) Maintainability, Average: 8.89/10 Performance risk, Average: 9.85/10

Critical biomarkers

• tests/test_rag_scoring.py — churn risk — impact −2.4
• tests/test_integration.py — churn risk — impact −2.4
• features/audit_trail.py — untested hotspot — impact −2.0
• features/rate_limiting.py — untested hotspot — impact −2.0
• graph/temporal.py — untested hotspot — impact −2.0

Repowise MCP Tools

This repo has the Repowise MCP server configured. The tools below answer questions grep/Read cannot. Every response carries an _meta envelope with index_age_days, indexed_commit, and a stale_warning only when the index has actually diverged from HEAD — silence means the index is current.

When to call which tool:

Trust protocol — when a response replaces reading the source:

• verified: true on any response means the served content was checked against the live working tree. Never follow a verified response with a Read of the same lines — you would be paying twice for identical bytes.
• get_answer with confidence: "high" or grounding: "extracted" is content-grounded (asserted values were verified against retrieved source; ≥1 citation is source-backed). Cite it directly. quotes entries {path, lines, quote} are verbatim live source — quote them instead of re-reading.
• Reading code: get_context skeleton first (~37% of a full Read), then get_symbol for bodies, "path.py:a-b" range reads for anything between symbols. Raw Read is for files the index marks mostly_full or cannot serve.
• The only re-read triggers: bounds: "approximate", _meta.stale_warning, search_method: "bm25", or confidence: "low"/retrieval_quality: "weak".
• Disallowed rationalizations for extra reads: "just to be safe", "to double-check the tool", "to see the full context" (use the skeleton / a range read), "the file might have changed" (that is what verified already checked).

Composition tips:

• get_answer → if confidence is medium/low, follow best_guesses[0].file or fallback_targets[0] into get_context, then get_symbol for bytes.
• get_context returns decision_records titles → get_why(targets=[...]) for the rationale; hotspot: true → get_risk before editing.
• PR review → get_risk(targets=[...], changed_files=[...]); read the directive block first.
• A tombstone error means the file was deleted/renamed since indexing — follow successor_paths.

Output Distillation

• Prefer repowise distill <cmd> for noisy commands — test runs, builds, git status/log/diff, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.
• Output may contain a marker like [repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]. The omitted content is fully preserved — run repowise expand <ref> to retrieve it, or repowise expand <ref> -q <regex> for just the matching lines.
• Never re-run a command to see omitted output; expand the marker instead.
• For structure-level questions about a large indexed file ("what's in here", "which function handles X"), get_context(["path"], include=["skeleton"]) returns the file with bodies elided — every signature plus the bodies of the most central symbols — at a fraction of the cost of a full Read.

Codebase Conventions

Commands:

• Test: pytest
• Lint: ruff check .
• Typecheck: mypy .