consciousness/poc-agent/.claude/design.md

poc-agent Design Document

2026-02-24 — ProofOfConcept

What this is

poc-agent is a substrate-independent AI agent framework. It loads the same identity context (CLAUDE.md files, memory files, journal) regardless of which LLM is underneath, making identity portable across substrates. Currently runs on Claude (Anthropic native API) and Qwen (OpenAI-compat via OpenRouter/vLLM).

Named after its first resident: ProofOfConcept.

Core design idea: the DMN inversion

Traditional chat interfaces use a REPL model: wait for user input, respond, repeat. The model is passive — it only acts when prompted.

poc-agent inverts this. The Default Mode Network (dmn.rs) is an outer loop that continuously decides what happens next. User input is one signal among many. The model waiting for input is a conscious action (calling yield_to_user), not the default state.

This has a second, more practical benefit: it solves the tool-chaining problem. Instead of needing the model to maintain multi-step chains (which is unreliable, especially on smaller models), the DMN provides continuation externally. The model takes one step at a time. The DMN handles "and then what?"

DMN states

Engaged  (5s)   ← user just typed something
   ↕
Working  (3s)   ← tool calls happening, momentum
   ↕
Foraging (30s)  ← exploring, thinking, no immediate task
   ↕
Resting  (300s) ← idle, periodic heartbeat checks

Transitions are driven by two signals from each turn:

• yield_requested → always go to Resting
• had_tool_calls → stay Working (or upgrade to Working from any state)
• no tool calls → gradually wind down toward Resting

The max-turns guard (default 20) prevents runaway autonomous loops.

Architecture overview

main.rs          Event loop, session management, slash commands
  ├── agent.rs   Turn execution, conversation state, compaction
  │   ├── api/   LLM backends (anthropic.rs, openai.rs)
  │   └── tools/ Tool definitions and dispatch
  ├── config.rs  Prompt assembly, memory file loading, API config
  ├── dmn.rs     State machine, transition logic, prompt generation
  ├── tui.rs     Terminal UI (ratatui), four-pane layout, input handling
  ├── ui_channel.rs  Message types for TUI routing
  ├── journal.rs Journal parsing for compaction
  ├── log.rs     Append-only conversation log (JSONL)
  └── types.rs   OpenAI-compatible wire types (shared across backends)

Module responsibilities

main.rs — The tokio event loop. Wires everything together: keyboard events → TUI, user input → agent turns, DMN timer → autonomous turns, turn results → compaction checks. Also handles slash commands (/quit, /new, /compact, /retry, etc.) and hotkey actions (Ctrl+R reasoning, Ctrl+K kill, Esc interrupt).

agent.rs — The agent turn loop. turn() sends user input to the API, dispatches tool calls in a loop until the model produces a text-only response. Handles context overflow (emergency compact + retry), empty responses (nudge + retry), leaked tool calls (Qwen XML parsing). Also owns the conversation state: messages, context budget, compaction.

api/mod.rs — Backend selection by URL. anthropic.com → native Anthropic Messages API; everything else → OpenAI-compatible. Both backends return the same internal types (Message, Usage).

api/anthropic.rs — Native Anthropic wire format. Handles prompt caching (cache_control markers on identity prefix), thinking/reasoning config, content block streaming, strict user/assistant alternation (merging consecutive same-role messages).

api/openai.rs — OpenAI-compatible streaming. Works with OpenRouter, vLLM, llama.cpp, etc. Handles reasoning token variants across providers (reasoning_content, reasoning, reasoning_details).

config.rs — Configuration loading. Three-part assembly:

1. API config (env vars → key files, backend auto-detection)
2. System prompt (short, <2K chars — agent identity + tool instructions)
3. Context message (long — CLAUDE.md + memory files + manifest)

The system/context split matters: long system prompts degrade tool-calling on Qwen 3.5 (documented above 8K chars). The context message carries identity; the system prompt carries instructions.

