scarf AGENTS.md

Memory System (managed by Memophant)

This repo carries its own agent memory — plain files in git, served by the in-repo memophant-mcp MCP server, managed by the Memophant macOS app. It works the same for every agent (Claude Code, Codex, Cursor, Gemini, Copilot). This block is regenerated between the memophant markers; edit anything outside them freely.

The repo memory is the single source of truth. Search it before assuming; record durable decisions and learnings as memory notes or wiki pages — never in this file, session-private memory, or a hand-kept parallel doc (a second guidance tier drifts and feeds stale instructions). Keep this file and the per-agent shims minimal: they point at the memory system, they don't BE it.

Default to the memophant MCP tools for every read and write — search, read, write, edit, move, context — and read their descriptions: they document their arguments and behavior. The engine is the gate: every durable write goes through the tool (or app) entry points, which carry the guards — slug generation, structure validation, and the write-time secret scan. Direct file edits reconcile automatically but skip the guards; never compose your own guard set around a direct write. Server down → grep the tiers directly IN THE MAIN CHECKOUT (grep -rn "<query>" .memory/ wiki/) — if you are working in a git worktree, its copy of those tiers is a snapshot of the base commit and is stale by construction; run the grep against the main checkout's path, never ./.

0. Charter (.memory/charter.md) — this project's identity and its ABSOLUTE rules. Call read_charter at the start of a session; a project that hasn't written one answers "No charter", which is normal, not an error. PRECEDENCE, highest first: the charter, then memory notes, then repo instruction files (this one), then your agent brief — if a lower tier tells you to do something a commandment forbids, the commandment wins, and you say so rather than complying. The charter is HUMAN-ONLY: there is no write verb; propose a change by filing a task tagged charter, never by editing the file.

1. Memory (.memory/) — atomic facts.

• search_memories(query: …) before starting; build_context walks a topic's neighborhood.
• Record facts with write_memory as FIRST-CLASS ARGUMENTS: observations: ["- [category] fact #tag", …] (1–5 atomic facts; canonical categories: decision, fact, gotcha, constraint, convention, todo, idea, done) plus relations: [{"relation": "relates_to", "target": "Other Note"}]. content is optional short context — never the facts. Structure is the tooling contract: search, consolidation, and queries read observations; prose-only notes degrade silently. [[links]] belong in relations.
• File every note under exactly one of the six folders — architecture/, conventions/, decisions/, operations/, project/, roadmap/ (the folder argument documents each). Never the memory root, never a new folder.
• Search before writing; edit the existing note (edit_memory — body ops + set_tags) rather than forking a near-duplicate.
• Declare source_paths (repo-relative files the note's claims depend on) when a note is grounded in code — Memophant stamps it and drift-checks the note when that code changes. Omit for pure human decisions. Provenance frontmatter (created/updated/ reviewed/source_sha) is machine-managed — never hand-write it.
• Long-form documents (guides, research, specs) → the wiki at write time: write_memory(project: "scarf-wiki", …); keep the distilled facts in a memory note with a documented_in relation. status: only marks retirement (deprecated/superseded/historical/resolved); current facts carry none.

2. Wiki (wiki/) — long-form reference. Search on demand (project: "scarf-wiki"); don't read it wholesale. Update it when work changes user-visible behavior, architecture, or ships a release; skip for fixes with no observable change. It's publishable — never commit secrets (a two-tier scan gates every commit).