Context Fabric

Context Fabric is a local compiler for software-system context. Milestones 0 through 10 are implemented and audited against all 175 SRS requirement IDs. See Implementation Status for measured gates and Requirement Coverage for the complete traceability matrix.

Implemented layers include compiler-resolved TypeScript, explicit project-wide JavaScript ESM/CommonJS resolution, syntax-aware Python intelligence, and deterministic PHP symbol/include/call resolution; workspace/framework detection; bounded dependency source roots; HTTP, Confluence, OpenAPI, GraphQL, SQLite, PostgreSQL, external MCP, Figma, and Storybook sources; cross-layer domain concepts with human correction; and design-system intelligence with screenshot evidence.

Project discovery excludes generated dependency and cache trees by default, including JavaScript package/build caches and PHP Composer vendor, PHPUnit cache, Laravel compiled/cache directories, and Symfony var/cache. A separately configured dependency source can still deliberately index a bounded package root. The universal 50 MiB ceiling keeps oversized files metadata-only.

Runtime intelligence ingests OpenTelemetry, HAR, Playwright JSON traces, application and SQL logs, and Istanbul coverage. It keeps static may-call edges separate from observed execution, retains bounded aggregate traces, and exposes generic graph tracing through the shared Knowledge API and MCP.

The Context Engine combines indexed exact/prefix, full-text, graph, concept, and optional local-semantic channels under compact/standard/deep budgets. Evidence strength, confidence, and freshness affect ranking. Optional reasoning providers are disabled by default and persist only grounded proposals with provider/model/task provenance. Production hardening adds WAL, integrity recovery, compaction, bounded background workers with crash detection and capped exponential-backoff restarts, compatibility checks, source/rebuild controls, pipeline metrics, and a 2.25-million-record qualification benchmark.

Run

npm install
npm test
npm run benchmark -- 1000
npm run benchmark:scale
npm run start:headless
npm run start:desktop
npm run start:headless -- index C:\path\to\project
npm run start:headless -- search MySymbol
npm run start:headless -- mcp-stdio
npm run start:headless -- mcp-http 7341
npm run start:headless -- watch C:\path\to\project
npm run package:desktop
npm run package:matrix

The headless runtime, background indexing worker, desktop renderer, and MCP adapters consume the same core services. Plugins receive a validated KnowledgeEmitter; they never receive database write access.

The Electron application automatically runs a read-only MCP Streamable HTTP server for the active project. It binds only to loopback, normally at http://127.0.0.1:7341/mcp; the exact endpoint is shown in Settings. In MCP Inspector, select streamable-http and enter that endpoint. Switching projects restarts it against the newly active Knowledge API, and quitting the app stops it.

The desktop also stays available from the system tray. Closing the dashboard hides it while indexing and MCP continue; hovering the tray icon shows current indexing activity, and its menu can open the dashboard, start an indexing run, restart the application, or close it completely.

Project discovery hard-excludes dotfiles, agent workspace directories (.claude, .agents, .codex, .cursor, and equivalent tool state), and transient *.lock files. Recognized dependency locks such as yarn.lock, Cargo.lock, and composer.lock remain part of the project corpus.

Incremental fingerprinting retains SHA-256 content identities but uses persisted size/index time as a no-read fast path for files that have not changed. Up to 16 bounded read/hash lanes operate concurrently, scaled down against the indexing memory policy and maximum file size. When configured, isolated dependency and external-source workers run beside the primary filesystem stage through separate WAL connections; all three lanes drain before derivation begins. Filesystem watch events force a content hash, and fingerprint activity ends before parsing/extraction begins.

On first launch, the desktop asks for a project working directory before it creates configuration or index data. Settings remembers and can change that directory. Filesystem/drive roots are rejected; choose a bounded repository, monorepo, or project directory. Switching roots closes the previous project runtime and opens the selected root as a separate identity universe. Use Index project to perform the first local sync, or Clear all app data to remove Context Fabric-owned state and return to first-run selection without touching project source files. The Storage location control can move the SQLite index and blob store to a different drive; Context Fabric uses a dedicated per-project subdirectory and migrates existing data before reopening the project.

The desktop Live view streams bounded, real indexing lifecycle events, including an in-place files-scanned count during project discovery, and a clickable recent-connection graph without simulated activity. Startup explicitly reports whether the system is starting, indexing, refining, idle, or in error. Context Fabric progressively streams the complete labeled interactive graph through bounded, keyset-paginated Knowledge API pages. GPU buffers grow geometrically and are reused as pages arrive instead of imposing a fixed node or edge cap. New nodes use their incrementing graph index and the known total to spawn around a complete radial turn before simulation. During genuine idle time, small deterministic refinement batches add evidence-backed containment connections, persist their cursor, converge, and pause whenever foreground indexing begins. The default shadow resource policy lazy-starts the TypeScript parser, releases it after three idle seconds, caps background worker memory, limits foreground concurrency, and lazy-loads heavyweight dashboard projections. Hot per-file signals are sampled at 12 events per second while reporting the exact number of real actions coalesced between visible updates.

