Reporecall

Reporecall

 ____                                    _ _
|  _ \ ___ _ __   ___  _ __ ___  ___ __ _| | |
| |_) / _ \ '_ \ / _ \| '__/ _ \/ __/ _` | | |
|  _  Entry --> Intent
  Intent --> Search
  Intent --> Wiki
  Wiki --> Product
  Intent --> Memory
  Search --> Resolver
  Wiki --> Resolver
  Product --> Selected
  Resolver --> Selected
  Memory --> Selected
  Selected --> Agent
  Selected --> Explain
  Product --> Lens
  Wiki --> Lens
  Product --> BusinessTools

The important rule is file coverage over chunk volume. For trace and architecture questions, Reporecall tries to cover the relevant layers: entry/UI, state or service, controller or edge function, and shared helpers when those layers exist.

Retrieval Modes

| Mode | Use case | | --- | --- | | lookup | Find an exact symbol, file, endpoint, or module. | | trace | Explain how a flow works or what calls what. | | bug | Localize likely files for a symptom or failure. | | architecture | Inventory the files that implement a subsystem. | | change | Find the places likely affected by a cross-cutting edit. | | skip | Avoid code retrieval for non-code prompts. |

flowchart LR
  Query["Prompt"]
  Mode{"Mode"}
  Lookup["Exact lookup"]
  Trace["Flow reconstruction"]
  Bug["Symptom evidence"]
  Arch["Layer coverage"]
  Change["Affected surfaces"]

  Query --> Mode
  Mode --> Lookup
  Mode --> Trace
  Mode --> Bug
  Mode --> Arch
  Mode --> Change
  Trace --> Resolver["Capability evidence"]
  Arch --> Resolver
  Change --> Resolver
  Resolver --> Files["Selected files with provenance"]
  Resolver --> Areas["Product areas used"]
  Resolver --> Pages["Business pages used"]

Capability Evidence

Capability evidence is generic. It does not encode customer/project names or repository-specific file lists.

For trace, architecture, and change prompts, Reporecall can:

• use matching wiki capability pages as anchors;
• hydrate their relatedFiles into real code chunks;
• add import and call neighbors from the graph;
• keep lookup prompts small and exact;
• suppress test/spec noise unless the query asks for tests.

Returned file records can include:

• selectionSource
• selectionReason
• wikiPagesUsed
• missingEvidence

Business Context Export

Reporecall exposes product-language context in three places:

• reporecall lens --json for whole-project productAreas[] and businessPages[].
• reporecall explain --json for query-specific productAreasUsed[] and businessPagesUsed[].
• MCP tools list_product_areas and business_context_query for live agent access.

These surfaces are additive product-language views over code evidence for external tools.

The schema is documented in [docs/business-context-schema.md](docs/business-context-schema.md).

Key fields include:

• productAreas[]
• displayName
• displaySummary
• areaKind
• displayQuality
• presentationSafe
• presentationIssues
• capability
• actor
• trigger
• businessTerms
• userActions
• decisionPoints
• sideEffects
• businessOutcome
• dataConcepts
• technicalEvidence
• externalSystems
• supportingFiles
• confidenceLabel

Business context is not fed back into core search as hard-coded rules. Hooks may append a small budgeted product-area evidence section for trace, architecture, and change prompts, but lookup prompts stay small and code retrieval remains grounded in source/wiki/graph evidence. Consumers should treat the business layer as a read-only product map with supporting evidence.

Lens

reporecall lens --serve --open
reporecall lens --json > lens.json

The HTML dashboard shows:

• overview stats;
• Louvain communities;
• high-degree hub nodes;
• surprising cross-module edges;
• generated wiki pages;
• product areas that group related business capability pages;
• business capability pages with product-facing summaries and supporting files.

The JSON export also includes machine-readable wiki graph data, productAreas[], and businessPages[] for other tools.

Comparison

Reporecall is a context layer, not a full AI editor, hosted model, or PR review SaaS. It is designed to improve the context that Claude Code, Codex, MCP clients, and other local coding agents receive.

For a paid/free competitor comparison across context layers, memory/rules, code graph support, business/product context, and local-first behavior, see [docs/reporecall-context-layer-competitor-comparison.md](docs/reporecall-context-layer-competitor-comparison.md).

MCP Tools

Reporecall exposes a local MCP server:

reporecall mcp --project .

Use this server from Codex or any MCP-compatible client when you want code search, flow navigation, business context, wiki pages, memory, or topology data without relying on Claude Code hooks.

Main tool groups:

| Group | Tools | | --- | --- | | Code search | search_code, get_symbol, resolve_seed | | Flow/navigation | find_callers, find_callees, explain_flow, build_stack_tree, get_imports | | Business context | list_product_areas, business_context_query | | Topology | get_communities, get_hub_nodes, get_surprises, suggest_investigations | | Wiki | wiki_query, wiki_read, wiki_write, wiki_check_staleness | | Memory | recall_memories, store_memory, forget_memory, list_memories, explain_memory, compact_memories, clear_working_memory | | Index/context lifecycle | refresh_context, get_lens_data, index_codebase, get_stats, clear_index |

Configuration

Configuration lives in .memory/config.json.

| Key | Default | Description | | --- | --- | --- | | embeddingProvider | "keyword" | Retrieval backend. keyword is local FTS-only. | | wikiBudget | 400 | Max tokens for wiki injection per prompt. | | wikiMaxPages | 3 | Max wiki pages injected per prompt. | | memoryBudget | 500 | Max tokens for memory injection per prompt. | | capabilityEvidence | true | Use code/wiki/graph evidence to select related files for trace, architecture, and change prompts. | | genericCapabilityHydration | true | Hydrate broad inventory evidence into prompt context for questions like "which files implement...". | | topologyEnabled | true | Run topology/community analysis after indexing. | | topologyMaxChunks | 50000 | Skip full topology graph construction above this indexed chunk count. | | shutdownTimeoutMs | 10000 | Graceful shutdown timeout in milliseconds. |

Assistant/client instruction files such as AGENTS.md, CLAUDE.md, .claude/**, .codex/**, and .mcp.json are ignored by default as code evidence.

CLI Reference

reporecall init
reporecall index
reporecall serve
reporecall lens
reporecall explain "query"
reporecall search "query"
reporecall mcp
reporecall doctor
reporecall stats
reporecall graph
reporecall conventions

Changelog

v0.7.1 - Self-Evaluation Patch

Patch release driven by reporecall's self-evaluation on its own codebase. Tightens seven defects in retrieval, capability evidence, indexing, and business-context routing without breaking any public API.

• reporecall index now generates deterministic wiki/business pages at the end of an index pass so list_product_areas/business_context_query work without serve. Pass --no-wiki to skip.
• Intent classifier routes "what files would I need to change" and similar phrasings to change/architecture mode.
• Bulk file deletion in the indexer now uses a single transaction, fixing a SIGILL on large delete sets.
• Wiki/business scoreFamilyEvidence no longer publishes false auth capability pages for reporecall's own infra directories, while keeping downstream React useAuth/useSession hooks classified as authentication.
• Lookup primary seeds must share at least two non-generic anchors with the query to be returned as a high-score exact hit.
• Architecture/change queries drop test files entirely (vs the prior multiplicative penalty) unless the query mentions test/spec/e2e/fixture/mock.
• Capability evidence resolver now runs for lookup mode and gates non-family queries on actual file-path anchor overlap.
• Discovered product areas can override a weak fixed match only when their score exceeds it by at least DISCOVERED_OVERRIDE_MARGIN (3).

v0.7.0 - Capability Evidence and Business Context Export

This release improves trace and architecture recall without adding project-specific rules.

• Added generic capability evidence resolution for trace, architecture, and change prompts.
• Business wiki pages can now act as evidence anchors without being blindly injected into prompt text.
• Wiki relatedFiles are hydrated into concrete source chunks when the query warrants it.
• Added selectionSource, selectionReason, and wikiPagesUsed metadata to selected files/chunks.
• Added capabilityEvidence and genericCapabilityHydration config flags.
• Added deterministic business capability wiki generation and stable productAreas[] / businessPages[] exports in lens --json.
• Added areaKind metadata for product areas so consumers can distinguish fixed, discovered, and fallback groupings.
• Added displayQuality, presentationSafe, and presentationIssues so business-facing tools can filter weak generated labels without losing technical evidence.
• Added Lens Product Areas and Business tabs for generated business capability pages.
• Added MCP business-context tools (list_product_areas, business_context_query), the lifecycle tool refresh_context, and the Lens export tool get_lens_data.
• Added a large-repo stress harness (npm run stress:large-repo, npm run stress:large-repo:ci) and chunk-count guardrails on topology/Lens graph construction.
• Documented Codex support through MCP and direct CLI usage.
• Added [docs/business-context-schema.md](docs/business-context-schema.md) for external utilities that want product-language context.
• Fixed rarest-term FTS fallback so zero-document terms do not dominate query planning.
• Fixed Lens metadata to use the target project root for projectName instead of the current shell directory.
• Filtered assistant/client instruction files from code evidence by default.
• Removed project/customer-specific examples from source tests and comments.

See [CHANGELOG.md](CHANGELOG.md) for the full package history.

Development

npm install
npm run lint
npm test
npm run build

Useful verification:

npm test -- --run test/search test/hooks test/wiki test/visualize
npm run benchmark -- --provider keyword --output /tmp/reporecall-keyword.json
npm run stress:large-repo -- --files 10000 --changes 1000 --output /tmp/reporecall-large-repo.json
npm run stress:large-repo:ci

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: proofofwork-agency
• Source: proofofwork-agency/reporecall
• License: MIT

Install and usage instructions live in the source repository linked above.