Infinite Code Next

A zero-config MCP server that gives AI coding agents persistent, verifiable memory of a codebase — the decisions behind it, what was already tried and rejected, and what must never break — anchored to the code and carried with it as the code moves.

Quick start · Explorer · Sharing · For agents · How it works · Brand

Git blame tells you who changed a line. This tells an agent why the code exists, what was already tried and rejected, and what must stay true — and it knows when its own knowledge has gone stale.

The problem

Every session, an AI agent arrives with no memory. It reads files to re-derive what the last agent already knew. Then it re-proposes the fix that was rejected three months ago, because nothing in the repository records that it was tried.

The expensive knowledge is never in the code:

This server stores that layer, keeps it attached to the code, and tells you when it can no longer vouch for it.

Quick start

pip install -e .

Register once with your MCP client — there is no second step. No admin panel, no port, no daemon, no per-repository setup.

claude mcp add icn -- infinite-code-next

[mcp_servers.icn]
command = 'infinite-code-next'
args = []

{ "mcpServers": { "icn": { "command": "infinite-code-next" } } }

The server works out which repository it is in from its working directory, and every response echoes the root it resolved, so a wrong workspace is obvious immediately.

The loop

workspace(action="open")          →  a briefing: rules, prior failures, what is unverified
investigate("what you're doing")  →  code + rationale + blast radius, budgeted
        ... do the work ...
record(summary=..., warnings=[...], failed_attempts=[...])

Two calls to get productive. One to leave the next agent smarter.

The knowledge explorer

Everything the server knows — repository, files, symbols, memories, and every edge between them — as one interactive graph.

./explore.sh          # macOS / Linux
explore.bat           # Windows
icn-explore           # if the package is on your PATH

Above: the export menu open over the full graph.

Self-contained: one HTML file with the data inlined. No CDN, no build step, no npm. Save it, email it, commit it — it still works.

icn-explore --no-serve -o graph.html    # just write the file
icn-explore --port 8080                 # pick the port
icn-explore --include-deleted           # include tombstoned code

Sharing knowledge

Hand another codebase's hard-won knowledge to someone else — or to another agent.

From the explorer

The Export button offers everything below without leaving the page. It all runs offline in the browser against the embedded graph — no server call, so a saved page still exports.

From the CLI

icn-explore export -o knowledge.md      # readable markdown, renders anywhere
icn-explore export -o knowledge.icn     # bundle: markdown + graph
icn-explore export -o graph.json        # raw graph

The markdown is the canonical shareable form, and it is readable on its own — in an editor, in a diff, on a wiki, in a pull request. A knowledge base nobody can read without the tool is a knowledge base nobody checks. A JSON block at the end makes the import lossless.

icn-explore import knowledge.icn        # bring it in
icn-explore import ./team-knowledge/    # a whole directory of .md / .icn
icn-explore import shared.md --preview  # look first, import nothing

Import never overwrites. Everything from outside is stored as authority='imported' with its origin attached, and anchored only where a matching symbol actually exists here. A memory about code you do not have is still worth keeping — but it must not claim to describe a span it never saw.

Guide for AI agents

Read this section before your first call.

1. Open first — do not read files to orient yourself

workspace(action="open")

Returns a briefing: the rules that govern this code, what has already been tried and rejected, what is currently unverified, and where knowledge is concentrated. Headlines and ids only — bodies stay out, investigate() is one call away.

This exists because of a measured failure. Every session building this server began by reading files to re-derive knowledge that already existed. open used to report symbol counts, which tells you nothing about what you are walking into. You cannot ask the right question before you know what is on the shelf.

2. Investigate in plain language — not with grep

investigate("I need to change refresh token rotation. What will I break?")

One call fuses lexical search, symbol lookup, code-graph traversal, memory-graph traversal, anchor status and git history, and returns compact capsules under a token budget. It searches code and knowledge together, so a warning finds you even when you never named the file it lives in.

3. Before deleting anything load-bearing, ask why

investigate(action="why", symbol="RefreshCoordinator.acquire")

decision: Use refresh-token rotation
  --was followed by--> bug_history: Parallel refresh requests invalidate each other
  --was followed by--> failed_attempt: Redis mutex could deadlock during a partition
  --was followed by--> * invariant: All refreshes pass through RefreshCoordinator

may reintroduce: Parallel refresh requests invalidate each other
regression tests: test_parallel_refresh_regression

A flat list of five memories makes you reconstruct the story. A chain hands it over.

4. Record what you learned — especially the failures

record(
    kind="bug_fix",
    summary="Serialize refresh requests per session",
    reasoning="Parallel requests rotated the same token.",
    invariants=["All refreshes for one session pass through RefreshCoordinator"],
    warnings=["Do not bypass RefreshCoordinator for new refresh entry points"],
    failed_attempts=["Redis mutex deadlocks during a network partition"],
    symbols=["RefreshCoordinator.acquire"],
    tests=["test_parallel_refresh_regression"],
    caused_by=[previous_memory_id],
)

failed_attempts is the highest-value field in the whole system. Nothing else in your toolchain records what was tried and rejected, and it is what future agents find most expensive to rediscover.

record() returns primary_memory — the id representing this event. Pass it as the next caused_by.

5. Trust the labels

Every memory carries an anchor_status. Anything other than ACTIVE has not been verified against the current code — treat it as a lead, not a fact.

memory(action="verify", memory_id=..., reason="confirmed it still applies")
memory(action="guard", memory_id=rule_id, body=test_memory_id)
memory(action="supersede", memory_id=..., body="what is true now")

How it works

Anchors that know when they are stale

