Repo Memory

{
  "schema_version": 2,
  "generated_at": "2025-01-15T10:30:00Z",
  "repo_map": { ... },
  "repo_model": { ... },
  "book": {
    "summary": "One-paragraph description",
    "toc": [
      {"id": "core.architecture", "title": "Architecture", "one_liner": "..."},
      {"id": "core.entrypoints", "title": "Entrypoints", "one_liner": "..."},
      ...
    ],
    "sections": {
      "core.architecture": {
        "title": "Architecture",
        "one_liner": "System design and module structure",
        "claims": [
          {
            "kind": "architecture",
            "statement": "Uses factory pattern for component creation",
            "evidence": [{"path": "src/factory.py", "quote": "class Factory:"}]
          }
        ]
      },
      ...
    }
  },
  "experiments": [ ... ],
  "quality": {
    "evidence_ok": true,
    "section_count": 7,
    "claim_count": 15
  }
}

from src.repo_memory import RepoMemoryManager

# Create or load memory
doc = RepoMemoryManager.ensure_exists_in_worktree("/path/to/repo")

# Get bounded summary + TOC
brief = RepoMemoryManager.render_summary_and_toc(doc, max_chars=3000)
print(brief)

# Repo Memory (book)
Schema: v2
GeneratedAt: 2025-01-15T10:30:00Z

## Summary
A framework for automated code generation with knowledge-grounded experimentation.

## Table of Contents (section IDs)
- [core.architecture] Architecture: System design and module structure
- [core.entrypoints] Entrypoints: How to run the application
- [core.where_to_edit] Where to edit: Key files for modifications
...

## How to read details
- Open `.kapso/repo_memory.json`
- Find `book.sections[section_id]` from the TOC above

# Read a section
section_text = RepoMemoryManager.get_section(doc, "core.architecture")
print(section_text)

from src.core.llm import LLMBackend

llm = LLMBackend()

# Build evidence-backed model via LLM
RepoMemoryManager.bootstrap_baseline_model(
    repo_root="/path/to/repo",
    llm=llm,
    seed_repo_path="/original/repo",
)

RepoMemoryManager.update_after_experiment(
    repo_root="/path/to/repo",
    llm=llm,
    branch_name="experiment_1",
    parent_branch_name="main",
    base_commit_sha="abc123",
    solution_spec="Implement feature X",
    run_result={
        "score": 0.85,
        "run_had_error": False,
    },
)

my_project/
├── .kapso/
│   └── repo_memory.json
├── src/
└── ...

from src.repo_memory.builders import validate_evidence

result = validate_evidence(repo_root, model)
if not result.ok:
    print(f"Missing evidence: {result.missing}")

# List sections
python tools/repo_memory_cli.py list-sections

# Get specific section
python tools/repo_memory_cli.py get-section core.architecture

def implement_solution(self, solution, context, session):
    repo_memory_doc = RepoMemoryManager.ensure_exists_in_worktree(session.session_folder)
    repo_memory_brief = RepoMemoryManager.render_summary_and_toc(repo_memory_doc)

    prompt = f"""
    # Repo Memory (Summary + TOC)
    {repo_memory_brief}

    # Problem
    {context.problem}

    # Solution
    {solution}
    """

For detailed section content (architecture, gotchas, invariants, etc.),
use the CLI: `python3 tools/repo_memory_cli.py get-section <section_id>`
Example: `python3 tools/repo_memory_cli.py get-section core.architecture`

doc["quality"] = {
    "evidence_ok": True,       # All claims have valid evidence
    "missing_evidence": [],    # List of missing evidence
    "section_count": 7,        # Number of sections
    "claim_count": 15,         # Total claims across sections
}