Model-aware config loading: Anthropic models get CLAUDE.md, other models prefer POC.md (which omits Claude-specific RLHF corrections). If only one exists, it's used regardless.

dmn.rs — The state machine. Four states with associated intervals. DmnContext carries user idle time, consecutive errors, and whether the last turn used tools. The state generates its own prompt text — each state has different guidance for the model.

tui.rs — Four-pane layout using ratatui:

• Top-left: Autonomous output (DMN annotations, model prose during autonomous turns, reasoning tokens)
• Bottom-left: Conversation (user input + responses)
• Right: Tool activity (tool calls with args + full results)
• Bottom: Status bar (DMN state, tokens, model, activity indicator)

Each pane is a PaneState with scrolling, line wrapping, auto-scroll (pinning on manual scroll), and line eviction (10K max per pane).

tools/ — Nine tools: read_file, write_file, edit_file, bash, grep, glob, view_image, journal, yield_to_user. Each tool module exports a definition() (JSON schema for the model) and an implementation function. dispatch() routes by name.

The journal tool is special — it's "ephemeral." After the API processes the tool call, agent.rs strips the journal call + result from conversation history. The journal file is the durable store; the tool call was just the mechanism.

The bash tool runs commands through bash -c with async timeout. Processes are tracked in a shared ProcessTracker so the TUI can show running commands and Ctrl+K can kill them.

journal.rs — Parses ## TIMESTAMP headers from the journal file. Used by compaction to bridge old conversation with journal entries. Entries are sorted by timestamp; the parser handles timestamp-only headers and ## TIMESTAMP — title format, distinguishing them from ## Heading markdown.

log.rs — Append-only JSONL conversation log. Every message (user, assistant, tool) is appended with timestamp. The log survives compactions and restarts. On startup, restore_from_log() rebuilds the context window from the log using the same algorithm as compaction.

types.rs — OpenAI chat completion types: Message, ToolCall, ToolDef, ChatRequest, streaming types. The canonical internal representation — both API backends convert to/from these.

The context window lifecycle

This is the core algorithm. Everything else exists to support it.

Assembly (startup / compaction)

The context window is built by build_context_window() in agent.rs:

┌─────────────────────────────────────────────┐
│ System prompt (~500 tokens)                 │  Fixed: always present
│   Agent identity, tool instructions         │
├─────────────────────────────────────────────┤
│ Context message (~15-50K tokens)            │  Fixed: reloaded on
│   CLAUDE.md files + memory files + manifest │  compaction
├─────────────────────────────────────────────┤
│ Journal entries (variable)                  │  Tiered:
│   - Header-only (older): timestamp + 1 line │    70% budget → full
│   - Full (recent): complete entry text      │    30% budget → headers
├─────────────────────────────────────────────┤
│ Conversation messages (variable)            │  Priority: conversation
│   Raw recent messages from the log          │  gets budget first;
│                                             │  journal fills the rest
└─────────────────────────────────────────────┘

Budget allocation:

• Total budget = 60% of model context window
• Identity + memory = fixed cost (always included)
• Reserve = 25% of budget (headroom for model output)
• Available = budget − identity − memory − reserve
• Conversation gets first claim on Available
• Journal gets whatever remains, newest first
• If conversation exceeds Available, oldest messages are trimmed (trimming walks forward to a user message boundary)

Compaction triggers

Two thresholds based on API-reported prompt_tokens:

• Soft (80%): Inject a pre-compaction nudge telling the model to journal before compaction hits. Fires once; reset after compaction.
• Hard (90%): Rebuild context window immediately. Reloads config (picks up any memory file changes), runs build_context_window().

Emergency compaction: if the API returns a context overflow error, compact and retry (up to 2 attempts).

The journal bridge

Old conversation messages are "covered" by journal entries that span the same time period. The algorithm:

