AI's tech debt is invisible — even to AI. I solved it at the architecture layer.

TL;DR — AI repeats your patterns badly, ignores existing services, and forgets every cross-session lesson you taught it. This isn't laziness — it's a new kind of tech debt: invisible, systemic, and architectural. Project memory hints don't scale. Bigger context windows don't help. The fix is structural: pin a graph projection of your codebase to every commit, let AI read it before writing, surface "graph stale" prompts when source drifts. Real commit receipts from my own OSS project (open-source cross-platform AI agent runtime, 274+ stars). I asked AI to add a stateService.

The directory server/services/ already contained, in clear sight:

CODE Kopieren

TOOLBOXCLIENT/server/services/

├── fingerPrintService.js

├── memoryService.js

├── providerModelService.js

├── proxyService.js

├── taskService.js

├── toolServiceManager.js

├── walletService.js

└── webSocketService.js

Roughly a dozen services, all sharing the same HTTP pattern.

What AI shipped (commit , 2026-03-21):

CODE Kopieren

feat: stateService Phase A+B — HTTP CRUD + SSE broadcast



Phase A: /api/state/* routes (read, write, session CRUD, language pref)

Phase B: SSE subscribe endpoint with topic filtering + EventBus broadcast



74/74 tests pass. No breaking changes — additive only.

WebSocket gone. HTTP CRUD + SSE matching the existing pattern. Clean fix.

For about ten seconds, I thought I'd solved it.

Why project memory hints don't scale

Then I realized something uncomfortable:

This catch only worked because I noticed.

The next AI session would start with zero memory of this lesson.

Every context window starts as a blank slate.

This is the systemic nature of AI tech debt:

• AI can't see existing patterns when it writes


• I see it → I fix it once → the fix doesn't propagate to future sessions


• Manual project memory maintenance puts the work back on me, not AI


• This doesn't scale — and the failure mode is silent

The first insight

I stopped trying to fix prompts and started looking at the structural problem:

AI agents don't need bigger context windows.

They need a persistent structural record of the project that survives across sessions.

Context windows are short-term memory. What's missing is long-term, project-level memory — something any AI session can read before writing.

This is the insight that turned into aming-claw.

Building aming-claw (and falling into the next trap)

The idea: give every AI session a queryable graph of the project. Files, modules, functions, patterns — all of it, machine-readable, persistent.

• Scan the codebase → build a graph of all entities and relations


• Expose it through an MCP server that any agent can query


• AI reads the graph before writing
  


• Graph persists across sessions
  

I built it. It worked. Then it broke — at a higher layer.

I had implemented the graph with:

• 
  Mutable nodes — agents could edit graph state directly


• 
  A patch pipeline — 5-stage mutation flow (propose → validate → review → apply → snapshot)


• 
  A graph editor UI — humans could also edit the graph

Within a few weeks, the graph drifted from the actual code.

Why? Because I had created a second source of truth:

• The real source of truth was source code


• But I also let the graph be directly mutated


• The two sources inevitably diverged

Same trap. Higher layer.

The real architectural insight

After hitting the same trap twice, the answer crystallized:

The graph is something you edit.

The graph is a projection of the commit.

In concrete terms:

Every commit can correspond to one graph

CODE Kopieren

git commit (modifies source / hints / config)

     ↓

system detects: HEAD ≠ graph's bound commit

     ↓ ⚠️ "graph stale" prompt

user decides when to reconcile

     ↓ user-triggered

fixed_algorithm(source + hints + config)

     ↓

new graph snapshot ←→ new commit hash

4 key invariants

#	Invariant	What it guarantees
1	Fixed algorithm	Same input → same graph (deterministic, no randomness)
2	1:1 binding	Every commit hash maps to exactly one graph snapshot
3	User-triggered	Reconciliation is explicit, not a background git hook
4	Stale prompt	System surfaces drift in dashboard / CLI; user triggers when ready

Why not a git hook?

A reasonable question: why not auto-rebuild the graph on every commit via a git hook?

Three reasons I deliberately didn't:

1. 
   Reconciliation is expensive (full codebase scan + algorithm)


2. 
   Surprise auto-builds destabilize state — user should control when state changes


3. Batching commits before a single reconcile is often what users want

The system shows a graph stale indicator in dashboard and CLI. Users reconcile when they're ready. This is a deliberate design choice, not a limitation.

How modification and rollback work

Operation	Implementation
Modify the graph	Modify source / hints / config → trigger reconcile
Roll back the graph	git revert → trigger reconcile
Verify consistency	Same commit → same graph (replayable)

Logic lives in code. The graph is a read-only projection.

How this solves AI tech debt

Returning to the original problem: AI repeats patterns badly because it can't see the codebase.

The architectural fix:

1. Every AI session starts by querying the graph (via MCP)


2. The graph records the full structure — files, functions, modules, patterns


3. AI sees, for example, existing HTTP service pattern in server/services/
   


4. AI reuses the pattern instead of shipping a parallel WebSocket implementation


5. After AI makes changes → user commits → system flags graph as stale → user reconciles → next session sees updated patterns

Cross-session knowledge transfer happens through the graph, not the prompt.

This is what "solved at the architecture layer" means: it's not a smarter prompt, it's a different topology of state.

Coming up: the algorithm itself

This post covered why the projection model works. The next post covers how the algorithm builds the graph:

• in-degree=0 entry detection


• DFS 3-color marking


• Tarjan SCC for cyclic clusters


• 6-signal layer scoring


• Cross-language fact pipeline (Python + TypeScript)

Follow me here to catch the next one.

Change my mind

I claim this architectural pattern solves AI tech debt: every commit corresponds to one graph + user-triggered reconcile + stale-state prompt.

Your turn. Two architectural choices:

• Treat project state as a single source of truth, commit-bound
  


• Or maintain a separate memory store that AI writes to

Which is more robust? Which scales better? Where would you attack my approach?

Calibrated invitation: I want senior engineers and AI infra people to push back with specifics. "What about X?" or "Have you considered Y?" lands better than "this won't work." If you've shipped something adjacent, tell me — I want to compare designs.

Vollständiger Original-Bericht

Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

↗ Original-Artikel auf dev.to lesen