Fixing Claude Code's Amnesia

Arpit — Mon, 01 Dec 2025 10:20:29 +0000

Picture this: You're deep in a refactor. Claude just helped you understand the token validation in auth.ts .

You're vibing. You feel productive.

Then you ask: "Cool, now how does this connect to cache_service.ts ?"

And Claude… re-reads auth.ts . From line 1 again! Like it's never seen it before.

You realize you're not having a conversation. You're giving tours to a very intelligent tourist with amnesia.

Every message is a fresh start. Every file read is from scratch. Every time you context-switch, Claude forgets what you were just talking about. It's brilliant at reasoning, terrible at remembering.

And here's the kicker: This isn't a bug. It's just how LLMs work. Stateless by design. Each API call is independent. No memory. No continuity. And No "yo, we looked at that file 5 minutes ago."

Enter: Super Claude Kit 🎭

This frustration led me to build a coding agent-Orpheus CLI, an experimental coding agent to understand how these tools work under the hood.

Super Claude Kit is what happened when I got annoyed enough to fix the amnesia problem myself.

It's a lightweight orchestration system that gives Claude Code:

Persistent memory across messages and sessions
Dependency intelligence for your entire codebase
Smart context management that doesn't waste tokens
Zero-config operation (it just works 🥷🏻)

Built entirely with bash hooks (thank you, Anthropic 🙏) and a couple of lightweight Go binaries, it turns Claude from a stateless assistant into a workspace-aware development partner.

Here's the best part: It's all local. No databases, no API calls, no cloud services.

Anthropic's Claude Code and that beautiful hook system

Let me give credit where it's due: Claude Code's hook system is genius. Anthropic could've built a closed system. Instead, they gave us lifecycle hooks.

Super Claude Kit is proof that Claude Code isn't just an AI assistant, it's a platform. The hooks let me inject context, track state, route intentions, and build memory without disturbing Claude Code's internals.

How it actually works (the fun part)

I ran the same task in vanilla Claude Code vs Claude Code with Super Claude Kit

**Task:** "Check for circular dependencies and identify dead code"
**Vanilla Claude Code (left):**
 - Spawned 2 Explore sub-agents
 - 60 tool uses scanning files
 - **55,400 tokens consumed**
 - **2 minutes 21 seconds**
 - Still processing when I stopped it
**Super Claude Kit (right):**
 - Used specialized tools: find-circular, find-dead-code
 - 2 direct tool calls
 - **<1,000 tokens**
 - **5 seconds**
 - Complete, accurate results
**That's 99% token reduction and 30x faster.**

This is the same query, same codebase, same computer, same model (Opus 4.5).

Zero redundant reads. Instant dependency analysis. Cross-message awareness.

It just… remembers. Like a teammate would.

Super Claude Kit works like a tiny orchestration system inside Claude Code.

The difference? Super Claude Kit guides Claude to use the right tools automatically.

Component Breakdown

Each layer responds to hooks in milliseconds. The whole system adds <100ms overhead. You don't even notice it running.

1. Persistent Memory: Because Forgetting Sucks
Every session gets a human-readable journal:

## Session: 2025–11–15 14:30 UTC
[pattern] Auth uses JWT with Redis-backed sessions
[architecture] Microservices talk via gRPC
[bug] Race condition in token refresh (auth.ts:142)
Files Accessed:
• src/auth/auth.ts (read, edit)
• src/database/redis.ts (read)

When you start a new session, if it's been less than 24 hours, this state auto-restores. You pick up exactly where you left off.

