> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leeroo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Repo Memory

> Evidence-backed understanding of repository structure

## Overview

RepoMemory is a structured representation of a repository's architecture, patterns, and conventions. It helps coding agents understand the codebase and make informed changes.

## Key Features

* **Evidence-backed claims**: All assertions link to specific file locations
* **Branch inheritance**: Child experiments inherit parent's memory
* **Bounded prompts**: Summary + TOC keeps context manageable
* **Section-based access**: Agents can read specific sections on demand

## Schema

```json theme={null}
{
  "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
  }
}
```

## Core Sections

| Section ID           | Title         | Content                         |
| -------------------- | ------------- | ------------------------------- |
| `core.architecture`  | Architecture  | System design, module structure |
| `core.entrypoints`   | Entrypoints   | How to run the application      |
| `core.where_to_edit` | Where to edit | Key files for modifications     |
| `core.invariants`    | Invariants    | Contracts and constraints       |
| `core.testing`       | Testing       | How to run tests                |
| `core.gotchas`       | Gotchas       | Common pitfalls                 |
| `core.dependencies`  | Dependencies  | Key dependencies                |

## Usage

### Ensure Memory Exists

```python theme={null}
from kapso.execution.memories.repo_memory import RepoMemoryManager

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

### Render for Prompts

```python theme={null}
# Get bounded summary + TOC
brief = RepoMemoryManager.render_summary_and_toc(doc, max_chars=3000)
print(brief)
```

Output:

```
# 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
```

### Get Specific Section

```python theme={null}
# Read a section
section_text = RepoMemoryManager.get_section(doc, "core.architecture")
print(section_text)
```

### Bootstrap from Existing Repo

```python theme={null}
from kapso.core.llm import LLMBackend

llm = LLMBackend()

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

### Update After Experiment

```python theme={null}
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,
    },
    max_retries=2,
)
```

`max_retries` counts repair attempts after the first response. Kapso selects
and reads repository files once, then asks the model to repair only malformed
JSON or an invalid outer schema. Provider, authentication, transport, and
configuration errors are not retried.

## Failure Policy

RepoMemory is optional enrichment; experiment code and evaluation results are
the primary artifacts. Search strategies therefore default to warning when a
baseline or per-experiment memory update fails:

```yaml theme={null}
search_strategy:
  type: generic
  params:
    repo_memory_failure_policy: warn  # warn | fail
    repo_memory_max_retries: 2
```

* `warn` logs the enrichment error, then still pushes the candidate branch and
  cleans up the coding agent session.
* `fail` still performs branch push and cleanup, then re-raises the original
  RepoMemory error.
* Invalid policy values and negative or non-integer retry counts fail during
  strategy/workspace setup.

Direct calls to `RepoMemoryManager.bootstrap_baseline_model()` and
`update_after_experiment()` always raise if structured-response repair is
exhausted. The `warn`/`fail` policy is applied by the search/session lifecycle.

## File Location

RepoMemory is stored at `.kapso/repo_memory.json` in each repository.

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

## Branch Inheritance

When experiments branch from a parent:

1. Child branch inherits parent's `.kapso/repo_memory.json`
2. After experiment runs, memory is updated with new understanding
3. Memory is committed to the branch
4. Future children of this branch inherit the updated memory

```mermaid theme={null}
flowchart TD
    M[main: baseline memory]
    E1[experiment_1: inherited + updated]
    E2[experiment_2: inherited from main]
    E3[experiment_3: inherited from E1]

    M --> E1
    M --> E2
    E1 --> E3
```

## Evidence Validation

Claims must have evidence that exists in the repository:

```python theme={null}
from kapso.execution.memories.repo_memory.builders import validate_evidence

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

## MCP Tools Access

For Claude Code agent, RepoMemory is accessible via MCP tools:

```python theme={null}
# Get summary and table of contents
get_repo_memory_summary()

# List available sections
list_repo_memory_sections()

# Get specific section content
get_repo_memory_section(section_id="core.architecture")
```

Available sections:

* `core.architecture` - System design and module structure
* `core.entrypoints` - How to run the application
* `core.where_to_edit` - Key files for modifications
* `core.invariants` - Contracts, constraints, and assumptions
* `core.testing` - How to run tests
* `core.gotchas` - Common pitfalls
* `core.dependencies` - Key dependencies

## Integration with Coding Agents

### Prompt Injection

Search strategies inject RepoMemory into prompts:

```python theme={null}
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}
    """
```

### Section Access Instructions

Agents are told how to access detailed sections via MCP tools:

```
For detailed section content (architecture, gotchas, invariants, etc.),
use the MCP tool: get_repo_memory_section(section_id="core.architecture")
Available sections: core.architecture, core.entrypoints, core.where_to_edit, core.invariants, core.testing, core.gotchas, core.dependencies
```

## Quality Metrics

```python theme={null}
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
}
```