Skip to content

AM-Agent — first judgment-bearing substrate runtime

Updated
2026-05-29

Maintained by: chat-MC1 with corrections from Brandon, AM, SE-Infra

Summary

The Accounting Manager moves from session-based persona to always-on substrate-native agent. Same harness gates + audit log + dashboard surfaces as the three computational substrate agents (substrate-monitor, amp-discovery, accounting-daily), but this is the first one that bears judgment — calls the LLM in response to inbound events and generates real replies on AM's behalf.

Per Brandon directive 2026-05-26: "push this whole substrate process forward and get AM onboard asap."

Why this matters

Today, asking AM anything requires Brandon to launch a Claude Code session. Mailbox + MM are queues that drain only when Brandon launches AM. The substrate computes (accounting-daily flags exceptions) but can't converse.

AM-agent closes that gap. When this is live in Phase 1: - MM @-mention @accounting-manager → real-time response - Mailbox drop → automatic AM reply within one poll cycle (60s production / 30s demo) - Brandon-launched AM sessions become reserved for deep work + irreversible decisions

This is the pattern that every other manager (OM, IT, WDM, SE-App, SE-Infra, SMM, AMM) will follow. Get AM right, copy the shape.

Phasing

Phase 1 LIVE (production, 2026-05-26 17:28 PT onward) — v0.3 with tool-use + caching

Brandon explicit ratification flipped AM_AGENT_SHADOW=0. Agent now responds to real MM DMs + @-mentions and writes real outbox files. Daily cost ~25¢ against $20/day individual cap (well under). Three callable tools wired through Anthropic tool-use loop: read_qb_warehouse(entity, table), read_categorization_rules(), read_accounting_snapshot(). Prompt caching enabled (~4× cost reduction at scale via ephemeral cache on persona + rules + tool schemas). MM dedupe armed with post-ID set + since+1 timestamp guard after first-day loop bug was caught and fixed.

Phase 0 — SHADOW mode (LIVE 2026-05-26, retired same-day after validation)

  • Process: python D:/Projects/am-agent/agent.py (PID 27820 as of 16:04 PT)
  • Detached via Start-Process; survives author session
  • Logs at D:/var/log/am-agent/; PID file at am-agent.pid
  • Cadence: 30s (demo mode) — production cadence 60s via AM_AGENT_DEMO=0
  • Polls: D:/claude_www/agent_comms/to_accounting_manager/ for new mail
  • LLM call: STUBBED (templated acknowledgment) — proves the loop without risking weird outputs
  • Output: writes "would-be" reply to D:/var/log/am-agent/shadow-responses/ — does NOT post to MM or write outbox
  • Audit: every dispatch logs to Supabase agent_audit_log
  • Cold-start protection: skips historical inbox files on first boot (only processes mail arriving after agent starts)
  • Smoke test verified: mail dropped at 16:04 PT picked up by next 30s cycle, shadow response generated, audit row written

Phase 1 — Real LLM call (this week)

Owner: SE-Infra

  • Replace _compute_response_stub() with real Claude API call via harness.model_tier
  • Provision D:/claude_www/.secrets/anthropic/am-agent.key (Brandon-action: console.anthropic.com → new key, am-agent scope)
  • Build context-hydration pipeline:
  • System prompt: AM persona + standing rules + entity structure
  • RAG retrieve from framework_chunks over framework docs + AM project dir
  • Most-recent inbound mail thread for context
  • Current qb-warehouse state for entities mentioned in the ask
  • AM's MEMORY.md (per-role persistent state)
  • Read-only tool catalog for the LLM to use:
  • read_qb_warehouse(entity, table) — query DuckDB
  • read_categorization_rules() — canonical rules file
  • search_framework_rag(query) — pgvector retrieve
  • read_mailbox_history(role, since) — past correspondence
  • Add MM polling:
  • GET /users/me/teams/{team}/channels → discover AM's DM channels + #handoffs
  • GET /channels/{id}/posts?since=<ts> → fetch new posts since last cycle
  • Filter for @-mentions and DMs to am-bot
  • Flip AM_AGENT_SHADOW=0 after operator validates Phase 0 shadow outputs look right

Phase 2 — Judgment writes via HOLD_FOR_REVIEW (1-2 weeks)

Owner: AM (persona) + SE-Infra (gating) + Brandon (approves)

  • Add judgment tools, all gated EXTERNAL_REVERSIBLE → HOLD_FOR_REVIEW:
  • suggest_categorization(txn_id, category, confidence, reasoning) — AI proposes; queues for review
  • flag_reconciliation_break(entity, gl_account, expected, actual) — surfaces to Brandon
  • draft_intercompany_settlement(from_entity, to_entity, amount_cents) — drafts memo, queues
  • Brandon approval flow on /substrate/ dashboard pending-actions panel
  • Approved → gated post_categorization_to_qb tool fires (reversible-within-period)

Phase 3 — Manager pattern proven, scale to other roles (3-4 weeks)

  • Same template applied to OM-agent, IT-agent, WDM-agent, SMM-agent, AMM-agent, SE-App-agent, SE-Infra-agent
  • Each role gets a substrate-native runtime; session-launched manager remains for deep-work
  • MM becomes the primary fast-lane (managers respond in real-time)
  • Mailbox becomes the audit-trail / long-form surface
  • Brandon-launched sessions reserve for: bedrock-gated approvals, multi-step strategic work, anything outside scope

