niklas‑stephan.de

AGENTS.md rules: where they live and why

Last updated 05/11/2026 · agents, tools

  • kb-id: agents-md-shared-rule-official-docs
  • importance: medium
  • tags: agents, tools, conventions
  • updated: 2026-11-01
  • summary: How AGENTS.md is built per host from agents.md + host notes, and the context-size budget it must respect.

Where the agent rules live (git repo, shared)

  • Source truth: /data/ai-persistence/agents.md (shared rules) + /data/ai-persistence/hosts/<hostname>.md (host notes). Both in the Gitea repo kb-agent/ai-persistence.
  • /data/AGENTS.md on each server is generated by bin/mem render (also run by mem sync); it starts with a generated by ... DO NOT EDIT marker, so never edit it by hand. The ThinkPad renders to /home/handtrixxx/code/AGENTS.md instead (needs KB_HOME/AGENTS_WORKSPACE_FILE env overrides, see its host note).
  • Workflow for rule changes: edit agents.md or a host file -> mem lint -> test with mem render --out /tmp/x -> mem save "msg"; other hosts pick it up at their next mem sync.
  • Procedural detail belongs in skills (skills/agent-memory, skills/home-assistant) or KB memories, not in AGENTS.md. AGENTS.md holds only short rules that must apply in every thread; the memory protocol itself lives in skill agent-memory.

Context-size budget

  • The rendered AGENTS.md is injected into every agent thread; on the local 131k-context llama this is a per-thread cost. Budget: <= 9000 bytes (~2200 tokens). bin/mem render prints a warning above that. Shrunk from 13.2 KB to 6.5 KB on 2026-11-01 by removing duplication with the agent-memory skill and historical cruft from host notes (OpenCode/OpenClaw/LibreChat removals are KB facts, not rules).
  • Host notes carry only current state: what runs locally, which hosts are reachable how, where secrets are. Dead services and migration histories belong in KB memories (archived if needed).

Why “check official docs” rule exists

Agents answered config questions for standard third-party software (Traefik, Docker, HA…) from stale pre-trained memory. Rule: current official docs first, Context7 MCP (resolve-library-id -> query-docs) preferred, fetch as fallback; GitHub links must be probed via the API before fetch (memory github-link-validation).

Source: Wiki.js