​

Agent Capabilities

​

Project Configuration: AGENTS.md and CLAUDE.md

​

Why AGENTS.md?

​

AskUserQuestion: Structured Interactive Dialogue

​

Protocol Mechanics

1. Validation — 1 to 4 questions, each with 2 to 4 options, unique labels, headers capped at 12 characters
2. Event emission — tool.question_requested with a UUID request_id and the full question payload
3. Suspension — a deferred Promise is stored in _pendingQuestions keyed by request_id; the tool loop blocks on this promise
4. Gateway relay — the question_requested event is broadcast to the client via the existing PodiumEventMapper path
5. Client rendering — the client displays the question dialog with selectable options (an “Other” free-text option is auto-provided)
6. Answer flow — the user’s response arrives as an answer_question client message, which Podium delivers to the agent’s onAnswer() callback
7. Resume — onAnswer() matches the request_id, resolves the pending promise, and the tool loop continues with the formatted answer as the tool result

​

Schema

{
  questions: Array<{
    question: string      // "Which database should we use?"
    header: string        // "Database" (max 12 chars, rendered as chip)
    options: Array<{
      label: string       // "PostgreSQL (Recommended)"
      description: string // "Battle-tested, rich ecosystem"
    }>
    multiSelect: boolean  // false = single choice, true = checkboxes
  }>
}

​

Mode Availability

​

Plan Lifecycle: Structured Task Decomposition

​

Architecture

​

Event Flow

LLM → PlanCreate tool call
  → Agent intercepts, validates, creates Plan via PlanTracker
  → Emits plan.created { plan_id, title, steps[] }
  → Gateway maps to plan_created, persists, broadcasts
  → Client updates activePlan in chat store
  → plan-progress.tsx renders title + step list + progress bar

LLM → PlanUpdate { step_id: "step-0", status: "in_progress" }
  → Agent intercepts, updates PlanTracker
  → Emits plan.step_started { plan_id, step_id, title }
  → Gateway maps to plan_step_started (ephemeral), broadcasts
  → Client updates step status, progress bar animates

​

PlanCreate Schema

{
  title: string,
  steps: Array<{
    title: string,
    description?: string  // optional detail, shown during in_progress
  }>
}

​

Mode Availability

​

Cross-Session Memory: LLM-Extracted Persistent Knowledge

​

Storage Architecture

data/sessions/{sessionId}/
├── session.db          # Messages, events, turns, usage (hot path)
├── session.db-wal
├── memory.db           # Extracted memories (cold path, created lazily)
└── memory.db-wal

• Zero write-lock contention — memory extraction writes (which happen at session cleanup) never block the event/message write path
• Independent WAL — memory.db can be checkpointed and replicated independently
• Lazy creation — the file is only created when the first insert_memory command arrives; short sessions that don’t extract memories incur zero filesystem overhead

​

Extraction Pipeline

1. Trigger — the agent’s cleanup() method fires when a session ends
2. Guard — sessions with fewer than 4 conversation turns are skipped (insufficient signal)
3. LLM call — the full conversation history is sent to the Ensemble client with a structured extraction prompt
4. Parse — the response is parsed as a JSON array of memories, each with content, category, confidence, and tags
5. Emit — a memory.extracted event carries the memories through the gateway
6. Persist — the gateway’s event stream handler intercepts memory_extracted, delegates to MemoryService.saveExtracted(), which writes to the session’s memory.db via the writer worker

​

Memory Schema

CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  tenant_id TEXT NOT NULL,
  category TEXT NOT NULL DEFAULT 'general',
  content TEXT NOT NULL,
  confidence REAL NOT NULL DEFAULT 1.0,
  tags TEXT DEFAULT '[]',
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER,
  superseded_by TEXT REFERENCES memories(id)
);

​

Cross-Session Recall

1. Index lookup — the tenant’s registry database contains a memory_sessions table that tracks which sessions have extracted memories and when
2. Targeted reads — only sessions with memories are queried (no directory scanning)
3. Per-session reads — each session’s memory.db is opened read-only via the reader worker
4. Deduplication — exact content matches are collapsed
5. Ranking — memories are sorted by confidence × recency and the top N are returned

​

Gateway Integration

​

Agent Modes and Tool Availability

​

System Prompt Integration

• AskUserQuestion — askUserQuestionGuidance() in Sections.ts: when to use the tool, option formatting conventions, the auto-provided “Other” option, and the explicit instruction not to use it for plan approval
• Plan tools — tool schemas in schemas/index.ts with descriptive parameter documentation; the LLM learns usage from schema descriptions rather than a dedicated prompt section
• Memory — extraction is implicit (fires at cleanup); recall can be injected into the system-reminder context alongside CLAUDE.md and git status on session start
• AGENTS.md — discovered and injected automatically via ProjectConfig.buildContextInjection(); no prompt section needed because the content is the prompt