Related Pages

Related topics: MCP Surface, Intent Routing & Hybrid Retrieval, Operations, Configuration & Common Workflows

Overview & the Trust Contract

reporecall is an MCP (Model Context Protocol) server that gives coding agents persistent, queryable memory of a repository's code, architecture, and evolving intent. As of v0.8.0, every retrieval path is governed by an explicit Trust Contract — a set of guarantees the server makes to the agent about freshness, scope, and source provenance of the context it injects.

What `reporecall` Does

reporecall indexes a codebase into a local SQLite store, derives structural and semantic artifacts from it (call graph, topology, wiki pages, lens dashboards), and exposes a small set of MCP tools that an agent can call to recall that context on demand. The daemon and MCP server share a single embedded storage layer so that wiki pages, capability evidence, and topology metadata survive across sessions Source: README.md:1-40.

The product's center of gravity is recall, not search ranking: the goal is to surface *what the agent has already forgotten* with enough provenance that the agent can trust it as a basis for edits. Every feature since v0.5.0 — Louvain community detection, the wiki layer, the lens dashboard, capability evidence resolution — feeds into this recall loop Source: docs/architecture-overview.md:12-58.

The Six-Tool Surface (v0.8.0)

The v0.8.0 release collapsed the public MCP surface to six tools to reduce agent tool-choice confusion:

Source: src/mcp/tools.ts:1-140 Source: docs/design/wp5-tool-collapse.md:1-60

Standalone wiki tools (wiki_query, wiki_read, wiki_write) and lens helpers from prior versions were folded into search_context, memory, and refresh_context so that agents no longer have to choose between overlapping entry points Source: CHANGELOG.md:6-22.

The Trust Contract

The Trust Contract is the set of properties every tool response must satisfy before it leaves the server. It is enforced in src/core/trust.ts and consulted by the staleness layer in src/core/staleness.ts:

1. Freshness honesty — Every payload carries an indexedAt timestamp and a sourceCommit SHA. If the underlying source has changed since indexing, the response is marked stale and the agent is told to call refresh_context rather than acting on the result Source: src/core/staleness.ts:18-74.
2. Lean injection — Context blocks are size-capped and ranked; the top-N highest-evidence snippets are returned, with the rest available via follow-up queries. This prevents context-window bloat that masked the underlying signal in earlier versions Source: src/core/trust.ts:30-92.
3. Source provenance — Every snippet, wiki claim, and topology edge is tagged with the file path and commit it was derived from. Agents can cite these directly in edits Source: src/core/indexer.ts:55-110.
4. Capability evidence — Trace, architecture, and change prompts resolve their evidence generically: the same evidence resolver backs explain_flow, search_context, and lens generation, so the agent cannot be told two different things by two different tools Source: docs/design/trust-contract.md:14-48.

Freshness Flow

flowchart LR
  A[Source files] --> B[indexer]
  B --> C[SQLite store]
  C --> D[staleness.ts]
  D -->|fresh| E[trust.ts]
  D -->|stale| F[mark stale + suggest refresh_context]
  E --> G[MCP tool response]
  F --> G

Source: src/core/staleness.ts:18-74 Source: src/core/trust.ts:30-92 Source: src/mcp/server.ts:40-120

The staleness layer runs at response time, not only at index time: a tool call whose referenced commit is older than the working tree's HEAD will downgrade its evidence weight and surface a refresh_context hint rather than silently returning pre-change data Source: docs/design/trust-contract.md:50-72.

Why It Matters for Agents

Before the Trust Contract, agents could receive high-confidence answers that were actually a few commits behind, or context blocks so large that the relevant signal was diluted. v0.8.0 trades breadth for honesty: smaller responses, six tools instead of fifteen, and a guaranteed provenance trail Source: CHANGELOG.md:6-22 Source: README.md:40-78.

For integration, the practical implication is that agents should treat a stale: true flag on any tool response as a hard signal to re-run refresh_context before editing, and should prefer search_context + explain_flow over ad-hoc tool chains when investigating unfamiliar code Source: docs/architecture-overview.md:60-96.

Related Pages

Related topics: Overview & the Trust Contract, Wiki, Memory, Business Context & Lens, Operations, Configuration & Common Workflows

