graymatter AGENTS.md

AGENTS.md

If you're an AI agent (Claude Code, OpenCode, Codex, Cursor, Antigravity, custom MCP client) operating in this repo, read this first. Full operational manual: docs/AGENTS.md.

This repo is a memory system for AI agents. While you work here, you also get to use it: it's wired into your MCP toolbelt as five tools that persist facts and checkpoints across sessions.

Your tools

Tool	Required params	Optional
memory_search	agent_id, query	top_k (default 8)
memory_add	agent_id, text	—
memory_reflect	action (add|update|forget|link), agent	text, target (which one is required depends on action — for forget, either works)
checkpoint_save	agent_id	state (JSON-encoded string)
checkpoint_resume	agent_id	—

memory_reflect uses agent_id (canonical since ADR-014). The other four also use agent_id. The deprecated alias agent is still accepted for compatibility; agent_id wins when both are set.

When to call which

• Before answering any question that depends on prior context → memory_search first.
• After learning a user preference, project convention, or making a non-obvious decision → memory_add.
• When the user corrects you or a fact becomes stale → memory_reflect with action="update" and target=<old fact text>.
• At the start of a session that may resume a long task → checkpoint_resume. Before stopping mid-task → checkpoint_save.

First call

The very first thing to do when you open a session is pull what you already know:

{ "tool": "memory_search", "args": {
    "agent_id": "<project>-<your-role>",
    "query":    "<the task the user just asked you to do>",
    "top_k":    8
}}

Inject the returned facts into your working context before composing your reply.

Identity

Pick a stable agent_id of the form <project>-<role> (e.g. graymatter-backend, okuna-frontend). Don't invent a new ID per session — that defeats persistence.