backlog-mcp: Instructions file for Codex

AGENTS.md — backlog-mcp

backlog-mcp is a local-first, markdown-backed engine for agent context and memory. Tasks, decisions, and memories share one store, used through the CLI, MCP, and a live read-only viewer. Humans can read, edit, and diff the markdown without the tool.

Critical constraints

• Preserve human-visible markdown and one source of truth. No LLM in the server write path. Local mode grows; D1/Workers is descoped, retained with no parity owed. Never compromise local capabilities for D1 parity.
• For code changes, follow ADR 0134: transport-free business logic in core, thin peer adapters, injected ports, modular typed code. Fix architecture violations; never grow the allowlist.
• Unit tests only, with mocked external dependencies and memfs. Repository/git probes may read real files via vi.importActual('node:fs'), never write them. Read the testing guide for any test work, including running and debugging.
• User-facing changes need a CHANGELOG.md entry; every version bump updates the changelog in the same change. See the packages and releases guide.
• Before calling a tool, expand its full input schema. Discovery summaries are not argument contracts; the shared Markdown body field is content.

Minimal memory loop

• Wake once at session start: backlog_wakeup / backlog wakeup. Do not repeat during ordinary work. After context loss, recover from the durable work record; wakeup with operation can restore a known live operation.
• Recall when prior knowledge matters, once per topic: backlog_recall / backlog recall "<topic>". Search the current corpus with backlog_search; expand selected entities with backlog_get (context: true for relation stubs).
• Inspect age, provenance, and correction lineage. Current user direction, project decisions, and verified contracts outweigh stale memories.
• Remember durable, non-obvious facts with backlog_remember, one fact per memory. Correct with supersedes or state_key; never duplicate contradictions.