codebase-learn

genomewalker's avatarfrom genomewalker

Learn and remember codebase structure to minimize future token usage. Records architectural knowledge, file purposes, and patterns as a connected graph.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️2downloads
[Memory and Context Management]

When & Why to Use This Skill

Codebase-learn is an advanced context-optimization skill that enables Claude to master large-scale codebases while minimizing token consumption. By combining tree-sitter AST extraction with high-level SSL (Semantic Schema Language) patterns, it builds a persistent, hierarchical knowledge graph of architectural relationships. This approach reduces context overhead by up to 90%, allowing for more efficient, cost-effective, and accurate long-term development sessions.

Use Cases

  • Rapid Onboarding: Quickly map and understand the architecture, file purposes, and design patterns of a massive, unfamiliar codebase.
  • Token-Efficient Development: Reduce LLM costs and prevent context window overflow by injecting only relevant hierarchical state (Project Essence, Module State, and Patterns) instead of full source files.
  • Architectural Impact Analysis: Query the connected graph to understand how changes in one module affect distant components through established triplets and relationships.
  • Incremental Knowledge Maintenance: Use provenance and staleness tracking to keep the agent's understanding of the codebase synchronized with real-time code changes without re-indexing the entire project.
namecodebase-learn
descriptionLearn codebase structure with tree-sitter + SSL patterns
executiontask
modelinherit
aliases[learn-codebase, map-code]

Codebase Learn

Two-phase codebase understanding:

  1. C++ tool (learn_codebase): AST extraction, provenance, hierarchical state
  2. Claude: High-level SSL patterns for architecture and relationships
[codebase-learn] tool + understanding

phase1: learn_codebase→tree-sitter→symbols+triplets+hierarchy
  handles: parsing, storage, provenance, staleness tracking
  output: Symbol nodes, file→contains→symbol triplets, ModuleState

phase2: Claude→architecture→SSL patterns
  handles: why, how, relationships between components
  output: Wisdom nodes with [LEARN] markers

Supported Languages

Tree-sitter parsers available:

  • C/C++: .c, .h, .cpp, .hpp, .cc, .cxx, .hxx
  • Python: .py, .pyw
  • JavaScript/TypeScript: .js, .jsx, .mjs, .ts, .tsx
  • Go: .go
  • Rust: .rs
  • Java: .java
  • Ruby: .rb
  • C#: .cs

Usage

Step 1: Run learn_codebase

chitta learn_codebase --path /path/to/project --project myproject

This single command:

  • Finds all supported source files (excludes build dirs, node_modules, etc.)
  • Extracts symbols with tree-sitter AST
  • Creates Symbol nodes with provenance (source_path, hash)
  • Creates triplets (file contains symbol, scope contains method)
  • Bootstraps hierarchical state (ProjectEssence + ModuleState)
  • Registers files for staleness tracking

Output:

Learned codebase: myproject

Files: 47 analyzed (of 52 found)
Symbols: 1234 stored
Triplets: 2567 created
Modules: 15 bootstrapped

Hierarchical State Modules:
  Mind @include/chitta/mind.hpp
  Storage @include/chitta/storage.hpp
  ...

Step 2: Add SSL Patterns (Claude)

After learn_codebase runs, I add architectural understanding:

[LEARN] [myproject] Mind→orchestrator→recall/observe/grow API
[ε] Central class managing tiered storage + embeddings + graph. @mind.hpp:52
[TRIPLET] Mind uses TieredStorage
[TRIPLET] Mind uses HierarchicalState
[TRIPLET] Mind provides recall

[LEARN] [myproject] HierarchicalState→token compression→3-level injection
[ε] L0=ProjectEssence(50t) + L1=ModuleState(20t) + L2=PatternState(10t)
[TRIPLET] HierarchicalState contains ProjectEssence
[TRIPLET] injection_protocol saves tokens

SSL captures what AST can't:

  • Why a component exists
  • How components relate architecturally
  • Patterns and design decisions

Incremental Updates

When code changes:

# Check what's stale
chitta staleness_stats

# Re-learn (only re-analyzes changed files internally)
chitta learn_codebase --path /path/to/project

Provenance tracking means:

  • Each Symbol knows its source file and hash
  • File changes mark symbols as maybe_stale
  • Re-analysis updates only what changed

Token Savings

Traditional: inject full code context (~thousands of tokens)

Hierarchical approach:

  • Level 0: ~50 tokens (project essence, always injected)
  • Level 1: ~100 tokens (relevant modules)
  • Level 2: ~50 tokens (active patterns)
  • Total: ~200 tokens vs ~2000+

View current state:

chitta hierarchical_state

Example: Learning cc-soul

# Step 1: C++ tool does the heavy lifting
chitta learn_codebase --path /path/to/cc-soul/chitta --project cc-soul

# Step 2: I add architectural SSL
[LEARN] [cc-soul] chitta→semantic memory substrate→tiered storage + SSL + triplets
[ε] C++ daemon: hot/warm/cold storage, JSON-RPC socket, Hebbian learning.
[TRIPLET] chitta contains Mind
[TRIPLET] Mind orchestrates recall
[TRIPLET] Mind orchestrates observe

[LEARN] [cc-soul] provenance→staleness tracking→source_path+hash→Fresh|MaybeStale|Stale
[ε] Two-phase: immediate MaybeStale marking, background verification.
[TRIPLET] Node has provenance
[TRIPLET] provenance tracks staleness

Benefits

After running:

  • recall("Mind architecture") → finds Symbol nodes AND architectural SSL
  • hierarchical_state → token-efficient context ready for injection
  • staleness_stats → know when re-indexing needed
  • query --subject Mind → find all Mind relationships

The soul knows both structure (symbols) and meaning (SSL).