2. TOON Format: Because JSON is Bloated
While building this, I stumbled on TOON (Token-Oriented Object Notation), a format designed specifically for LLMs.
JSON (everyone's default): 95 tokens of mostly syntax noise

{
 "git": {"branch": "epic/labs", "head": "38f6f42e", "dirty": 22},
 "files": [{"path": "CLAUDE.md", "action": "read", "age": 120}]
}

TOON : 45 tokens (52% smaller!)

GIT{branch,head,dirty}:
 epic/labs,38f6f42e,22
FILES{path,action,age}:
 CLAUDE.md,read,120

That's not just clever, it's practical. Every token saved is more room for actual code context.

The Context Capsule holds everything Claude needs:

Git status (branch, dirty files, HEAD commit)
Recently accessed files
Current tasks
Discoveries
Session metadata

A hook updates this before each prompt, but only if something actually changed (hash-based diffing). That optimization alone cuts updates by 40–50%.

3. Dependency Graph: Know Your Codebase

On session start, a Go binary (using tree-sitter for parsing) builds a complete dependency graph.
Current languages supported: TypeScript, JavaScript, Python, Go

What it does:

Scans your entire codebase
Extracts imports/exports from every file
Builds a directed graph of dependencies
Detects and finds all strongly connected components/references, not just individual cycles (using Tarjan's algorithm)
Identifies dead code (files nobody imports)
Saves for future reference in the session

Now Claude can answer:

Who imports this file?
What breaks if I change this?
Are there circular dependencies?
What files are unused?

Before refactoring, claude knows what we're about to break. No surprises.

*Why Tarjan's algorithm? *
Because it's what npm, cargo, and every serious dependency analyzer uses. It finds all circular dependencies in a single O(V + E) pass.
Simple DFS would need multiple passes. Floyd-Warshall would be O(V³).
Tarjan's is just… the right tool.

4. Progressive Reader: Semantic Chunking for Large Files
Large files (>50KB) kill context windows. Traditional line-based reading breaks functions mid-definition.

Progressive Reader uses tree-sitter to chunk files at semantic boundaries:

// auth.service.ts (300 lines)
// Chunk 0: Imports + AuthService class (lines 1–85)
import { User } from './user';
export class AuthService {
 // Full class definition
}
// Chunk 1: TokenService class (lines 86–150)
export class TokenService {
 // Complete class
}
// Chunk 2: SessionService (lines 151–220)
export class SessionService {
 // Complete class
}

You read chunk 0. That's enough? Done. Need more? Read chunk 1. It's like pagination, but smart.

Benefits:

Read only what you need (60–80% context savings)
Preserve semantic coherence (no broken functions)
Continuation tokens for stateful reading
Tree-sitter guarantees correct boundaries

5. The "Boss Layer": Making Claude Use Its Brain
Even with memory and context, Claude sometimes ignored the capsule.
So I added forcing functions:

Smart Refresh (Don't Update If Nothing Changed)

current_hash=$(compute_state_hash)
if [[ "$current_hash" == "$last_hash" ]] && [[ $minutes < 5 ]]; then
 exit 0 # Skip - nothing changed
fi

Result: 60–70% fewer capsule updates.

Intent Router (Delegate to Specialists)
Hook analyzes prompts and routes to specialized sub-agents:

"Explore database architecture" → database-navigator
"Debug this MCP integration" → agent-developer
"Create a GitHub issue" → github-issue-tracker

Claude stops trying to do everything and delegates intelligently.

Decision Matrix (SKILL.md)

A rule table that enforces best practices:
BEFORE refactoring → Run impact-analysis
BEFORE deleting → Run query-deps
WHEN imports fail → Run find-circular

Think of it as a "boss" that reminds Claude to use its tools.

| Metric                           | Before   | After  | Improvement 
|----------------------------------|----------|--------|-------------
| **Tokens per context update**    | ~8,500   | ~4,900 | **42% reduction**
| **Capsule refreshes per session**| ~12      | ~4     | **67% fewer** 
| **Files re-read unnecessarily**  | ~15      | ~5     | **67% reduction** 
| **Context loss between sessions**| 100%     | 0%     | **Total persistence**
| **Dependency analysis time**     | 5-10 min | <5 sec | **~100x faster** 
| **Disk footprint**               | N/A      | 10-30KB| Negligible 
| **Hook overhead**                | N/A      | <50 ms | Imperceptible

A Complete Session (How It All Connects)

1. $ claude
2. SessionStart hook fires
 ├─ Check for previous session (<24h ago)
 ├─ Restore state from capsule_persist.json
 ├─ Build dependency graph (1,247 files, 4.2s)
 └─ Save to .claude/dep-graph.toon
3. Claude receives context injection:
   "RESTORING FROM PREVIOUS SESSION
   Last: 28m ago | Task: Auth refactor → Redis"
4. You: "Continue the refactor"
5. UserPromptSubmit hook fires
 ├─ Hash current state
 ├─ Compare to last refresh
 ├─ No changes → Skip update (saves ~4,500 tokens)
 └─ Proceed
6. Claude: "From the capsule, I see we're migrating auth.ts
   to Redis. Last session we updated token validation.
   Let me now update the login endpoint…"
7. You: "What breaks if I change token format?"
8. Claude runs: impact-analysis.sh auth.ts
   Output: "15 dependents. HIGH RISK."
9. You: "Create a GitHub issue for this"
10. Intent router: → github-issue-tracker sub-agent
    Issue created with full context from capsule
11. You: exit
12. SessionEnd hook fires
 ├─ Save state → capsule_persist.json
 ├─ Append discoveries → exploration journal
 └─ Set 24h expiry

Next session: Everything restores automatically. You pick up where you left off.

AI coding assistants are incredible. But they're tourists in your codebase. They parachute in, help with a problem, then forget everything.

Super Claude Kit turns tourists into residents.

It's not about changing the model. It's about giving the model a home, a persistent workspace where context lives, dependencies are mapped, and sessions connect.

Claude stops forgetting. You stop repeating yourself. Development becomes a conversation, not isolated transactions.

If you've ever been frustrated explaining the same thing to Claude for the third time in an hour, this is for you.

Try It (It's Open Source)

Super Claude Kit works with Claude Code out of the box.

arpitnath / claude-capsule-kit

A toolkit that makes Claude Code better at engineering — session memory, dependency analysis, large file navigation, 18 specialist agents, and crew teams for parallel multi-branch work.

A toolkit that makes Claude Code better at engineering.

Session memory. Dependency analysis. Large file navigation. 18 specialist agents.
Crew teams for parallel multi-branch work. All automatic, zero configuration

Install

npm install -g claude-capsule-kit
cck setup

Restart Claude Code. Everything activates automatically via hooks.

Why CCK

Claude Code is powerful out of the box. But on real codebases, you run into limits:

Session isolation — Claude starts fresh every time. Previous context, discoveries, and decisions are lost.
No dependency awareness — Claude doesn't know your import graph. It can't tell you what breaks when you change a file.
Large file blindness — Files over 50KB get truncated. Claude can't navigate framework internals or generated code.
Single-threaded work — One branch, one task at a time. No way to parallelize across features.
Agent amnesia — Sub-agents start with zero context. Findings from one agent don't flow to others.

CCK fills these…

View on GitHub

Anthropic Claude Code and that beautiful hook system

TOON Format : Token-efficient notation that just works

Tree-sitter : AST parsing that makes semantic chunking possible

2 weeks of Hacktoberfest as a first-time maintainer and contributor

Arpit — Thu, 12 Sep 2024 14:52:24 +0000

While people enjoy the oncoming autumn, developers are psyched for a specific reason in October. It’s that time of the year again (Hacktober)! Hacktoberfest 2021 marks yet another year of celebrating open-source software. Celebrating open-source software for the entire month of October encourages people with all skill-set levels to try their hands on real-world software, contribute to the public repositories between October 1–31 and win some cool swaggers or goodies.

To participate in Hacktoberfest, you need to sign up for the event on the official website and can begin to create pull requests to any project that has a “Hacktoberfest” label on its issue tracker. You can also find projects by browsing through the Hacktoberfest site. Like ToolJet (yes, that’s us!, with 3.7k stars 😎), every valid Pull Request is eligible for ToolJet swag ( stickers, t-shirts, and more ), and selected top contributors will receive special surprise prizes.

I had never contributed to any open-source software before joining ToolJet. This year I found myself being a part of a team and maintaining specific aspects of the project, listing out Issues and trying to help other fellow developers with their queries. At some point, we could not even keep pace with the steep number of contributors picking up Issues and being bombarded with really overwhelming notifications, which was awed, happy, shocked (all at once). To put things into perspective, we had over 50 Pull Requests from 40+ new contributors; out of this, a good number of them were first-timers.

My preconceived notion that every contribution needed to be sizeable was shattered, seeing the sheer amount of responses. I turned into a contributor myself and contributed to a few projects (very few), some without the “Hacktoberfest” label. I finally started my stint in open sourcing!
No matter how big or small the contributions, we welcome you to collaborate and contribute, starting with fixing a bug, improving the documentation, or even contributing a new feature.

To read more about how to contribute to ToolJet: Hacktober Blog andGitHub. In conclusion, you can make a difference even if you are proofreading documentation. Get Hacking!

Forem: Arpit