Provenant

🧠 Provenant

Provenant is a Command Line Interface (CLI) and MCP server designed to give AI coding agents a local memory layer for your repository. Integrate Provenant into Claude Code, Cursor, Windsurf, Cline, Copilot, or any MCP-compatible agent to retrieve focused, cited codebase context instead of repeatedly loading raw files.

Provenant reads your codebase, builds generated wiki pages, tracks symbols and dependencies, extracts git history, scores risky files, detects dead code, and exposes all of it through agent-friendly tools. It runs locally against your existing Git repository and stores its index in .provenant/.

Using a codebase memory layer for coding agents offers a range of benefits:

• Lower token waste: Give agents compact wiki context instead of thousands of raw source tokens.
• Faster file localization: Help agents find the files that matter before they start editing.
• Grounded answers: Return cited context so claims can be traced back to repository evidence.
• Safer changes: Surface risk, dependency centrality, dead-code signals, and likely blast radius.
• Architectural memory: Answer "why does this code exist?" using git history and decision context.
• Self-improving retrieval: Low-confidence answers can trigger background wiki repair.
• Editor portability: Use the same memory layer from any MCP-compatible coding agent.

🧭 The Problem

AI coding agents waste context. They search, open, and re-read raw files until they stumble into the right part of the repo. That works on small projects. It breaks down when the system has history, hidden dependencies, stale code, risky modules, and architectural decisions buried across commits.

Provenant builds a local codebase intelligence layer before the agent starts guessing.

It turns your repository into searchable, cited memory: generated wiki pages, dependency structure, symbol-level context, git archaeology, dead-code signals, risk scoring, and repairable retrieval indexes. Your agent asks Provenant for focused context instead of dragging raw file sprawl into every prompt.

⚡ Quickstart

pip install provenant

provenant init ./myrepo        # index repo, generate wiki, build retrieval state
provenant serve ./myrepo       # MCP server + local web dashboard

Use Provenant from Claude Code, Cursor, Windsurf, Cline, Copilot, or any MCP-compatible coding agent:

{
  "mcpServers": {
    "provenant": {
      "command": "provenant",
      "args": ["serve", "/path/to/repo"]
    }
  }
}

📊 Evaluation

Provenant was evaluated on SWE-bench Verified: 500 real GitHub issues across 12 Python repositories.

File Coverage@5 means the correct issue-relevant file appears in the top 5 retrieved results. File Coverage@10 uses the top 10. MRR is mean reciprocal rank.

Evidence trail:

• Evaluation summary
• Benchmark artifacts
• Read the whitepaper

A longer research manuscript is currently under submission.

🧠 How It Works

repo
  -> tree-sitter parse
  -> symbol + import graph
  -> generated wiki pages
  -> BM25 / vector / HyDE retrieval
  -> cited MCP answers
  -> confidence-gated repair

🔌 MCP Tools

🧰 What You Get

Codebase wiki

provenant init parses your repo with tree-sitter across 15+ languages and generates plain-English wiki pages for every file: purpose, public API, key functions, relationships, and implementation notes. The wiki is stored locally in .provenant/.

Attribution confidence

Every answer computes confidence = cited pages / retrieved pages. Low confidence is a signal that the wiki or retrieval index should be improved. Provenant uses that signal for repair instead of blindly trusting the first answer.

Self-healing index

Low-confidence answers can trigger background wiki repair. Agents do not wait on repair, and confidence-gated rewrites prevent uncontrolled churn. In the Django repair study, 2 of 4 low-confidence queries improved, average judge score moved from 4.50 to 4.75, and only 10 of 1,393 pages needed rewriting at about $0.02.

Dependency and risk graph

Provenant extracts file nodes, symbol nodes, imports, inheritance, mixins, and trait impls where supported. PageRank and betweenness centrality identify central code; risk scoring combines change frequency, dependency centrality, and test coverage gaps.

Dead-code analysis

Find unreachable functions, classes, and modules. Findings are grouped by confidence tier and marked safe-to-delete when Provenant can avoid dynamic-call ambiguity.

Git archaeology

provenant_why traces why code exists: git blame, related commits, and architectural decisions linked to the files your agent is editing.

🖥️ Web Dashboard

provenant serve ./myrepo

The local dashboard visualizes wiki pages, graph structure, dead-code findings, risk scores, repair candidates, and retrieval state. It is useful when you want to inspect the same memory layer your agent is querying.

🧩 Monorepos

provenant init ./my-project
# Detected 3 repositories:
#   backend/     Django
#   frontend/    React/TypeScript
#   mobile/      React Native

Each sub-repo gets its own wiki. Cross-repo context is linked so frontend questions can surface backend files and backend questions can surface client usage.

⚙️ Configuration

Set one LLM provider for wiki generation and answer synthesis:

ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
DEEPSEEK_API_KEY=...
GEMINI_API_KEY=...

Choose an embedder:

provenant init ./myrepo --embedder local     # free, small local model, no API key
provenant init ./myrepo --embedder openai    # hosted embeddings, stronger retrieval

Optional embedding settings:

OPENAI_EMBEDDING_API_KEY=...
OPENAI_EMBEDDING_MODEL=nomic-embed-text-v1.5
OPENAI_EMBEDDING_BASE_URL=https://api.fireworks.ai/inference/v1

Provenant is self-hostable and has no product telemetry. Repository indexes stay local; only the configured LLM or embedding calls leave your machine.

✅ When To Use Provenant

Use Provenant when:

• Your agent keeps opening too many files before making progress.
• The repo is old enough that "why does this exist?" matters.
• You need cited answers instead of plausible summaries.
• Risk, dead code, and dependency structure matter before edits.
• You want MCP tools that work across editors instead of a single-agent plugin.

📄 License

MIT