agent-working-memory

Register or heartbeat an agent in the hive. Call at session start and periodically.

Sign off from the hive. Releases all locks and marks agent as dead. Call at session end.

Create a task assignment. Orchestrator uses this to dispatch work to agents.

Get your current assignment, or auto-claim the next pending task. Call this to find out what to work on.

Report progress or completion of an assignment. Set status to in_progress, completed, failed, or blocked.

Acquire a file lock to prevent concurrent edits by other agents.

Release a file lock you hold.

List all currently held file locks across all agents.

Issue a broadcast command to all agents. Orchestrator only. Commands: BUILD_FREEZE, PAUSE, RESUME, SHUTDOWN.

Check for active commands from the orchestrator. Call periodically to stay responsive to BUILD_FREEZE, PAUSE, etc.

List available workers in the hive. Filterable by capability, status, and workspace.

Report a finding (bug, issue, suggestion) discovered during work.

Get a full dashboard view of the hive: agents, assignments, locks, findings, and stats.

Store a memory. The salience filter decides whether it's worth keeping (active), needs more evidence (staging), or should be discarded. CALL THIS PROACTIVELY — do not wait to be asked. Write memories when you: - Discover something about the codebase, bugs, or architecture - Make a decision and want…

Recall memories relevant to a query. Uses cognitive activation — not keyword search. ALWAYS call this when: - Starting work on a project or topic (recall what you know) - Debugging (recall similar errors and solutions) - Making decisions (recall past decisions and outcomes) - The user mentions a to…

Report whether a recalled memory was actually useful. This updates the memory's confidence score — useful memories become stronger, useless ones weaken. Always call this after using a recalled memory so the system learns what's valuable.

Retract a memory that turned out to be wrong. Creates a correction and reduces confidence of related memories. Use this when you discover a memory contains incorrect information.

Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct. Use this when: - A status or count has changed (e.g., "5 reviews done" → "7 reviews done") - Architecture or infrastructure evolved…

Identify THIS AWM instance — agent id, mode (standalone/hive), backend, store path, code provenance, ports, and the sibling agent spaces present in the same store. Call when unsure which AWM instance or memory space you are talking to.

Get memory health stats — how many memories, confidence levels, association count, and system performance. Also shows the activity log path so the user can tail it to see what's happening.

Save your current execution state so you can recover after context compaction. ALWAYS call this before: - Long operations (multi-file generation, large refactors, overnight work) - Anything that might fill the context window - Switching to a different task Also call periodically during long sessio…

Restore your previous execution state after context compaction or at session start. Returns: - Your saved execution state (task, decisions, next steps, files) - Recently recalled memories for context - Your last write for continuity - How long you were idle Use this at the start of every session o…

Scan a project's documentation + repository and return CANDIDATE memories to seed a cold store. Use this when the store is empty / you're new to a project. The scan is deterministic (real file contents, not guesses) — YOUR job is to refine the candidates into atomic, recall-shaped memories, run the…

Return the onboarding interview questions. Ask the user ONE at a time, starting with the goal of the memory system, and ask follow-ups for clarity. Turn each answer into a canonical memory.

Create a task that you need to come back to. Tasks are memories with status and priority tracking. Use this when: - You identify work that needs doing but can't do it right now - The user mentions something to do later - You want to park a sub-task while focusing on something more urgent Tasks aut…

Update a task's status or priority. Use this to: - Start working on a task (open → in_progress) - Mark a task done (→ done) - Block a task on another (→ blocked) - Reprioritize (change priority) - Unblock a task (clear blocked_by)

List tasks with optional status filter. Shows tasks ordered by priority (urgent first). Use at the start of a session to see what's pending, or to check blocked/done tasks.

Get the single most important task to work on next. Prioritizes: in_progress tasks first (finish what you started), then by priority level, then oldest first. Skips blocked and done tasks. Use this when you finish a task or need to decide what to do next.

Signal that you're starting a significant task. Auto-checkpoints current state and recalls relevant memories. CALL THIS when starting: - A multi-step operation (doc generation, large refactor, migration) - Work on a new topic or project area - Anything that might fill the context window This ensur…

Signal that you've finished a significant task. Writes a summary memory and auto-checkpoints. CALL THIS when you finish: - A multi-step operation - Before switching to a different topic - At the end of a work session This captures what was accomplished so future sessions can recall it.

Compress a STRUCTURED tool output (JSON object/array, query rows, log records) into TOON — a compact, schema-aware tabular encoding — before putting it in your context. Cuts ~50-65% of the tokens on uniform arrays at zero comprehension cost (validated: models read TOON as accurately as JSON). Use th…

Retrieve the verbatim original text for a 'ref' returned by compress_output. Use this when you need the exact, uncompressed source (e.g. to pass it to another tool unchanged). Returns an error if the ref has expired (originals are kept for the most recent compressions only).