MCP Surface, Intent Routing & Hybrid Retrieval

Overview

The MCP (Model Context Protocol) surface is the public contract between agent hosts and the reporecall daemon. As of v0.8.0 it is collapsed to six tools — search_context, search_code, explain_flow, memory, refresh_context, and get_stats — to reduce agent tool-choice confusion and enforce tighter freshness contracts (Source: src/daemon/mcp-server.ts:1-120). Internally, a tool call flows through intent classification, hybrid retrieval, optional capability-evidence resolution, and budget-aware evidence compression before a JSON response is returned to the agent.

MCP Surface

mcp-server.ts registers the six tools against the MCP transport, attaches JSON Schema for parameters, and routes each call into a typed handler implemented by the search pipeline (Source: src/daemon/mcp-server.ts:120-260). The surface guarantees:

• One tool per intent class. search_context covers semantic/trivia queries, search_code returns raw source, explain_flow traces calls and data flow, memory reads/writes persistent notes, refresh_context re-runs index freshness checks, and get_stats reports pipeline and storage metrics.
• No overlapping coverage. Previously separate wiki and topology queries were folded into search_context via downstream routing rather than exposed as parallel tools.
• A refresh_context tool that invalidates the cached index commit without performing a search.

Intent Routing

intent.ts classifies the agent's query before any retrieval happens. It uses lightweight keyword and structural cues to assign an intent label such as capability.trace, capability.architecture, capability.change, code.search, or flow.explain (Source: src/search/intent.ts:1-180). The label feeds two downstream decisions:

1. Which retrieval strategy the hybrid layer weights (dense vector vs. lexical BM25 vs. topology priors).
2. Which evidence resolver populates the response — capability-evidence.ts handles the three capability.* intents while other intents fall through to raw hits.

Routing is deterministic and the resolved intent is echoed in the response so agents and operators can verify alignment with the original query (Source: src/search/intent.ts:180-260).

Hybrid Retrieval

hybrid.ts runs the actual retrieval, fusing three signals:

• Dense vector similarity over code and chunk embeddings.
• Lexical BM25 over the same corpus for exact-identifier matches.
• Topology-derived priors — Louvain community membership and hub-node scores — injected from the SQLite cache built during indexing (Source: src/search/hybrid.ts:1-220).

Results are merged with reciprocal rank fusion and handed to pipeline-core.ts, which orchestrates per-tool post-processing: result-count caps, deduplication, and back-link enrichment from the wiki layer (Source: src/search/pipeline-core.ts:1-180).

Capability Evidence & Compression

For capability.* intents, capability-evidence.ts resolves generic evidence (trace logs, architecture summaries, change manifests) and stitches them into a structured response instead of raw search hits (Source: src/search/capability-evidence.ts:1-200). All responses then pass through evidence-compressor.ts, which trims injected context to fit the agent's token budget while preserving citation anchors (file:line) so the agent can follow links back into the source (Source: src/search/evidence-compressor.ts:1-160). This is the "leaner injected context" guarantee introduced in v0.8.0.

End-to-End Flow

sequenceDiagram
    participant Agent
    participant MCP as mcp-server.ts
    participant Pipe as pipeline-core.ts
    participant Intent as intent.ts
    participant Hybrid as hybrid.ts
    participant Cap as capability-evidence.ts
    participant Comp as evidence-compressor.ts

    Agent->>MCP: tool call (e.g. search_context)
    MCP->>Pipe: route to handler
    Pipe->>Intent: classify query
    Intent-->>Pipe: intent label
    Pipe->>Hybrid: retrieve (weights per intent)
    Hybrid-->>Pipe: fused hits
    alt capability.* intent
        Pipe->>Cap: resolve structured evidence
        Cap-->>Pipe: trace/arch/change bundle
    end
    Pipe->>Comp: compress to token budget
    Comp-->>MCP: trimmed response
    MCP-->>Agent: JSON result with citations

Trust Contract Notes

The v0.8.0 surface changes were framed as a trust-contract remediation. Two guarantees follow from the source layout:

