uteke: Instructions file for Codex

AGENTS.md — uteke

Project

Uteke — local-first memory engine for AI agents. Rust workspace: uteke-core (engine), uteke-cli, uteke-server, uteke-mcp, docgen.

Session start (continuity ritual)

• Every new session/round: read & understand the team knowledge rooms (codecora-workflow-standard, uteke-conventions) before doing any work.
• Save every decision or important outcome back to the responsible room (this repo: uteke) during or at the end of the session.
• Handing over mid-task: leave a [HANDOFF] entry (current state, next step, blockers).

Stack

• Rust (workspace, single version in root Cargo.toml)
• Storage: SQLite (rusqlite bundled) + dual-engine vector index
• Vector engines: usearch (default, C++ FFI) OR vecq (quantized, zero C++ dep) — runtime-selected via UTEKE_VECTOR_BACKEND env or [vector] backend in uteke.toml (#1168)
• Embeddings: EmbeddingGemma Q4 ONNX (default) / OpenAI / Ollama
• Package manager: BUN for any JS/tooling (not npm). Rust uses cargo.
• Git author: email MUST be [email protected]
• Message & PR standard: keep commit messages, PR titles/bodies, comments and release notes clean — no third-party trailers, no generated-with lines (ecosystem message standard; enforced by tooling). See the team knowledge rooms.

Branch & release rules (STANDARD — applies to all CodeCora repos)

• Branches: develop = integration, main = release (tags cut from main).
• Branch naming: feat/, fix/, docs/, chore/, perf/, security/, refactor/, test/, build/, ci/. release/x and bare names are rejected.
• main only accepts PRs from develop or chore/release-* (Source Branch check).
• No main→develop sync PR. The repository rejects merge commits and main only receives squash commits, so main never becomes an ancestor of develop through a PR (a squash/rebase merge drops the -s ours merge and changes nothing, #1381). The divergence is resolved inside each release branch instead — see "Release procedure" below. Skipping that makes the develop→main PR conflict in ~30 files (merge-base stays at v0.13.2).
• PR body: ## What / ## Why / ## Testing headers are REQUIRED (CI enforces).
• CI is green + Cora bot clean before merge; never trust one gate alone. "Clean" means a REAL verdict ("✅ No issues found" or concrete findings): "Review could not complete" / "empty result" is a blocker. Since #1386 the Cora job diffs against the PR's own base branch (base-branch: origin/${{ github.base_ref }}); before that it defaulted to origin/develop, so PRs into main were reviewed against an empty diff. Re-run the job once; if it is still empty, investigate instead of accepting.
• Version: single workspace version in root Cargo.toml; internal deps (uteke-core/ uteke-mcp) must be bumped to the same version in the release commit.
• docs/api-reference.md is GENERATED (cargo run -p docgen) — never hand-edit.