# Research Stack Receipt: Persistent Codebase Memory (2026-05-13)

## Agent: Hermes (Nous Research self-adaptive agent)
## Task: Persistent multi-domain codebase memory without Python

---

## Summary

Built a FAMM-based persistent codebase memory system that lets Hermes remember
the full project structure between sessions, without retraining or rescanning.

---

## Architecture (Rust crate)

```
4-Infrastructure/shim/codebase-memory/
  Cargo.toml            -- Rust crate manifest (serde, sha2, walkdir)
  src/lib.rs            -- Public exports
  src/types.rs          -- Q16_16, CodeDomain (7), CodeCell, DomainBank,
                           DomainScarField, DualMapMemory, 6 tests
  src/adapter.rs        -- CodebaseMemoryAdapter with observe/commit/query_all
  src/main.rs           -- Binary: load_for_hermes(project_root, persist_path)
  hermes_integration_manifest.json  -- Agent contract
```

## Key Types

- **Q16_16**: Fixed-point arithmetic matching Lean Q16_16
- **CodeDomain**: 7 domains (0-Core through 6-Docs)
- **CodeCell**: Artifact path, type, data, delay (staleness), delay_mass (uncertainty), version_hash
- **DomainBank**: 1000-cell FAMM bank with thermal budget (5000), current stress, heatsink_halt
- **DualMapMemory**: ahead (speculative) + behind (committed) + per-domain scar differentials

## Operations

1. **observe(domain, path, type, data, delay, mass)**
   - Finds or allocates cell in ahead map
   - Updates version_hash from SHA-256
   - If content changed: adds scar to ahead_scar
   - Emits MemoryAccessReceipt

2. **commit_if_admissible(domain)**
   - Computes |ahead_total - behind_total|
   - If |Delta| <= epsilon: copies ahead -> behind, admits
   - Else: holds (receipt says "blocked")
   - Emits MemoryAccessReceipt

3. **advance_epoch()**
   - Commits all domains in one epoch cycle

4. **query_all(pattern)**
   - Searches all domains for artifact path substring
   - Returns HashMap<domain, Vec<CodeCell>>

5. **load_for_hermes(root, .hermes/codebase_memory.json)**
   - Scans all 7 domain directories
   - Observes every file with artifact_type from extension
   - Saves to JSON, then loads back via serde
   - This is the Hermes startup path

## Receipt Verification

- cargo check: PASS
- cargo test (6 tests):
  - test_q16_16_basic: PASS
  - test_code_domain_all: PASS
  - test_artifact_type_from_ext: PASS
  - test_domain_bank: PASS
  - test_memory_state: PASS
  - test_dual_map_commit: PASS

## Lean Modules (Quarantined)

Three Lean modules were written as formal spec but quarantined from `lake build`
because they have field notation issues with `KnowledgeCell` / `CodeCell`
shadowing `FAMMCell`. They can be re-enabled when the naming collision is resolved.

- `Semantics/CodebaseMemory.lean` -- types + thermal management + pruning
- `Semantics/CodebaseFSDU.lean` -- dual-map scar differentials
- `Semantics/CodebaseReceipt.lean` -- MemoryAccessReceipt + observer/provider pairs

## Quarantine Log

```log
2026-05-13 02:30 -- quarantined CodebaseMemory.lean, CodebaseFSDU.lean, CodebaseReceipt.lean
2026-05-13 02:30 -- deleted codebase_memory_adapter.py (Python disallowed per AGENTS.md)
2026-05-13 02:35 -- built Rust codebase-memory crate
```

## Promotion Gate

- Status: CANDIDATE
- Next: Observer/Provider receipt audit to advance to REVIEWED

## Answer SHA-256

```
echo -n "codebase_memory_manifest_2026_05_13" | sha256sum
# (runtime-computed)
```

-- Research Stack Team