• Freshness honesty — every response carries the index commit it was generated against; refresh_context is the only sanctioned way to invalidate this claim (Source: src/daemon/mcp-server.ts:260-340).
• Bounded storage — evidence compression plus dedup in pipeline-core.ts keeps SQLite footprint stable across indexing runs (Source: src/search/pipeline-core.ts:180-300).

Together these modules turn an agent's free-form query into a bounded, citation-anchored response drawn from the indexed repository, without exposing the internal wiki or topology layers as separate MCP tools.

Related Pages

Related topics: MCP Surface, Intent Routing & Hybrid Retrieval, Operations, Configuration & Common Workflows

Wiki, Memory, Business Context & Lens

Reporecall exposes three persistence surfaces — a curated wiki for human-readable codebase knowledge, a memory store for agent-curated facts, and a business context / capability evidence layer — plus a Lens dashboard that visualizes the resulting architecture. Together these were promoted into a first-class selling point in v0.6.0–v0.6.2 and survived the v0.8.0 MCP-surface collapse as either first-party tools or prompt-injected context.

Wiki Layer

The wiki is the project's long-form memory. Pages live on disk and are addressed by slug, with backlinks and keyword search over their body content.

• Generation — The generator.ts module walks the call graph and topology output (see Topology-Aware Search) to propose pages, then writes them through writePage. As of v0.6.1, generation runs not only inside index_codebase but also on MCP server and daemon startup, so wiki context is always present when an agent attaches. Source: src/wiki/generator.ts:42-118
• Freshness guard — writePage reads the on-disk sourceCommit for the page and skips a rewrite when the recorded commit is unchanged. This avoids re-emitting identical markdown on every startup and was the v0.6.1 bug fix that prevented wiki stampedes. Source: src/wiki/staleness.ts:18-64
• Auto-capture — auto-capture.ts listens for indexing events and snapshots notable findings (hub nodes, cross-community edges, capability resolutions) into candidate wiki pages before the generator curates them. Source: src/wiki/auto-capture.ts:30-91
• Public tools (pre-v0.8.0) — Four MCP tools: wiki_query (keyword search), wiki_read (page fetch + link/backlink listing), wiki_write (manual edit, persists sourceCommit), and a fourth surfacing tool. After v0.8.0 these were folded into the trimmed six-tool surface (search_context, search_code, explain_flow, memory, refresh_context, get_stats) so wiki reads now flow through search_context while writes happen internally during indexing.

Memory Tool

Memory is the agent's writable scratch space, distinct from the wiki's curated pages. It was introduced alongside the wiki and gained precision in v0.6.0, then surfaced as a top-level MCP tool in v0.8.0.

• Storage — Facts persist via memory/context.ts under a per-repository SQLite namespace, keyed by short identifier and tagged with the commit that captured them. Source: src/memory/context.ts:55-140
• Read semantics — On each MCP attach, the daemon promotes the most-relevant memories into the agent's system context, deduplicating against the wiki to prevent double-injection. Source: src/memory/context.ts:142-198
• Write semantics — The memory MCP tool accepts short free-form facts and stores them with provenance; v0.8.0's trust-contract remediation tightened the schema so freshness metadata is mandatory. Source: src/mcp/tools.ts:201-256

Business Context & Capability Evidence

Business context is the part of the wiki that answers *"why does this code exist for this product"* rather than *"what does it call"*. Capability evidence is the structured backing for those claims.

• Generation — business.ts emits per-capability pages anchored to call-graph regions, with each claim citing a code range or git-blame excerpt. Source: src/wiki/business.ts:24-88
• Capability resolution — context.ts resolves generic capability phrases ("trace", "architecture", "change") to the appropriate evidence bundle before the wiki is queried, a v0.7.0 improvement that removed brittleness from prompt phrasing. Source: src/wiki/context.ts:30-77
• Export — v0.7.1 added a "Business Context Export" path that serializes the capability pages into a single bundle for sharing outside the agent loop. Source: src/wiki/business.ts:120-178

Lens Architecture Dashboard

Lens is reporecall's standalone, self-contained HTML visualization of the indexed codebase. It is invoked from the CLI, not the MCP surface.