A memory is not stored at src/auth/oauth.ts:193. Line numbers are a rendering detail. Each memory attaches to a semantic anchor: the symbol path, an AST path, a content fingerprint (structure + identifiers), a skeleton fingerprint (structure only), and its surrounding context.

When code changes, a cascade relocates the anchor — cheapest test first:

Two rules make this trustworthy:

• Verification fires on the edit that caused the drift, not on a timer.

• The cascade can only lower trust, never raise it. Once DRIFTED or NEEDS_REVIEW, only an explicit memory(action="verify") returns an anchor to ACTIVE — otherwise the next pass would find its freshly re-anchored fingerprint matching, report "unchanged", and quietly re-trust a memory nobody ever confirmed.

Problem detection

investigate() narrows to a subgraph first, then asks targeted questions of it — never a workspace-wide scan. What separates these from a linter is that they are knowledge-aware: a linter sees a function has no test; only this graph knows the function is governed by an invariant recorded after a production incident.

A failing detector never breaks the search: a diagnostic enhances an answer, it is not a precondition for one.

No LLM in the loop

record() is fully deterministic — entity resolution, edge derivation and contradiction detection are graph operations, not model calls. No API key, no network, no token cost. Ranking is a static, inspectable formula with per-intent weights, because a fresh local install has no labeled relevance data to train a reranker on.

Search that tolerates how people type

Exact and prefix matching runs first; when it finds nothing, an approximate pass takes over, so subproces still finds the subprocess warning. Hyphenation is bridged in both directions — reanchor finds text saying re-anchor and vice versa — because FTS5's tokenizer splits on hyphens and neither spelling would otherwise reach the other.

The fallback is deliberately a fallback: FTS ranking beats anything computed locally when it has hits at all, so running fuzzy matching by default would let loose matches outrank exact ones.

Ranking learns from use

Every memory tracks how often it was surfaced and how often an agent opened it in full. Opening is weighted far higher — being shown only means the query matched, while being opened means an agent chose it out of everything it saw.

The boost is bounded at 0.5 and decays with a 45-day half-life. Frequency is evidence, not authority: unbounded, it would pin last month's popular memory above a critical warning recorded yesterday.

Storage

%LOCALAPPDATA%\InfiniteCode\               (Windows)
$XDG_DATA_HOME/infinite-code/              (Linux)
~/Library/Application Support/InfiniteCode/ (macOS)

  catalog.db                repositories, aliases, checkouts, cross-repo edges
  data/repos/<id>/repo.db   DURABLE      code graph, memories, anchors, events
  cache/repos/<id>/         REBUILDABLE  safe to delete at any time

<repo>/.agit/               agent git, gitignored
<repo>/.icn.toml            optional, committed, tiny

Override the root with INFINITE_CODE_HOME.

Identity is never the path and never the remote URL — both are mutable. It is derived from the root commit, an optional committed project id, and normalised remotes, so moving a clone or running git remote set-url reattaches to existing knowledge. A fork shares upstream's root commit, so it is split explicitly rather than silently inheriting upstream's memories.

Nothing is ever destroyed

• Deleted symbols become tombstones with their last known path and the commit that removed them.

• Edges carry valid_from_commit / valid_until_commit and become HISTORICAL rather than disappearing.

• A vanished checkout is MISSING; an unmounted drive is OFFLINE. Neither deletes anything.

• Corrections version the previous text; supersession keeps both memories and the link between them.

• An agent cannot rewrite a human-authored memory — it must supersede it, leaving the disagreement visible.

• purge is the only destructive operation, and requires confirm=True.

Lookups go through a resolver that never raises: "cannot currently resolve" is returned as data, with whatever was last known.

Brand

The mark is the product's one idea: a piece of knowledge (violet) anchored to code (green) that would otherwise carry no memory of it. The ring is left open — knowledge is never finished being verified.

Stroke weights are set so the shape survives to a 16px favicon: the memory node stays dominant and the three anchors read as a triangle even when the ring blurs away.

One rule governs the whole UI: structure is quiet, knowledge is loud. CALLS and DEFINES recede into the background so that anchor and causal edges — the thing no other tool can show you — carry the colour.

Assets live in assets/; the explorer's own source is src/icn/web/:

src/icn/web/
  explorer.html    shell and markup
  explorer.css     the design system above, as custom properties
  explorer.js      force layout, canvas rendering, inspector
  mark.svg         logo
  banner.svg       header

Real .html, .css and .js rather than string literals, so an editor treats them as what they are. They are inlined at render time, because the published page must stay a single self-contained file.

Tools

agit keeps agent checkpoints in .agit/, entirely separate from the user's .git. Checkpoint risky work, restore it, never touch their history.

Testing

python -m pytest

172 tests, including a live MCP suite that spawns the real server over stdio and drives a full agent workflow through the wire protocol, and a dirty-worktree harness that asserts cascade behaviour on uncommitted edits — reformat, rename, body change, cross-file move, delete, weak migration.

That regime is unvalidated by the published literature, which only ever measures post-hoc commit-history mining, so it is measured here directly.

The live test earns its keep. It found a bug in-process testing cannot see: subprocess calls inherited the server's stdin, which is the MCP protocol pipe. Git blocked on it for its full 20-second timeout on every tool call and could swallow protocol bytes. Fixing it took tool latency from 20s to 0.2s.

Measured on a real 4,621-file repository

Design

The reasoning behind each decision lives next to the code it governs: every module's docstring states what it does and, more importantly, which failure it exists to prevent. anchors.py explains why the cascade may only lower trust, briefing.py why open volunteers a summary, causal.py why causality is asserted and never inferred.

Planning notes are kept locally and are not part of the shipped artifact.

Built by Ranit Bhowmick

If an agent had to read your codebase to understand it, that knowledge died with the session. This is the fix.