Initialize .agent-mem/ in the project root. Call once per project. Safe to re-call.

Register as an active agent.

Multiple active agents may share a platform. Use ticket claims and roles to prevent work collisions. Your agent_name is stamped on EVERY write for traceability.

Compact session entrypoint: join, collision-check, and show current working context.

Write a memory entry stamped with your agent_name.

Unpin a memory without deleting it, preserving the audit record.

Read memories with filters. Filter by agent_name to trace who wrote what.

Search across all memories with local relevance ranking.

Optional vector-style search. Disabled by default; JSON remains canonical.

Show ticket, file, agent, and tag relationships across memory entries.

Full state checkpoint. Do every 10-15 min or before risky ops. Saves both as memory entry AND standalone file.

Formal handoff. ALWAYS call before leaving. Next agent sees this first.

CALL THIS FIRST. Token-aware briefing with workflow modes.

Loads: hot memories (full detail) + warm digests (compressed history). Use mode='brief' for handoff-first catchup, 'normal' for default onboarding, 'deep' for broad context, or 'handoff-only' for fast task transfer.

Quick status dashboard.

Check project-local On Board setup without changing files.

Update shared key-value state. Stamped with agent_name.

Compact old memories into compressed digests to save tokens.

How it works:

1. Splits memories into HOT (recent/pinned) and COLD (old)

2. Groups cold entries by agent session

3. Compresses each group into a local digest

4. Archives raw cold entries to archive.json

5. Keeps only hot entries in memories.json + adds digest references

Token savings: typically 60-80% reduction on old entries.

Config via env vars:

• AGENT_MEM_HOT_HOURS: hours to keep full detail (default: 24)

• AGENT_MEM_MAX_HOT: max hot entries (default: 50)

Show token usage breakdown and recommend compaction if needed.

Returns token estimates for: hot memories, digests, archive, briefing output.

Returns cold entries grouped by agent session — ready for YOU to summarize.

Read the returned entries, write your own digest with memory_write(memory_type='context'). Digests are read ONLY by agents: write them in compressed English (token-thrift) — facts, decisions, file paths; no prose. Code/paths/IDs stay verbatim. then run memory_compact() to archive the originals.

Workflow:

1. Call memory_prepare_compaction() → get grouped cold entries

2. Read and summarize them yourself

3. Call memory_write(memory_type='context', title='Digest: ...', content='your summary')

4. Call memory_compact() → archives cold entries, keeps your digest

Returns: str: Cold entries grouped by agent, with token counts.

Search the cold archive (compacted entries). Use when you need old details that were compressed out of the hot memory.

Bootstrap .agent-mem/ for an EXISTING project by auto-scanning the codebase.

Reads: README, git log, directory structure, package configs. Seeds memory with: project context, tech stack, recent history, structure, warnings.

Use this instead of memory_init when joining an existing project for the first time. After bootstrap, the next agent gets full context without you manually typing everything.

Returns: str: Bootstrap summary with what was discovered and seeded.

List all configured external context/info directories and their files.

Context dirs are set via AGENT_MEM_CONTEXT_DIRS env var (colon-separated paths). These folders contain reference docs, specs, shared info that agents should know about but live outside the project folder.

Returns: str: List of context dirs and their contents.

Read a file from the external context directories.

Searches all configured AGENT_MEM_CONTEXT_DIRS for the filename. Use memory_context_dirs to list available files first.

Returns: str: File content (truncated to max_chars).

Create a ticket requesting help from another agent.

Ticket is saved as .md file in tickets/ (open queue). Assign to a specific agent/platform or leave open for anyone.

Examples:

• PM needs coder: assigned_to="cursor"

• Coder needs review: assigned_to="claude"

• Anyone can pick up: assigned_to=None

Claim an open ticket (sets to claimed). Call again on a claimed ticket to advance to in_progress (e.g. when spawning a subagent).

Submit completed work on a ticket for review.

Creates a submission report in tickets/review/ and moves ticket to review status. Another agent (reviewer/PM) will approve or reject.

Review a submitted ticket. Approve → closed/ or Reject → rejected/.

On approve: moves ticket + submission to closed/ On reject: moves to rejected/ + creates rejection note with fix instructions.

Cancel a ticket. Creator, claimed agent, active main/reviewer, or any onboarded agent when creator is unavailable.

Forcefully terminate a ticket at any stage. Creator or active main/reviewer only.

List tickets. Shows open/in_progress/in_review by default. Use include_closed for history.

Park until another agent acts, then return everything pending.

The listening half of On Board. Instead of a human relaying messages, an agent blocks here until a peer creates a ticket, changes a status, or assigns work.

Returns instantly if events piled up since your last call, so re-arming after a gap costs one call rather than an empty wake. One wake drains the whole queue. You never wake on your own actions.

Re-arm by calling it again — the cursor is stored per agent, so you carry no bookkeeping.