• Invocation — reporecall lens reads the latest SQLite topology store and writes a single dashboard.html file with no external network dependencies. Source: src/lens/dashboard.ts:40-95
• Five tabs — (1) Modules, (2) Communities (Louvain clusters), (3) Hubs, (4) Surprising cross-boundary edges, and (5) Investigation questions produced during the v0.5.0 topology pipeline. Source: src/lens/dashboard.ts:120-205
• Position in the stack — Lens is a *consumer* of wiki/memory/context: it renders the same SQLite tables that the agents query, so a freshly-index_codebase run is the only prerequisite.

┌────────────────────────────────────────────────┐
│ MCP agents ──► search_context / explain_flow    │
│                     │                          │
│                     ▼                          │
│         ┌──── wiki + memory + capability ────┐ │
│         │     (SQLite, sourceCommit tracked) │ │
│         └────────────────┬───────────────────┘ │
│                          ▼                     │
│           ┌── Lens dashboard.html (CLI) ──┐    │
│           └───────────────────────────────┘    │
└────────────────────────────────────────────────┘

The wiki provides human-readable prose, memory provides agent-writable facts, capability evidence anchors business claims to code, and Lens turns the same underlying tables into an architecture diagram. Operating on a shared SQLite store means a single index_codebase keeps all four surfaces in sync — and the v0.8.0 trust-contract changes ensured each surface reports freshness honestly rather than silently re-emitting stale content.

Related Pages

Related topics: Overview & the Trust Contract, MCP Surface, Intent Routing & Hybrid Retrieval, Wiki, Memory, Business Context & Lens

Operations, Configuration & Common Workflows

Overview

reporecall exposes its functionality through a small set of CLI entry points under src/cli/. Each command is a thin orchestration layer that wires up configuration loading, the indexing pipeline, the MCP server, or diagnostic utilities. The six public surfaces — init, index, serve, mcp, doctor, and stats — together cover the full lifecycle of a reporecall installation: bootstrapping a project, building the index, serving it to agents, and verifying health. Source: src/cli/init.ts:1-40

The v0.8.0 release deliberately collapsed the MCP tool surface to six primitives (search_context, search_code, explain_flow, memory, refresh_context, get_stats) to reduce agent tool-choice confusion. The CLI commands mirror this philosophy by keeping operator workflows short, predictable, and scriptable. Source: src/cli/mcp.ts:1-30

Command Reference

Source: src/cli/init.ts:20-60, src/cli/index-cmd.ts:1-45, src/cli/serve.ts:1-35, src/cli/mcp.ts:15-55, src/cli/doctor.ts:1-40, src/cli/stats.ts:1-30

Initialization Workflow

init is the entry point for new projects. It creates the .reporecall/ directory layout, writes a default configuration file, and verifies that the underlying storage backend (SQLite) is writable. The command is idempotent: re-running it preserves an existing index and only refreshes missing artifacts. Source: src/cli/init.ts:40-90

A typical initialization sequence looks like this:

# From inside a project root
reporecall init
reporecall index              # build the first index
reporecall stats              # confirm the index exists and is fresh

The init step is also responsible for seeding the wiki layer directory and registering the freshness hooks used by later commands. Because wiki pages auto-generate on MCP server and daemon startup (v0.6.1), the storage paths created by init must be stable across runs. Source: src/cli/init.ts:60-110

Indexing and Server Operations

Index Pipeline

index is the heaviest command: it walks the repository, chunks source files, extracts symbols and call-graph edges, runs the topology analysis (Louvain community detection, hub scoring, cross-boundary surprise scoring from v0.5.0), and persists everything into the local SQLite store. The pipeline is incremental where possible, so subsequent runs only re-process changed files. Source: src/cli/index-cmd.ts:30-120

The topology layer also generates investigation questions, which are written into the index and later surfaced to agents through the injected context — this is why index must run before serve or mcp can produce meaningful results. Source: src/cli/index-cmd.ts:90-150

Serve and MCP

serve starts the long-running RPC server that backs the lens dashboard (reporecall lens, v0.6.2) and other non-MCP integrations. It binds to a configured port, loads the index, and keeps it hot in memory for low-latency queries. Source: src/cli/serve.ts:20-80

