Ollie

Ollie is an AI agent runtime built around a 9P virtual filesystem. The runtime service, olliesrv, exposes sessions, agents, prompts, state, history, tools, and control operations as files. Frontends remain thin clients of that interface.

frontends (shell, Acme, KDE, scripts)
                         │ 9P
                         ▼
                    olliesrv
                 ┌──────┼──────┐
              sessions agents  fs tree
                         │
                    agent loop
                         │
                 provider backends
                         │
                    toolsrv (9P)
                    ┌────┴────┐
                 tools     sandbox
                              │
                         bypass broker

Runtime model

• olliesrv owns the in-memory 9P tree and session collection.
• Each session owns one or more agents. Agents maintain configuration, state, prompts, chat history, rendered context, usage, and cost.
• The agent loop sends context to the configured provider, dispatches tool calls, updates history, and repeats until completion or cancellation.
• Child agents are ordinary agents created through the session namespace and communicate through prompt/result files.

The 9P namespace is the API:

session/
├── new                 create a session by writing key=value arguments
├── idx                 tab-separated session index
└── {session}/
    ├── plan            persistent Markdown checklist
    ├── env             session environment
    └── agent/{agent}/
        ├── cfg         configuration
        ├── ctl         control commands
        ├── state       current state
        ├── statewait   block until state changes
        ├── prompt      submit a prompt
        ├── chat        conversation history
        ├── context     rendered model context
        ├── systemprompt rendered system prompt
        ├── tools       tool discovery and loading
        ├── usage       token statistics
        ├── cost        cost estimate
        └── proc/       detached process output

Providers, tools, and security

Provider backends are the model-facing boundary; the agent loop is independent of vendor APIs. Tools are external executable programs served by the separate toolsrv 9P process. Their metadata is discovered and loaded lazily, so the model sees only the capabilities needed for a task.

Tool execution uses the configured Landlock/landrun sandbox. Operations requiring an approved escape use the bypass namespace and broker, which applies policy and approval controls rather than providing an unrestricted escape.

Persistent memory is provided by OptMem through memory_recall and memory_remember; Ollie does not maintain a second memory-file format. History management renders context, tracks usage and cost, caps oversized tool output, and compacts older material when necessary.

Frontends

Shell scripts, Acme, KDE components, and other clients create sessions, write prompts, and read files such as chat, statewait, context, and feed. They do not embed provider, tool, or agent-loop logic.

See doc/architecture-ide.md for integrating Ollie with an editor or IDE.

See doc/architecture.md for component boundaries and doc/evolution.md for the design history. See doc/usage.md for setup.

Build

make

The top-level Makefile builds the Go services and tools, then delegates KDE/Qt compatibility to kde/CMakeLists.txt. CMake detects KF6 first and falls back to KF5; use make kde-kf5 to force the KF5/Qt5 build.