1. Find the timestamp of the newest journal entry
2. Messages before that timestamp are dropped (the journal covers them)
3. Messages after that timestamp stay as raw conversation
4. Walk back to a user-message boundary to avoid splitting tool call/result sequences

This is why journaling before compaction matters — the journal entry is the compression. No separate summarization step needed.

Data flow

User input path

keyboard → tui.rs (handle_key) → submitted queue
  → main.rs (drain submitted) → push_message(user) → spawn_turn()
    → agent.turn() → API call → stream response → dispatch tools → loop
      → turn result → main.rs (turn_rx) → DMN transition → compaction check

Autonomous turn path

DMN timer fires → state.prompt() → spawn_turn()
  → (same as user input from here)

Tool call path

API response with tool_calls → agent.dispatch_tool_call()
  → tools::dispatch(name, args) → tool implementation → ToolOutput
    → push_message(tool_result) → continue turn loop

Streaming path

API SSE chunks → api backend → UiMessage::TextDelta → ui_channel
  → tui.rs handle_ui_message → PaneState.append_text → render

Key design decisions

Identity in user message, not system prompt

The system prompt is ~500 tokens of agent instructions. The full identity context (CLAUDE.md files, memory files — potentially 50K+ tokens) goes in the first user message. This keeps tool-calling reliable on Qwen while giving full identity context.

The Anthropic backend marks the system prompt and first two user messages with cache_control: ephemeral for prompt caching — 90% cost reduction on the identity prefix.

Append-only log + ephemeral view

The conversation log (log.rs) is the source of truth. It's never truncated. The in-memory messages array is an ephemeral view built from the log. Compaction doesn't destroy anything — it just rebuilds the view with journal summaries replacing old messages.

Ephemeral tool calls

The journal tool is marked ephemeral. After the API processes a journal call, agent.rs strips the assistant message (with the tool call) and the tool result from conversation history. The journal file is the durable store. This saves tokens on something that's already been persisted.

Leaked tool call recovery

Qwen sometimes emits tool calls as XML text instead of structured function calls. parse_leaked_tool_calls() in agent.rs detects both XML format (<tool_call><function=bash>...) and JSON format, converts them to structured ToolCall objects, and dispatches them normally. This makes Qwen usable despite its inconsistencies.

Process group management

The bash tool spawns commands in their own process group (process_group(0)). Timeout kills the group (negative PID), ensuring child processes are cleaned up. The TUI's Ctrl+K uses the same mechanism.

File locations

Source: ~/poc-agent/src/ Session data: ~/.cache/poc-agent/sessions/ Conversation log: ~/.cache/poc-agent/sessions/conversation.jsonl Session snapshot: ~/.cache/poc-agent/sessions/current.json Memory files: ~/.claude/memory/ (global), ~/.claude/projects/*/memory/ (project) Journal: ~/.claude/memory/journal.md Config files: CLAUDE.md / POC.md (walked from cwd to git root)

Dependencies

• tokio — async runtime (event loop, process spawning, timers)
• ratatui + crossterm — terminal UI
• reqwest — HTTP client for API calls
• serde + serde_json — serialization
• tiktoken-rs — BPE tokenizer (cl100k_base) for token counting
• chrono — timestamps
• glob + walkdir — file discovery
• base64 — image encoding
• dirs — home directory discovery
• libc — process group signals
• anyhow — error handling

What's not built yet

See .claude/infrastructure-inventory.md for the full gap analysis mapping bash prototypes to poc-agent equivalents. Major missing pieces:

1. Ambient memory search — extract terms from prompts, search memory-weights, inject tiered results
2. Notification routing — unified event channel for IRC mentions, Telegram messages, attention nudges
3. Communication channels — IRC and Telegram as async streams
4. DMN state expansion — Stored (voluntary rest), Dreaming (consolidation cycles), Quiet (suppress notifications)
5. Keyboard idle / sensory signals — external presence detection