PolyFabric

PolyFabric helps AI coding agents understand your project using less prompt context. It indexes your code locally, finds relevant functions and references, and gives your chosen model focused snippets with file and line references. Connect it to an MCP-capable IDE or use its Python API for code search, editing assistance and debugging.

[!NOTE] Latest Head-to-Head Benchmark Evidence: Headline results below are recomputed from published records in benchmarks/results/RUN_HEAD_TO_HEAD_BASELINE_VS_IMPROVED/. Tested versions: Baseline (eda7e0e) vs. Improved (2ce529e). Later documentation/handover commits were not benchmarked. Token reductions are not verified dollar savings; provider billing deltas remain unresolved. Evidence guide → · Release readiness report →

---

1. What PolyFabric Does

• Finds relevant code: Resolves exact AST symbols (<15 ms), lexical matches, and vector semantic candidates without sending entire files to models.
• Builds focused context: Assembles line-bounded code intervals and reference definitions into a compact prompt payload.
• Shows traceable provenance: Annotates every evidence snippet with repository, file path, symbol name, and line numbers.
• Fits existing agent workflows: Connects as a standard Model Context Protocol (MCP) stdio server or in-process Python library; the coding model still generates the answers and edits.

A practical example

Developer request: “Change the soil-moisture alert threshold.”

Instead of dumping multiple whole source files (e.g. 10k–30k tokens) into the prompt, PolyFabric locates the exact alert interface and threshold logic. The agent receives focused snippets (~350–800 tokens), plans the edit, and runs its standard build and test verification.

---

2. Latest Results: Head-to-Head Comparison

The completed head-to-head benchmark compares baseline PolyFabric (eda7e0e) with improved PolyFabric (2ce529e) on FarmWatch pinned to commit 201321eb045f9b5170007fc26def90e4d13bf564, evaluated with gemini-2.5-flash via Helix Gateway.

Matrix: 26 tasks $\times$ 3 trials $\times$ 2 arms = 156 evaluated attempts (78 attempts per arm), with at most one repair per attempt.

Verified Evidence Distinctions & Known Limitations

• Recomputed from published records: All headline metrics above were verified and recomputed from raw per-attempt records in benchmarks/results/RUN_HEAD_TO_HEAD_BASELINE_VS_IMPROVED/ (493 files, SHA-256 verified in checksums.sha256).
• Token reductions $\neq$ verified dollar savings: LiteLLM gateway reported spend ($0.1869) vs. client formula spend ($0.0676) remains UNRESOLVED pending itemized transaction logs.
• Tested commits: Metrics belong to tested commits eda7e0e and 2ce529e. Later documentation and handover commits were not benchmarked.
• Older comparisons (vs. rg and Whole-File Context): Detailed historical results comparing early PolyFabric against ripgrep and whole-file context are preserved in the Evidence Guide.
• Targeted pilot checks: Release candidate 9ca5287 was verified for MCP write rejection, byte immutability, and relative CLI paths in PILOT_VERIFICATION_9CA5287.
• StructZero integration: Integration with StructZero remains planned; the benchmark evaluated PolyFabric standalone.

---

3. Compact Architecture

flowchart TD
    Source["Project Source Code"] --> Parser["Tree-sitter AST Parser & Chunking"]
    Parser --> Embedding["FastEmbed Local ONNX (BAAI/bge-small-en-v1.5)"]
    Parser --> FTS["Tantivy Lexical / Exact Symbol Index"]
    Embedding --> LanceDB["In-Process LanceDB Vector Store"]
    
    Task["Developer Request / Agent Task"] --> System1["System 1 Hybrid Retrieval (RRF Fusion)"]
    FTS --> System1
    LanceDB --> System1
    
    System1 --> Context["Line-Bounded Evidence Context (<=350 tokens/chunk)"]
    Context --> Agent["AI Coding Agent / LLM (Cursor, Claude Code, etc.)"]
    Agent --> Review["Developer Review & Verification (Build / Test)"]

---

4. Quickstart & Installation

For a step-by-step pilot onboarding walkthrough, consult PILOT_QUICKSTART.md.

Easiest Option: Paste This Prompt into Your Coding Agent

Set up PolyFabric for this project's code search and task context:
https://github.com/vishalvermauts/PolyFabric

Read its current README, PILOT_QUICKSTART.md, and source before setup. Clone PolyFabric
into a separate tools directory outside my target project, check out tag v0.2.0-rc1,
create a dedicated Python virtual environment, and install it with python -m pip install -e .

Use this project's absolute root and a unique project name. Set an isolated,
absolute INFINITE_MEMORY_HOME and INFINITE_MEMORY_DB_PATH outside the source
tree; use the same values for indexing and the MCP server.

