.codexrules

# CodeRecall Coding Guidelines & AI Behavior Rules

As an AI engineering assistant working on CodeRecall, follow these rules:

1. **Language Requirement**
   - All code, comments, docstrings, variable names, and commit messages MUST be in English.
   - Python 3.10+ is the primary language for the MVP.

2. **Typing & Documentation**
   - Every public function and class MUST have strict type hints.
   - Every module, class, and complex function MUST include standard Python docstrings.

3. **Architecture & Modularity**
   - Keep parser, storage, retrieval, revision memory, verification, GitHub ingest, MCP, and UI logic decoupled.
   - CodeRecall is a memory and context engine, not a coding agent.
   - Main coding agents such as Claude Code, Codex, Cursor, Continue, and Aider should remain responsible for editing, debugging, and testing.

4. **Lightweight Defaults**
   - Do not require LLM API calls for indexing.
   - Do not require embeddings for the core loop.
   - Do not require a hosted service.
   - Prefer SQLite and FTS5 before adding heavier storage systems.

5. **Revision Memory Safety**
   - Never overwrite an original external snippet with an adapted version.
   - Store fixes as revision branches with source, error, patch, explanation, and verification evidence.
   - Treat unverified revisions as suggestions, not trusted fixes.

6. **Performance & Memory**
   - Prioritize performance when walking directories or parsing files.
   - Skip generated, dependency, cache, build, and virtual environment directories by default.
   - Use hashes and incremental indexing where appropriate.

7. **Defensive Programming & Logging**
   - File system and network operations must handle permission, lock, timeout, and rate-limit errors.
   - A single unreadable file or failed GitHub request should not crash the whole indexing run.
   - Do not use `print()` for debugging. Use structured logging with levels such as INFO, DEBUG, WARNING, and ERROR.