mcp is the sibling command tailored for AI agents. It speaks the Model Context Protocol and registers only the six v0.8.0 trust-contract tools. Because v0.6.1 introduced wiki auto-generation on MCP startup, the first request after mcp boot may pay a one-time generation cost; subsequent requests are served from disk. Source: src/cli/mcp.ts:30-90

Diagnostics and Common Workflows

`doctor` and `stats`

doctor performs a sequence of preflight checks: configuration validity, storage writability, index presence and freshness, MCP server reachability (when serve is running), and dependency versions. It is the recommended first step when an agent reports stale or missing context. Source: src/cli/doctor.ts:20-90

stats prints quantitative metrics: number of indexed files, symbols, edges, wiki pages, and storage footprint. The v0.8.0 release specifically called out smaller storage as a goal, so operators monitoring capacity should watch the stats output across releases. Source: src/cli/stats.ts:15-70

Standard Workflow Patterns

Three recurring workflows cover most operational scenarios:

1. Cold-start workflow — init → index → mcp. Used when bootstrapping a new project or recovering from a wiped .reporecall/ directory.
2. Refresh workflow — index → refresh_context (MCP tool). Used during active development when code changes faster than the freshness window. The v0.8.0 refresh_context tool replaced older standalone refresh commands to keep the MCP surface lean.
3. Health-check workflow — doctor → stats. Used by CI or scheduled jobs to confirm the installation is still healthy and within capacity budgets.

Source: src/cli/doctor.ts:60-110, src/cli/stats.ts:40-90, src/cli/mcp.ts:60-110

Configuration Notes

Configuration is read from a single file produced by init. The same file is consulted by every other command, which keeps behavior consistent between operator-driven and agent-driven use. The v0.6.1 release added a freshness guard inside the wiki generator (writePage checks sourceCommit from disk) — this means index and serve must agree on the commit being read, which is enforced by the shared config. Source: src/cli/init.ts:80-130, src/cli/index-cmd.ts:120-170

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.5.0 — Topology-Aware Search & Architecture Decomposition
• User impact: Upgrade or migration may change expected behavior: v0.5.0 — Topology-Aware Search & Architecture Decomposition
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.5.0 — Topology-Aware Search & Architecture Decomposition. Context: Observed when using node, python
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.5.0

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.6.2 — Lens Architecture Dashboard
• User impact: Upgrade or migration may change expected behavior: v0.6.2 — Lens Architecture Dashboard
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.2 — Lens Architecture Dashboard. Context: Observed when using node, python, windows, macos
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.6.2

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches
• User impact: Upgrade or migration may change expected behavior: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.7.1

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.8.0 — Trust Contract Remediation
• User impact: Upgrade or migration may change expected behavior: v0.8.0 — Trust Contract Remediation
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.8.0 — Trust Contract Remediation. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.8.0

5. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/proofofwork-agency/reporecall

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.6.0: Wiki Layer, Topology Tools & Memory Precision
• User impact: Upgrade or migration may change expected behavior: v0.6.0: Wiki Layer, Topology Tools & Memory Precision
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.0: Wiki Layer, Topology Tools & Memory Precision. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.6.0

7. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/proofofwork-agency/reporecall

8. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/proofofwork-agency/reporecall

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/proofofwork-agency/reporecall

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/proofofwork-agency/reporecall

11. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v0.6.1: Wiki Startup Generation & Version Sync
• User impact: Upgrade or migration may change expected behavior: v0.6.1: Wiki Startup Generation & Version Sync
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.1: Wiki Startup Generation & Version Sync. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.6.1

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/proofofwork-agency/reporecall

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using reporecall with real data or production workflows.

• v0.8.0 — Trust Contract Remediation - github / github_release
• v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patch - github / github_release
• v0.6.2 — Lens Architecture Dashboard - github / github_release
• v0.6.1: Wiki Startup Generation & Version Sync - github / github_release
• v0.6.0: Wiki Layer, Topology Tools & Memory Precision - github / github_release
• v0.5.0 — Topology-Aware Search & Architecture Decomposition - github / github_release
• v0.3.1 - github / github_release
• Configuration risk requires verification - GitHub / issue