Configure this IDE's supported MCP settings using the virtual environment's
absolute Python executable, args ["-m", "infinite_memory.server"], and:
POLYFABRIC_ENABLE_SERVER=1
POLYFABRIC_READ_ONLY=1
INFINITE_MEMORY_HOME=
INFINITE_MEMORY_DB_PATH=

Preserve existing MCP settings. If this client cannot configure MCP
automatically, show me the exact configuration and restart instructions.
Do not claim the connection works until you initialize MCP and list tools.

Index/register my project through mesh_index_repository(project_name,
repository_path). Inspect indexing errors and chunk counts. Demonstrate
mesh_build_task_context on a real symbol or feature from this project.
If it is empty, explain that there is no source to retrieve yet.

For later coding tasks, call mesh_build_task_context before proposing edits;
use project-scoped search and expand incomplete evidence with direct reads
or exact reference searches. Refresh the index after source changes.
Do not assume all callers or imports are present in bounded context.

Keep PolyFabric source-write mode disabled. Let the coding agent propose
changes through its normal review, build and test workflow. Do not alter my
project merely to demonstrate setup, run benchmarks, or make paid LLM calls.
Report install location, installed Git commit, project name, state paths,
MCP connection status, and a sample retrieval.

Manual Installation

Requires Git and Python 3.10+. No generative AI API key is needed for local retrieval.

git clone https://github.com/vishalvermauts/PolyFabric.git
cd PolyFabric
git checkout v0.2.0-rc1
python -m venv .venv

macOS / Linux:

.venv/bin/python -m pip install -e .
export INFINITE_MEMORY_HOME="$HOME/.polyfabric/my-project"
export INFINITE_MEMORY_DB_PATH="$HOME/.polyfabric/my-project/db"
export POLYFABRIC_READ_ONLY=1
.venv/bin/python -m infinite_memory.cli register my-project /absolute/path/to/project

Windows PowerShell:

.\.venv\Scripts\python.exe -m pip install -e .
$env:INFINITE_MEMORY_HOME = "$env:USERPROFILE\.polyfabric\my-project"
$env:INFINITE_MEMORY_DB_PATH = "$env:USERPROFILE\.polyfabric\my-project\db"
$env:POLYFABRIC_READ_ONLY = "1"
.\.venv\Scripts\python.exe -m infinite_memory.cli register my-project "C:\absolute\path\to\project"

Connect Through MCP

Add the following to your IDE’s MCP configuration (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "polyfabric": {
      "command": "/absolute/path/to/PolyFabric/.venv/bin/python",
      "args": ["-m", "infinite_memory.server"],
      "env": {
        "POLYFABRIC_ENABLE_SERVER": "1",
        "POLYFABRIC_READ_ONLY": "1",
        "INFINITE_MEMORY_HOME": "/absolute/path/to/polyfabric-state/my-project",
        "INFINITE_MEMORY_DB_PATH": "/absolute/path/to/polyfabric-state/my-project/db"
      }
    }
  }
}

Note: On Windows, use C:/absolute/path/to/PolyFabric/.venv/Scripts/python.exe and absolute Windows paths.

---

5. Supported Pilot Scope & Critical Boundaries

• Monitored Developer-Reviewed Scope: PolyFabric is approved as a read-only code-context component for existing-code exploration, editing assistance, and debugging. All proposed code edits must be reviewed and tested by a human developer or host agent.
• Fail-Closed Read-Only Protection: Setting POLYFABRIC_READ_ONLY=1 strictly disables PolyFabric’s mesh_write_file tool. It does not block internal index creation/updates, nor does it block edits made by the host IDE/agent via other tools.
• Reference Completeness: Bounded context retrieves high-probability snippets; it does not guarantee 100% transitive call-graph coverage. Always verify imports and call sites before executing large cross-file refactors.
• Local Compute & Memory: FastEmbed downloads ONNX weights (~130 MB) on first run. Memory consumption scales with codebase size; FarmWatch peak indexing RSS measured 1.54 GB. Size host environments appropriately.

---

6. Technology Stack

---

7. Evidence Links & Documentation

• Pilot Quickstart Guide — Pilot setup, runtime bounds, rollback instructions, and feedback template.
• Evidence Guide — Recomputed benchmark metrics, historical search baselines, and limitations.
• Head-to-Head Benchmark Evidence Directory — All 493 raw attempts, ledger, manifest, and SHA-256 checksums.
• Candidate 9ca5287 Verification Evidence — MCP read-only denial, byte immutability, and CLI path normalization records.
• Release Readiness Report — Comprehensive independent audit and release assessment.