Architecture

Overview

Working Mind is a local-first terminal AI agent built on a single-agent loop with tool calling. The core is pack-agnostic -- it knows nothing about any domain. Packs define the domain through prompts, tools, skills, and personas.

Tech Stack

The OpenAI SDK is the backbone of the provider layer. Working Mind uses it for:

• Streaming chat completions with tool calling
• Structured function call formatting
• OpenRouter and any OpenAI-compatible endpoint (Ollama's OpenAI-compat API, vLLM, LM Studio)

Anthropic and Google have their own API formats, so Working Mind uses dedicated adapters for those providers while the OpenAI SDK covers everything else.

Agent Loop

The main loop runs in runAgent():

1. Stream -- Send the conversation (system prompt + history) to the LLM. Stream the response.
2. Check for tool calls -- If the LLM responds with tool calls, execute them. If not, return the response to the user.
3. Execute tools -- For each tool call: parse arguments, get user approval, execute, push result to conversation.
4. Repeat -- Continue the loop until the LLM responds without tool calls or the turn budget is exhausted.

The loop has guardrails:

• Turn budget -- Maximum iterations (default: 20, configurable)
• Context compaction -- When conversation exceeds 100K characters, older messages are compacted into a synthetic summary
• Orphan cleanup -- Tool result messages without matching tool calls are removed before each turn
• Cancellation -- Ctrl+C aborts the current LLM request

System Prompt Assembly

The system prompt is assembled from multiple sources:

1. Pack prompt -- From the pack's prompt.md (or config.systemPrompts.default if no pack)
2. Current task -- Directive from slash commands (e.g., /ingest sets currentTask)
3. Available skills -- List of inactive skills the user can activate
4. Active skills -- Instructions from currently active skills
5. Turn budget -- Information about the available tool-call turns
6. Knowledge index -- Truncated list of entities in the knowledge graph
7. Project rules -- From AGENTS.md, LAB.md, or WBRAIN.md in the current directory

MCP Integration

MCP servers provide tools. The flow:

1. Pack declares servers -- pack.json lists required and optional servers
2. Registry connects -- On startup, Working Mind connects to each MCP server via stdio transport
3. Tools discovered -- Each server exposes tools (e.g., mcp__brave-search__web_search)
4. Tool filtering -- Packs can filter which tools are available (via toolFilter in personas)
5. Execution -- When the LLM calls a tool, Working Mind routes it to the correct MCP server

All MCP servers run as local child processes. No remote connections. Stdio transport sidesteps the security vulnerabilities of remote MCP servers.

Pack Loading

Packs are loaded at startup:

1. Resolve pack names -- From --pack flags (default: starter)
2. Find pack directory -- Check builtin packs/ directory, then ~/.wmind/packs/
3. Read pack.json -- Parse manifest, validate schema
4. Read prompt.md -- Load the system prompt
5. Read personas, skills, commands -- Load from subdirectories
6. Register MCP servers -- Declare servers in the MCP registry
7. Create agent -- Assemble system prompt, merge tools, store on agent instance

Tool Resolution

When the agent is created, tools come from three sources:

1. Pack tools -- Defined in the pack's tools array (usually empty for declarative packs)
2. Native tools -- Built-in tools like memory_* (12 knowledge graph tools)
3. MCP tools -- Discovered from connected MCP servers

Persona tool filters can restrict which tools are available:

• preset: "all" -- all tools available
• preset: "readonly" -- only read tools
• preset: "none" -- no tools
• include: [...] -- only these tools
• exclude: [...] -- all tools except these

Session Persistence

Sessions are saved to ~/.wmind/sessions/ as JSON files. Each session stores:

• Conversation messages
• Agent persona and pack name
• Pack system prompt (for correct reconstruction on resume)
• Active skills
• Creation and update timestamps

When you resume a session, Working Mind reconstructs the agent with the same pack prompt, tools, and conversation history.

Context Compaction

When the conversation exceeds 100K characters, older messages are replaced with a synthetic summary:

1. Identify old messages -- Everything before the most recent tool-call sequence
2. Preserve tool pairs -- Tool calls and their results must stay together
3. Generate summary -- Replace old messages with a note summarizing what happened
4. Continue -- The agent operates on the compacted context

This prevents context window overflow while maintaining conversation coherence.

Key Design Decisions

• Single agent, not multi-agent -- One well-configured agent with the right tools matches multi-agent systems at lower token cost
• MCP as tool layer -- MCP servers are sensors (search, read) and actuators (create, write, scrape)
• Local-first -- No cloud dependency for the core. API keys go to LLM providers, not to us
• Declarative packs -- No code required. Anyone can create a pack by editing markdown files
• Approval gate -- Tool calls require user approval by default. Auto-approve is opt-in