# Repository Guidelines

## Project Structure & Module Organization

- `src/ormah/`: Python package (backend + core engine)
  - `api/` FastAPI routes and middleware
  - `engine/` MemoryEngine, whisper/context building
  - `index/` SQLite schema + FTS/vector indexing
  - `store/` Markdown/YAML-frontmatter storage + watchers
  - `background/` APScheduler jobs and LLM maintenance helpers
  - `embeddings/` hybrid search + reranking
  - `adapters/` CLI/MCP/LLM provider adapters
- `ui/`: React + TypeScript (Vite). Production build outputs to `src/ormah/ui_dist/` and is served by the backend.
- `tests/`: pytest suite; `tests/smoke/` Docker smoke test.
- `eval/`: evaluation tooling (packaged alongside the main wheel).

## Build, Test, and Development Commands

- `make install`: install Python package in editable mode + install UI deps.
- `make server`: run backend (`python -m ormah.main`) with reload.
- `make ui-dev`: run Vite dev server (proxies `/ui`, `/agent`, `/admin` to `localhost:8787`).
- `make dev`: run backend + UI dev server together.
- `make restart`: rebuild the UI and restart the backend.
- `make ui-build`: build UI into `src/ormah/ui_dist/`.
- `make test`: run pytest.
- `make lint`: run Ruff on `src/` and `tests/`.
- `make help`: list available targets.
- `make smoke`: run Docker fresh-install smoke test.
- CLI: `ormah ...` (notably `ormah server start [-d]`, `ormah setup`, `ormah mcp`).
- Single test example: `uv run pytest tests/test_engine/test_whisper_context.py::TestWhisperFlatRankedDisplay -v`.
- Before testing the installed CLI, run `uv tool install . --reinstall`; the `ormah` binary in `~/.local/bin/ormah` uses the installed tool environment, not the editable source tree.
- Release flow: `./scripts/release.sh [patch|minor|major|<version>]`, then `git push && git push --tags`.

## Planning Workflow

- Always plan before making changes. Explore the relevant code before editing files or running mutating commands.
- For non-trivial work, present the plan first and then implement against the approved direction.
- Prefer the simplest design that solves the problem; justify any added complexity.

## Architecture Notes

- Ormah is a local-first persistent memory system for AI agents with MCP, REST, and CLI interfaces.
- Core entities are nodes (content, type, tier, space, confidence, importance, FSRS stability) and typed edges (weight + optional reason).
- Space is project scope, auto-detected from the git repo name.
- Layer stack: adapters (`MCP`, CLI, OpenAI) → FastAPI routes (`/agent`, `/admin`, `/ui`, `/ingest`) → `MemoryEngine` + background jobs → embeddings/hybrid search → SQLite index → markdown files in `memory/nodes/`.
- Frontend stack: React + TypeScript + Vite; main views include graph visualization, search, node detail, review queue, insights, and admin.

## Coding Style & Naming Conventions

- Python: 4-space indent, type hints encouraged, double quotes, max line length 100 (see `tool.ruff` in `pyproject.toml`).
- UI: TypeScript/React with 2-space indent; components in `ui/src/components/`, hooks in `ui/src/hooks/`.
- Naming: Python `snake_case`; TS/React `camelCase` for values and `PascalCase` for components.
- Don’t hand-edit generated UI artifacts in `src/ormah/ui_dist/`; change `ui/` sources and rebuild.

## Testing Guidelines

- Framework: `pytest` (+ `pytest-asyncio`, `pytest-httpx` where needed).
- Conventions: tests live under `tests/` and follow `test_*.py` naming.
- Add a regression test for bug fixes; keep tests deterministic and fast.
- Test and verify every change before suggesting a commit. If verification needs live services or manual steps, spell that out instead of skipping it silently.
- Do not confuse the two eval systems: the main whisper regression suite lives in `tests/test_engine/test_whisper_context.py`, while `eval/` is a separate retrieval-eval system and is not the same thing.

## Commit & Pull Request Guidelines

- Commit messages follow a Conventional Commits-style pattern: `feat(scope): ...`, `fix: ...`, `docs: ...`, `refactor: ...`, `test: ...`, `chore: ...`.
- PRs should include: a clear problem/solution description, linked issues (if any), notes on config/env changes, and UI screenshots when visuals change.
- Before opening a PR: ensure `make test` and `make lint` pass.
- After major feature or design changes, ask whether to bump the version and publish before touching release/version files.

## Configuration & Security

- Use `.env.example` as the baseline for local `.env` overrides; never commit secrets or API keys.
- Default server: `http://localhost:8787`.
- Key config knobs live in `.env`, especially `ORMAH_PORT`, `ORMAH_MEMORY_DIR`, `ORMAH_EMBEDDING_MODEL`, `ORMAH_EMBEDDING_PROVIDER`, `ORMAH_LLM_PROVIDER`, and `ORMAH_LLM_MODEL`.

## Ormah Memory Usage

- Use Ormah memory actively while working on this repo: remember decisions, user preferences, failed approaches, useful resources, and completed milestones.
- Store memories at natural save points rather than batching everything at the end; keep each memory atomic and self-contained.
- Use `recall` or `get_self` before assuming prior context; use `mark_outdated` when a stored memory is wrong or superseded.
- Set `space=null` for user identity/preferences that should apply across projects; otherwise keep repo-specific memories in the project space.
- When whispered memories are clearly useful or clearly irrelevant, submit implicit feedback so retrieval improves over time.
- If a client exposes background maintenance and whisper signals maintenance is due, run maintenance out of band rather than interrupting the active task.

## Agent-Specific Instructions

- Prefer root-cause fixes over patches; do not paper over issues.
- Keep diffs focused, and update tests/docs alongside behavior changes.
- Update `README.md` when a meaningful feature or behavioral change affects users or contributors.