The Live view's Boost pill switches the current project between the persistent shadow background profile and performance active profile without restarting the app. Boost uses the project's full configured concurrency while retaining the same worker-memory and file-safety ceilings; the control is locked while an indexing operation is in flight.

Plugin artifact traversal is streamed in small database pages and retains at most 64 MiB of content for legacy bulk consumers. TypeScript deep resolution is isolated in batches of at most 128 files or 8 MiB, with bounded result payloads; generated bundles, minified scripts, and source maps are excluded by default.

Optional OAuth reasoning providers can also be added and signed into from Settings using the provider's device-authorization endpoints and public client ID. Sessions are encrypted with Electron's operating-system credential facility, stored outside project data, refreshed when supported, and removable with Sign out. API-key environment variables remain supported.

package:desktop builds and structurally verifies the current host bundle. package:matrix additionally creates x64 Windows, Linux, and unsigned macOS transfer bundles and writes release/packaging-manifest.json. On Windows hosts without symlink privilege, the macOS bundle uses materialized framework aliases; final macOS execution, signing, and notarization still belong on a macOS runner.

Filesystem discovery applies a built-in global exclusion policy before project rules. Common VCS, dependency, framework output, build, coverage, and cache directories such as .git, node_modules, .next, dist, target, release, .electron-package-cache, __pycache__, and .cache are skipped automatically. Project .gitignore and configured ignore rules are layered on top; dependency trees can still be indexed intentionally by configuring their directory as an explicit bounded dependency root.

Project discovery is additionally capped at 250,000 files by default to prevent an unexpectedly broad tree from exhausting the indexing worker. Set projectSource.maxFiles in .context-fabric/config.json to tune the ceiling (the runtime clamps it to 1–1,000,000).

Individual files are capped at 50 MiB. Larger artifacts are retained as searchable file metadata (path, size, extension, and revision fingerprint), but their bytes are never loaded into the indexing worker. Set projectSource.maxFileBytes to choose a lower limit; configured values are clamped to 64 KiB through the absolute 50 MiB ceiling.

External sources are declared in .context-fabric/config.json. Secret-bearing headers reference environment variables rather than storing values:

{
  "sources": [
    {
      "id": "product-api",
      "type": "openapi",
      "name": "Product API",
      "enabled": true,
      "config": {
        "urls": ["https://example.test/openapi.yaml"],
        "headerEnv": { "authorization": "PRODUCT_API_AUTH" }
      }
    }
  ]
}

PostgreSQL credentials and reasoning-provider credentials are environment references, not stored values. Optional dependencies and local semantic ranking can be enabled independently:

{
  "embeddings": { "enabled": true, "model": "context-local-v1", "dimensions": 384 },
  "dependencySources": [
    { "id": "shared-sdk", "path": "vendor/shared-sdk", "enabled": true, "maxFiles": 10000 }
  ],
  "sources": [
    {
      "id": "commerce-db",
      "type": "postgres",
      "name": "Commerce PostgreSQL",
      "enabled": true,
      "config": { "connectionStringEnv": "COMMERCE_DATABASE_URL", "schemas": ["public"] }
    }
  ]
}

Related MCP server: codemap

Specification traceability

• Canonical model and stable IDs: TAS sections 4–18

• Plugin lifecycle and scoped services: TAS sections 30–37

• Core-owned scheduling and failure isolation: TAS sections 62–65

• Candidate validation and identity: TAS sections 67–75

• SQLite, transactions, and deduplication: TAS sections 86–90

• Worker/backpressure rules: TAS sections 114–121

• Milestone 0 scope and exit criteria: SRS section 21

• Filesystem discovery and snapshots: SRS requirements FR-010–FR-017

• TypeScript symbols and dependencies: SRS requirements FR-030–FR-036

• Incremental pipeline and fingerprints: TAS sections 76–80

• Search and bounded context packs: TAS sections 81–84

• Milestone 1 scope and exit criteria: SRS section 21

• SourceProvider lifecycle: TAS sections 38–41

• Source freshness and caching: SRS requirements FR-010–FR-028

• Milestones 2–10 scope and exit criteria: SRS section 21

• Concept identity, claims, annotations, and knowledge gaps: TAS sections 19–24

• Figma/code ambiguity and rendering reliability: Risks R-027–R-029

• Runtime incompleteness, volume, and retention: Risks R-020–R-021