Zero-Friction Agent Substrates: Powering KruschContext & KruschGit with Swappable Local & Polygres Drives

2. The Swappable Architecture: Console, Cartridge, and Drive

Developer tooling has historically conflated the agent tool with the database hosting it. If you change where memory is saved, you have to rewrite your agent's MCP servers, prompts, and workflows.

We decouple agent intelligence into three clean, swappable layers:

• The Console: The agent-facing APIs. Cursor, Windsurf, or Claude Code talk exclusively to standard MCP tools (krusch-context-mcp and krusch-git). The model never writes raw SQL and never interacts with vendor SDKs.
• The Cartridges: Portable workspaces. Repositories (krusch-git, @krusch/toolkit), decision logs, and symbol snapshots. Cartridges can be checked into git or synced across environments.
• The Drives: Where the data physically executes. By default, developers use local SQLite and local PostgreSQL. When distributed teams need shared context, they mount Polygres Cloud as the drive.

3. Compatibility Matrix: What Belongs Where

Not every database is designed for every workload. Context is not graph; graph is not vector search; vector search is not OCR. The following matrix defines the exact boundary across our local and cloud drives:

4. Deep Dive: krusch-context as a First-Class Product

krusch-context is not a key-value store or a fuzzy chat history buffer. It is an ACID-compliant working memory substrate designed to enforce invariants and survive model swaps.

4.1 The Record (Nugget) Schema & Storage Field Map

Every piece of working memory is stored as a strongly-typed record. Whether persisted in local SQLite WAL (.agent/context.db) or synchronized to Polygres Cloud pgContext, the schema maps 1-to-1:

4.2 Multi-Agent Write Conflict Resolution

When multiple agents (e.g. Cursor modifying a frontend component while Claude Code refactors an API in the terminal) write to memory simultaneously, naive syncing creates race conditions. krusch-context uses causal monotonic sequence numbering and optimistic concurrency checks:

• Every update requires a target_id and the rule's last known state hash.
• If Agent B attempts to update Rule #12 while Agent A has already superseded Rule #12 with Rule #15, pgContext rejects Agent B's write with a StaleMemoryConflictError.
• Agent B is forced to re-hydrate active memory via retrieve(), discover the new Rule #15, and adjust its plan before touching code.

4.3 The Sanitization Invariant: What Must NEVER Sync

5. Deep Dive: krusch-git & The SHA-Pinning Join Story

krusch-git splits codebase understanding into two complementary substrates: relational AST symbol graphs (on pgGraph) and semantic code passages (on Wondersearch). But how do these two systems stay synchronized without drifting?

5.1 The SHA-Pinning Protocol

The danger of splitting graph traversal from semantic search is the split-brain index: an agent retrieves an AST symbol from HEAD, but searches for code passages that reflect a commit from last week.

To eliminate this failure mode, krusch-git binds every query and synchronization to an explicit Git commit SHA:

If the remote Wondersearch drive is still indexing a fresh push, the connector flags the SHA mismatch and falls back to local AST diffing for unstaged files, guaranteeing the agent never consumes conflicting representations.

5.2 The Refactoring Walk: resolve_controlling_clause

Let's trace how an autonomous coding agent uses krusch-git to prepare a refactor of resolve_controlling_clause() in repository krusch-biz:

import { createPolygresConnector } from '@krusch/polygres-connector';

const connector = createPolygresConnector({
  polygresUrl: process.env.POLYGRES_URL,
  wondersearchApiKey: process.env.WONDERSEARCH_API_KEY
});

// Step 1: Find authoritative AST declaration with exact line boundaries
const symbol = await connector.git.findSymbol('krusch-biz', 'resolve_controlling_clause');
// Returns: { file: 'src/backend/resolver.py', lines: [142, 280], kind: 'function' }

// Step 2: Calculate blast radius via recursive caller CTE (inbound dependencies)
const blastRadius = await connector.git.getDependencyGraph('krusch-biz', 'resolve_controlling_clause');
// Returns: 
//   Inbound Callers: src/backend/main.py:L215 (POST /conflicts), tests/test_resolver.py:L48
//   Outbound Callees: _evaluate_precedence_hop (L198), _detect_clause_conflict (L245)

// Step 3: Semantic code search with exponential recency decay applied (exp(-0.01 * days))
const passages = await connector.git.searchCode('krusch-biz', 'precedence resolution hop');
// Returns passages with decay weight 0.970 for fresh commits vs 0.026 for 2-year-old stale code

6. Empirical Parity Benchmark: 20 Pure Context & Code Operations

Below is the empirical evaluation benchmark comparing Local Substrates (PostgreSQL 5432 + SQLite WAL) and Polygres Cloud across 20 representative developer queries, proving complete parity across working memory and codebase graphs without a single external legal query:

7. Real Engineering Metrics: Local vs. Cloud Substrates

8. Getting Started in 60 Seconds

To power KruschContext and KruschGit on your choice of local or cloud substrates, follow this 3-step path:

1. Install the Connector & Configure Credentials:

   npm install -g @krusch/polygres-connector
   
   # Set your Polygres Cloud endpoint (or leave blank to default to local SQLite/Postgres)
   export POLYGRES_URL="postgresql://user:[email protected]:5432/team_db"
   export STORAGE_PROVIDER="polygres" # 'local' | 'polygres'
   export ALLOW_CLOUD=1

2. Sync Agent Memory & Codebase Graphs:

   # Push local invariants and Git AST symbols to the target drive
   krusch-polygres sync-context homelab
   krusch-polygres sync-git krusch-git

3. Query Symbols & Memory from Any Agent:

   import { createPolygresConnector } from '@krusch/polygres-connector';
   
   const connector = createPolygresConnector({
     polygresUrl: process.env.POLYGRES_URL
   });
   
   // Instant AST symbol graph lookup via pgGraph
   const symbol = await connector.git.findSymbol('krusch-git', 'find_symbol');
   console.log(symbol.file_path, symbol.location.lines);

9. Conclusion: Decoupling Agent Intelligence from Infrastructure

The future of AI coding agents is not about stuffing millions of raw code tokens into larger context windows, nor is it about locking developer tooling into proprietary cloud silos.

By decoupling agent intelligence into Consoles (stable agent APIs like krusch-context and krusch-git), Cartridges (portable codebases and decision logs), and Swappable Drives (local SQLite, PostgreSQL, or Polygres Cloud), you gain complete sovereignty.

You can run 100% locally on your laptop when working solo, mount Polygres Cloud when coordinating swarms across remote IDEs, and maintain absolute confidence that your agent's memory and code understanding will remain identical across every environment.