fossel: Instructions file for Codex

AGENTS.md

Orientation and roadmap for agents working on Fossel.

What Fossel is

A local-first MCP memory server for coding assistants. It stores per-repo conventions, bug fixes, decisions and reviewer patterns in SQLite with FTS5 search, and serves them back to Cursor / Claude Desktop / any stdio MCP client. The guiding constraint behind almost every decision: no LLM, no model download, no network at runtime. Where a general memory tool would call an LLM, Fossel either uses a heuristic or hands the judgment back to the client's own model.

Layout

• src/db/ — client.ts (singleton connection, WAL), migrate.ts (the runtime source of truth: sequential named migrations), schema.sql (hand-maintained reference of the final shape).
• src/lib/ — domain logic: repo.ts (canonical repo-key resolution + alias merging), context.ts (retrieval assembly), fts.ts (three-tier FTS), fusion.ts (weighted RRF), embeddings.ts, idf.ts, vector-index.ts, merge.ts (dedupe), dedupe.ts, inference.ts, temporal.ts.
• src/tools/ — thin MCP tool registrations. Each resolves the repo, calls a lib function, and returns { content: [{ type: "text" }] }, catching errors into isError: true rather than throwing. Keep tools thin; put logic in lib.
• bench/ — retrieval benchmark. npm run bench scores fts/vector/hybrid on a committed eval set; npm run bench:check fails on drift; npx tsx bench/sweep.ts tunes constants.

Working agreement

• Measure retrieval changes. Anything touching search must be run through npm run bench and the results snapshot committed. Keep a change only if the numbers support it; several ideas have been implemented, measured, and removed (see the "tried and rejected" notes in fusion.ts and fts.ts). Do not re-try those blindly.
• Verify before claiming done. npm run ci (typecheck + typecheck:bench + tests + build + smoke) must pass. Commits should be independently green.
• Windows dev shell is PowerShell 5 — use ; not &&; multi-line commit messages go through a file (git commit -F), not inline -m.
• The fusion weight is coupled to embedder quality. Re-sweep DEFAULT_VECTOR_WEIGHT whenever the embedder changes.
• Stored embedding vectors must stay a pure function of their own text, or every vector goes stale on any corpus change (forcing a full re-index). Corpus-derived weighting (IDF) is applied to the query side only for this reason.