codebase-learn

# 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

```ssl
[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

```bash
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]