Record a lesson into the persistent store. Returns the new lesson.

Recall top-k lessons matching query (FTS5 retrieval).

Return the most-recent lessons (chronological).

Return lessons filtered by category (most-recent first).

Bump times_used on a lesson — call when you actually applied it.

Return total and per-category counts.

Run deterministic static checks. Returns Markdown report + raw findings list.

Return the full AGENTS.md content (auto-curated project conventions).

Append a new convention to AGENTS.md and return its line number.

Suggest a fix sketch by combining the issue with k similar past lessons.

This is deterministic text-stitching — no LLM is called. The orchestrator (which has the LLM) reads the result and decides whether to apply.

Return a Markdown draft of new AGENTS.md conventions from recent lessons.

The orchestrator curates which lines to apply by calling set_convention() for each. The agent itself does no LLM calls — the draft is a deterministic aggregation of stored signals (category breakdown, frequently-recurring tags, never-recalled lessons, top-referenced).

Run external linter(s) and test runner; return findings + summary.

Each tool maps to the same Finding shape the built-in analyzer uses, with source set to the tool name (e.g. 'ruff', 'pytest'). Tools not on PATH are skipped with a reason field, not raised as errors.

Same report as smart-agent doctor CLI, returned as a string.

Useful when the orchestrator wants to spot-check the installation during a session.

Return a structured JSON snapshot for monitoring.

Fields: ok boolean — always true if the store could be opened schema_version stored schema_version current_schema version this code expects wal_mode WAL / journal-mode status db_path absolute path to the SQLite file db_size_bytes file size on disk lessons_total row count in the lessons table conventions_path where AGENTS.md lives conventions_writable bool — whether AGENTS.md can be appended to

Use this for liveness/readiness checks, not for hot-path validation.