We Spent Months Teaching AI to Read Our Codebases. We Forgot to Teach It How to Remember.
Every developer has had this session: You spend three hours pair-programming with Claude, Cursor, or Codex. Together, you untangle a gnarly race condition in authentication, discard three plausible dead-ends, decide on an RS256 token strategy, and touch seven files.
The tests finally pass. You commit the code. You close the chat tab.
And in that single keystroke, every drop of architectural reasoning, every discarded alternative, and every piece of developer intent evaporates into thin air.
Tomorrow, when you or your teammate open a new session with the same agent in the same codebase, the model starts with complete amnesia. It doesn’t remember why you avoided that library. It doesn’t know what you plan to do next. It has to re-read, re-grep, and re-hallucinate its way through your repository from scratch.
As an industry, we spent the last two years obsessing over how to shove repository context into the model. We wrote AGENTS.md, dialed in vector embeddings, tuned token budgets, and built MCP servers.
We taught the agent how to read. But we completely neglected the return trip.
Today, we are releasing TokenCap v2.7.0 — "The Loop". It is built around a single engineering thesis: a finished AI session must become a small, redacted, reviewable handoff back into the repository — without dumping raw transcripts, without surveillance telemetry, and without silent changes to your code.
The Three-Hour Epiphany That Dies on Tab Close
When human engineers finish a sprint or an incident, disciplined teams write a handoff note, a PR description, or an Architecture Decision Record (ADR). It takes five minutes, and it preserves sanity for whoever touches the code next.
With AI coding agents, we went in the exact opposite direction.
Because LLMs feel ephemeral, we treat the conversation like scrap paper. Telemetry from engineering studies in 2026 shows that developers working with AI assistance are now juggling 67% more task and PR contexts per day than they were a year ago. Work restarts are up, and tasks sit abandoned for days because context switching between fragmented AI chats is exhausting.
The problem isn't the model's intellect. The problem is that the conversation-to-repository loop is completely broken.
When an AI session ends, you are forced to pick between two awful extremes:
- Raw Transcript Hoarding: Stashing 80,000 tokens of chat chatter, polite conversational filler, and aborted code snippets into a giant wiki or database that nobody (and no LLM) will ever afford to re-read.
- Total Amnesia: Closing the window and accepting that tomorrow's session will cost another $1.50 in tokens just to re-discover what you solved today.
Neither of those belongs in a serious engineering system.
"We gave AI agents structured documentation so they could onboard into our repos, but we left them with no mechanism to hand their work back to the team."
Why We Refused to Let Models Silently Edit Your Memory
When we started designing the return leg of TokenCap in v2.7.0, the most common suggestion was: "Just have the model automatically update the memory files and git commit on exit."
We explicitly refused to build that.
AI agents hallucinate. They make optimistic claims about tests they didn't run. They invent dependencies that don't exist. If an agent can silently edit your durable repository memory or your Constitution records in the background, you haven't closed the loop — you've created a slow-motion context-poisoning machine.
In TokenCap v2.7.0, session capture is governed by Staged Inbound Memory:
Finished AI Session
│ (POST /capture or tokencap remember)
▼
1. Validation & Hard Clamps (max 8KB, 60 lines, path normalized)
▼
2. Centralized Secret Redaction (tokens, keys, certificates stripped)
▼
3. Graph-Grounded Quality Scoring (path validity, groundedness, novelty)
▼
`.tokencap/memory/inbound/` ← STAGED (never silent)
│
├─ tokencap remember --list
├─ tokencap remember --approve <id> ──► Promotes to .tokencap/memory/sessions/
└─ tokencap remember --reject <id> ──► Audited, never enters memory
Nothing modifies durable project memory until a human developer types tokencap remember --approve. It is reviewable, provenance-stamped, and 100% deterministic.
Scoring Grounding, Not "Truth"
One of the hardest engineering challenges in v2.7.0 was designing the quality gate. How do you evaluate whether a session summary written by an AI is safe to ingest?
Most tools attempt to use a secondary LLM to judge the first LLM. That adds cost, latency, non-determinism, and network egress.
TokenCap does something fundamentally different: we score grounding against your local AST knowledge graph.
- Path Validity: Did the summary reference files that actually exist in the git tree?
- Groundedness: When the summary claims it changed
validateToken, does that symbol actually exist in the AST of src/auth.ts?
- Specificity: Does the summary mention concrete functions, files, and architectural decisions, or is it vague filler like "refactored code and fixed issues"?
- Novelty: Does this duplicate a session that was already approved yesterday?
We don't claim to evaluate the philosophical "truth" of an agent's reasoning. We evaluate whether the agent's summary is structurally anchored to the ground truth of your code.
Build Health: Because 40% of Agent Failures Are Rotten Context
If you hand an agent a 2-week-old context snapshot while your git working tree has 14 uncommitted changes and unmapped files, the agent will hallucinate. Then developers blame the model.
In v2.7.0, we introduced Repository Build Health (tokencap health).
Instead of guessing whether your context layer is trustworthy, TokenCap computes an explainable 0–100 health score before every session:
$ tokencap health
Build health: 94/100 · built 1.2h ago
100 freshness — built 1h ago
90 sourceDrift — 1 uncommitted change since build
95 detection — Node.js, TypeScript, Next.js detected
90 coverage — 3/3 intelligence layers present
Remediation:
[low] 1 uncommitted file in src/auth/ -> run `tokencap make`
If your build health drops, TokenCap doesn't fail silently. It prints exact, copy-pasteable remediation steps (tokencap rebuild) and surfaces the health factor directly into MCP tools like tokencap_overview.
Honest Host Adapters (No Fake "Auto-Capture")
Every AI tooling company loves to put logos on their landing page and claim "Works seamlessly with every host!"
We took the opposite path in v2.7.0.
Run tokencap remember --hosts in your terminal today:
| Host | Capture Level | Honest Reality |
|---|
| Claude Code | Assisted | Hooks exist, but session-end lacks a reliable native hook. Falls back to remember. |
| Cursor | Manual / CLI | Background extension cannot observe chat window termination. |
| Windsurf | Manual / CLI | Extension sandbox does not provide conversation-end lifecycle hooks. |
| Antigravity | Native MCP | Discovers staged inbound memories; manual review preserved. |
| Codex | Assisted | Staged review via CLI; never auto-committed. |
We refuse to mark any host as "automatic" unless there is a verified, un-fakable session-end signal. An MCP process shutting down is not a conversation end — it's often just an editor reloading a window. Treating process kills as session saves corrupts repositories. TokenCap tells you the truth about what each host can and cannot do.
Closing the Loop Without Giving Away Your Sovereignty
The easiest way to build session memory would have been to spin up a SaaS cloud, ask you to paste an API key, upload your chat logs to an external database, and charge you $20/month per seat.
TokenCap v2.7.0 sticks strictly to our Four Laws:
- Zero Network Egress: 100% of computation — the AST graphs, the secret redactions, the health scores, the staging engine — runs on your CPU. Not a single byte leaves
127.0.0.1.
- Strictly 4 Dependencies: Zero native compilation toolchains. Pure Tree-sitter WebAssembly.
- Budget-Capped: The latest approved session handoff (
tokencap handoff) is formatted into clean, tight Markdown that fits comfortably in under 800 tokens.
- Local Sovereignty: Your code, your memories, and your architectural intent stay inside
.tokencap/ in your git repository.
Get Started with v2.7.0
TokenCap v2.7.0 is available on npm today.
# Update globally
npm install -g tokencap
# Check repository build health
tokencap health
# Capture your first session summary
tokencap remember --summary "Reworked auth middleware to JWT" --files src/auth.ts --decision "Used RS256 with 15m expiration"
# Review staged captures
tokencap remember --list
tokencap remember --approve <session-id>
# Export the handoff note for your next AI session
tokencap handoff
Stop teaching every AI your codebase from scratch. Close the loop.
TokenCap is an open-source, local-first context layer for AI coding agents.
Website · [GitHub]
(https://tokencap.vansharora.app/docs)