# 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 155 files at commit `b356dfb800de`. Read this first, then `readmenator-wiki/index.md`, then `readmenator . ask ""` for anything specific. ## 1. Purpose and domain - What it is: A token-free, offline, production-grade polyglot codebase knowledge graph & architectural analyzer. (`README.md:7`) - Domain vocabulary (term, files): `readmenator` (104), `file` (91), `graph` (73), `node` (67), `files` (66), `symbols` (61), `project` (59), `edges` (59), `imports` (56), `nodes` (55), `build` (54), `config` (54), `symbol` (53), `all` (53), `one` (52) - Subsystem `readmenator: _video`: 35 files, core `readmenator/_video.py`: Cinematic codebase overview video, general purpose. - Subsystem `readmenator/parsers`: 35 files, core `readmenator/_models.py`: Data model types for the readmenator knowledge graph. - Subsystem `readmenator: _agent_output`: 19 files, core `readmenator/_agent_output.py`: Agent-friendly output generator for ReadMenator. - Subsystem `readmenator: _graphrag`: 18 files, core `readmenator/_graphrag.py`: Zero-token GraphRAG index and retrieval for AI agents. - Subsystem `readmenator: _pipeline`: 17 files, core `readmenator/_pipeline.py`: AnalyzerFactory (lazy component construction) and DeepAnalysisRunner. - Subsystem `readmenator: _diagrams`: 15 files, core `readmenator/_diagrams.py`: Self-contained interactive system maps for the knowledge graph. - Subsystem `readmenator: _flowcharts`: 12 files, core `readmenator/_flowcharts.py`: Architecture and execution-flow Mermaid diagrams from static structure. - Business rules that the code cannot show live in section 7: record them there. ## 2. Workflow Detected commands: - `python -m pytest -q` (pyproject.toml) - `readmenator --help` (pyproject.toml [project.scripts]) - `readmenator-mcp --help` (pyproject.toml [project.scripts]) - `CI workflow main.yml` (.github/workflows/main.yml) - `CI workflow publish.yml` (.github/workflows/publish.yml) - `CI workflow static.yml` (.github/workflows/static.yml) - `CI workflow validate-rules.yml` (.github/workflows/validate-rules.yml) 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 ""` (local = entities + sources, `--global` = community reports). 3. Before editing a file: `grep -n '' 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 "" --kind decision`. ## 3. Rules and constraints Declared: - Config is the single source of truth for all constants (`CLAUDE.md:848`) - Symbol creation logic is not duplicated across parsers (`CLAUDE.md:849`) - Docstring extraction lives once in LanguageParser base class (`CLAUDE.md:850`) - File-level doc extraction lives once in PolyglotScanner (`CLAUDE.md:851`) - All analysis thresholds in Config, never hardcoded (`CLAUDE.md:852`) - Single Responsibility: each module has one job (`CLAUDE.md:855`) - Open/Closed: add parsers/analyzers without modifying existing code (`CLAUDE.md:856`) - Liskov Substitution: all parsers inherit from LanguageParser (`CLAUDE.md:857`) - Interface Segregation: each contract exposes minimal surface (`CLAUDE.md:858`) - Dependency Inversion: app depends on abstractions (Config, Scanner) (`CLAUDE.md:859`) - No absolute paths in source code (`CLAUDE.md:862`) - No network calls from the core scanner (`CLAUDE.md:863`) - Symlinks rejected (`CLAUDE.md:864`) - File size limits enforced (`CLAUDE.md:865`) - Directory depth limits enforced (`CLAUDE.md:866`) - All parsing exceptions caught (`CLAUDE.md:867`) - No external API calls in any analysis or export module (`CLAUDE.md:868`) - Pattern-based security analyzer with 18 language rule sets (`CLAUDE.md:869`) - Privacy mode strips source snippets from output (`CLAUDE.md:870`) - Fix any security issues found (symlinks, path traversal, size limits) (`CLAUDE.md:899`) - Remove hardcoded values and move to Config if they are tuneable (`CLAUDE.md:900`) - Update tests to cover new behaviors (`CLAUDE.md:901`) - Keep the "Classs" pluralization fix intact (`CLAUDE.md:902`) - Do not add absolute paths (`CLAUDE.md:903`) - Do not add external dependencies to the core scanner (`CLAUDE.md:904`) - Maintain backward compatibility of the CLI interface (`CLAUDE.md:905`) - Update this CLAUDE.md and README.md for any contract changes (`CLAUDE.md:906`) - Fix inline imports (move to top of file) (`CLAUDE.md:907`) - Add type annotations to all function signatures (`CLAUDE.md:908`) - Maintain strict separation of concerns. (`.cursorrules:5`) - UI/presentation components must not contain business logic or database queries. (`.cursorrules:6`) - Business logic must not depend on presentation or infrastructure details. (`.cursorrules:7`) - Data access must be isolated behind repository interfaces. (`.cursorrules:8`) - Keep files under 300 lines. Split larger files into cohesive modules. (`.cursorrules:9`) - Never add absolute paths to source code. (`.cursorrules:10`) - Never hardcode configuration values. Use the Config class. (`.cursorrules:11`) - All new modules must have corresponding test files. (`.cursorrules:12`) - Use type annotations on all function signatures. (`.cursorrules:13`) - Follow the existing code style and naming conventions. (`.cursorrules:14`) Measured baseline: - Security findings at medium or above: 0 (see `readmenator-agent/SECURITY.md`); do not add new ones. - Dependency cycles: 0; layer violations: 11 (see `readmenator-agent/GOTCHAS.md`). ## 4. Style norms Declared: - All progress/report messages use `logging.getLogger(__name__)` (never `print()`) (`CLAUDE.md:873`) - User-facing output (query results, summaries) uses `print()` to stdout (`CLAUDE.md:874`) - Logging format configured in `__main__.py` via `logging.basicConfig` (`CLAUDE.md:875`) - Each module gets its own logger via `logger = logging.getLogger(__name__)` (`CLAUDE.md:876`) Measured baseline: - py: 153 files, 2993 symbols; docstrings on 55% of symbols; functions snake_case (96%); types PascalCase (100%); median file 204 lines, max 4166. - js: 1 files, 35 symbols; docstrings on 100% of symbols; functions snake_case (80%); types PascalCase (40%); median file 5 lines, max 5. - sh: 1 files, 1 symbols; docstrings on 100% of symbols; functions snake_case (100%); median file 42 lines, max 42. - Tests: 55 files under tests; follow the existing naming (e.g. `test_agent_friendliness.py`). ## 5. Minimum deliverables Declared: - Tests named as `test__` (BDD style) (`CLAUDE.md:879`) - Each module has its own test class (`CLAUDE.md:880`) - Security behaviors tested explicitly (`CLAUDE.md:881`) - Edge cases tested (empty files, syntax errors, symlinks) (`CLAUDE.md:882`) - Integration tests validate end-to-end pipeline (`CLAUDE.md:883`) - "Classs" regression test prevents re-introduction (`CLAUDE.md:884`) - All new modules have complete contract test suites (`CLAUDE.md:885`) - Mutation check after SDD+TDD+BDD: introduce one-line mutants (validation bypass, escaping bypass, ordering change); a killed mutant fails at least one test, a surviving mutant requires a stronger test before refactor (`CLAUDE.md:886`) - Property-based parser tests skip cleanly when hypothesis is not installed (inert strategy placeholders, identity decorators) (`CLAUDE.md:887`) - English only, no emojis, no prose comments, docstrings on every public and private function (`CLAUDE.md:890`) - DRY and SOLID, one self-contained file per contract, production code with no placeholders or simplifications (`CLAUDE.md:891`) - No hardcoded tuneables or magic numbers: every setting lives in Config (`CLAUDE.md:892`) - No absolute paths, no network calls from analysis or export modules, all untrusted text escaped at the boundary (`CLAUDE.md:893`) - Boy scout: any technical debt or security flaw found during the change is fixed without losing functionality (`CLAUDE.md:894`) Measured baseline: - Tests pass: `python -m pytest -q`. - Docstring coverage stays at or above 55%. - 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): `readmenator/_models.py`, `readmenator/_config.py`, `readmenator/_pipeline.py`, `readmenator/_app.py`, `readmenator/parsers/__init__.py` - Hotspots (complex and central): `readmenator/_vendor/force-graph.min.js`, `readmenator/_diagrams.py`, `readmenator/_app.py`, `readmenator/_video.py`, `tests/test_parsers.py` - Full blast radius: `readmenator-agent/GOTCHAS.md`; findings: `readmenator-agent/SECURITY.md`. ## 7. Session log (preserved across rebuilds) Append with `readmenator . remember "" --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.