# Project Memory

> Cross-session context for agents. Sections 1-6 are regenerated from the source tree with zero LLM tokens: declared rules are quoted verbatim with `file:line`, measured baselines come from the scan. Section 7 is written by agents and humans and is preserved across rebuilds.

Generated from 44 files at commit `4d3ec5e49007`. Read this first, then `readmenator-wiki/index.md`, then `readmenator . ask "<question>"` for anything specific.

## 1. Purpose and domain

- What it is: A 122M parameter complex-valued autoregressive language model trained on (`README.md:3`)
- Domain vocabulary (term, files): `topo` (27), `model` (25), `eval` (25), `run` (22), `gpt3` (20), `topogpt3` (20), `load` (19), `build` (18), `prompt` (16), `checkpoint` (15), `config` (15), `one` (15), `all` (14), `new` (14), `runs` (14)
- Subsystem `topogpt3: model`: 12 files, core `topogpt3/model.py`: TopoGPT2: Quaternion-Enhanced Topological Transformer Language Model  Author: Gris Iscomeback...
- Subsystem `eval: harness`: 7 files, core `eval/harness.py`: Harness for evaluating TopoGPT3 on HumanEval (164 problems).
- Subsystem `eval: governor`: 6 files, core `eval/governor.py`: Streaming + governance for autoregressive generation.
- Subsystem `topogpt3: inference_hrm`: 5 files, core `topogpt3/inference_hrm.py`: TopoGPT3.1: Hierarchical Recursive Reasoning Inference Engine.
- Subsystem `topogpt3: jlens`: 4 files, core `topogpt3/jlens.py`: TopoGPT3JLensFitConfig: Centralized configuration for Jacobian lens fitting.
- Business rules that the code cannot show live in section 7: record them there.

## 2. Workflow

Detected commands:
- `python -m pytest -q` (pyproject.toml)
- `topogpt3-train --help` (pyproject.toml [project.scripts])
- `topogpt3-infer --help` (pyproject.toml [project.scripts])
- `topogpt3-infer-hrm --help` (pyproject.toml [project.scripts])
- `topogpt3-jlens --help` (pyproject.toml [project.scripts])
- `topogpt3-api --help` (pyproject.toml [project.scripts])
- `make help` (Makefile)
- `make install-min` (Makefile)
- `make install` (Makefile)
- `make install-api` (Makefile)
- `make test` (Makefile)
- `make test-jlens` (Makefile)

Session protocol:
1. Start: read this file, then `readmenator . fresh` (exit 1 means run `readmenator . --rebuild`).
2. Orient: `readmenator-wiki/index.md`; for a question use `readmenator . ask "<question>"` (local = entities + sources, `--global` = community reports).
3. Before editing a file: `grep -n '<file>' readmenator-agent/GOTCHAS.md readmenator-agent/SECURITY.md`.
4. After the change: run the tests above, then `readmenator . --rebuild` so the maps, wiki, and this file stay true.
5. End: record decisions, business rules, and gotchas with `readmenator . remember "<note>" --kind decision`.

## 3. Rules and constraints

Declared:
- none declared in instruction files (add them to AGENTS.md or record them in section 7)

Measured baseline:
- Security findings at medium or above: 0 (see `readmenator-agent/SECURITY.md`); do not add new ones.
- Dependency cycles: 0; layer violations: 0 (see `readmenator-agent/GOTCHAS.md`).

## 4. Style norms

Declared:
- none declared in instruction files (add them to AGENTS.md or record them in section 7)

Measured baseline:
- py: 39 files, 813 symbols; docstrings on 52% of symbols; functions snake_case (100%); types PascalCase (97%); median file 224 lines, max 3824.
- sh: 5 files, 11 symbols; docstrings on 0% of symbols; functions snake_case (100%); median file 82 lines, max 165.
- Tests: 2 files under tests; follow the existing naming (e.g. `test_jlens.py`).

## 5. Minimum deliverables

Declared:
- none declared in instruction files (add them to AGENTS.md or record them in section 7)

Measured baseline:
- Tests pass: `python -m pytest -q`.
- Docstring coverage stays at or above 51%.
- No new security findings at medium or above (current: 0).
- No new dependency cycles (current: 0).
- Files stay under 300 lines where possible (`readmenator . lint`).
- Docs refreshed: `readmenator . --rebuild`, and decisions recorded in section 7.

## 6. Risks to respect

- God nodes (changes ripple widely): `topogpt3/model.py`, `topogpt3/__init__.py`, `topogpt3/train.py`, `topogpt3/lens_model.py`, `topogpt3/inference_hrm.py`
- Hotspots (complex and central): `topogpt3/model.py`, `topogpt3/train.py`, `topogpt3/api_server.py`, `eval/harness.py`, `synthetic_dataset.py`
- Full blast radius: `readmenator-agent/GOTCHAS.md`; findings: `readmenator-agent/SECURITY.md`.

## 7. Session log (preserved across rebuilds)

Append with `readmenator . remember "<note>" --kind <kind>` (kinds: business, decision, rule, workflow, style, deliverable, gotcha, todo, note) or the MCP tool `readmenator.remember`. Record business rules, decisions and their reasons, workflow changes, and anything the next session must not rediscover.

<!-- readmenator:memory:notes:begin -->
<!-- readmenator:memory:notes:end -->