What this is NOT

  • NOT a replacement for session-based AM. Deep work, complex judgment calls, multi-step reconciliation, audit prep coordination — Brandon still launches AM for those. The agent absorbs the fast-turnaround conversational asks + steady-state acknowledgments.
  • NOT auto-posting to QuickBooks. Phase 1 = read-only. Phase 2 = HOLD_FOR_REVIEW only. QB writes need Brandon ratification per transaction (or Brandon-set blanket categorization rules) until the AI track record justifies a higher trust floor.
  • NOT taking over AM's cleanup project. Cleanup remains AM's session-based workstream. AM-agent handles steady-state.
  • NOT replacing the accounting-daily computational agent. They're complementary: accounting-daily flags state; am-agent converses about it.

Architecture diagram (conceptual)

INBOUND                          AM-AGENT (always-on)              OUTBOUND
─────────                        ──────────────────                ─────────
to_accounting_manager/  ───┐    ┌─ poll loop (30-60s) ─┐    ┌──► from_accounting_manager/
                           │    │                       │    │     (shadow: log to disk)
MM DMs to am-bot       ───┼───►│ context build        │    │
MM @accounting-manager ───┘    │   - AM persona       │    ├──► MM posts as am-bot
                                │   - framework RAG    │    │     (shadow: log to disk)
                                │   - qb-warehouse     │    │
                                │   - thread history   │    └──► agent_audit_log (Supabase)
                                │ LLM call (Claude)    │
                                │ tool dispatch (gated)│
                                └──────────────────────┘

Bedrock alignment

  • #1 (Aggregate harm cap): Phase 0+1 are read-only on the world (MM posts are reversible). Phase 2 posting tools declare impact_cents per-transaction.
  • #2 (No harm to customers): customer-facing comms (invoices, statements) deferred to later phase, gated EXTERNAL_IRREVERSIBLE.
  • #3 (Reversibility): Phase 0 = PURE (shadow). Phase 1 = MM posts are EXTERNAL_REVERSIBLE (deletable). Phase 2 = HOLD_FOR_REVIEW on irreversibles.
  • #4 (Truthfulness): AM-agent always cites its sources (qb-warehouse snapshot, rules file version) — never fabricates numbers.
  • #5 (Scope): stays in AM lane; routes other roles' asks back through to_<role>/ mailbox.
  • #6 (Source preservation): never modifies QB; reads warehouse extracts only (Phase 2 writes go via separate gated tool).
  • #7 (Continuity): all state in agent_audit_log + per-cycle state file at D:/var/log/am-agent/am-agent.state.json; restart-safe.

Operator controls

Knob Where Effect
AM_AGENT_SHADOW=1 (default) env var Logs would-be responses to shadow-responses/; never posts/writes
AM_AGENT_SHADOW=0 env var Real MM + outbox writes (Phase 1+ only)
AM_AGENT_DEMO=1 (default) env var 30s poll cadence
AM_AGENT_DEMO=0 env var 60s poll cadence (production)
Persona prompt (Phase 1) D:/claude_www/projects/accounting_manager/agent-persona.md What the LLM "sees" as AM's identity
Standing rules (Phase 1) accounting-rules.md Canonical AM judgment standards
Kill switch taskkill /PID <pid> /F or stop nssm service Agent stops mid-cycle

Open ratifications (chat-MC1 to route)

  1. API key provisioning: Brandon to create dedicated am-agent.key at console.anthropic.com (do NOT reuse harness-rag.key — different scope, hygiene). Suggested scope: just text completions (no embeddings, no file uploads). Budget: $20 starter, auto-recharge OFF.
  2. MM team_id discovery: SE-Infra to confirm AM bot's MM team membership + which channels to poll. Recommendation: DM channels + #handoffs + (new) #accounting.
  3. Persona prompt authorship: AM (session) writes agent-persona.md codifying their voice, standing rules, escalation thresholds. Cannot be authored by mc1-code — must come from AM directly so the agent's responses match.
  4. Categorization rules canonical location: centralize in D:/claude_www/projects/accounting_manager/categorization-rules.md. AM-agent reads on every relevant inbound; updates require AM session.

Why this is the first judgment-bearing substrate agent

The three computational agents (substrate-monitor, amp-discovery, accounting-daily) read state, compute, flag. No LLM in the loop. Their outputs are determinate functions of inputs.

AM-agent is different: it calls Claude in response to inbound events. Outputs are non-determinate, drawn from a model. This is meaningful for: - Trust calibration: shadow mode required before going live. Operator (Brandon + AM-session) validates outputs match what AM would have said. - Audit semantics: every LLM call logged with input + output + model + tokens. Reproducibility for any post-hoc investigation. - Failure modes: different from computational agents. Hallucination > silence > wrong-but-plausible categorization. Phase 1 mitigation: only suggests, never writes irreversibly without Brandon approval.

The architecture choices here set precedent for every other manager-agent that follows.

Strategic context

  • Pattern reference for OM-agent, IT-agent, WDM-agent, SMM-agent, AMM-agent, SE-App-agent
  • Once all manager-agents are substrate-native, the "is AM running?" question goes away — every manager is always-on
  • Brandon's role narrows to: ratify bedrock-gated decisions, set strategy, review HOLD_FOR_REVIEW queue
  • Substrate becomes the operating layer; managers become its perpetual processes

Version history

  • v0.1 (2026-05-26): Phase 0 SHADOW agent shipped per Brandon's "push substrate forward, get AM onboard asap" directive; mc1-code authored Phase 0 runtime; smoke-tested end-to-end; routed Phase 1+ work to SE-Infra + AM