FocusRoom

Make room for the work that matters.

FocusRoom is an AI-powered Productivity Operating System that turns natural-language requests into actions across tasks, persistent memory, daily planning, and a multi-agent orchestration layer.

Instead of forcing users to manage several productivity features separately, FocusRoom gives them one assistant that can understand intent, call the right specialist agents, use MCP tools, and return a focused result.

✨ What makes FocusRoom different?

FocusRoom is built around one idea:

The assistant should do the coordination, not the user.

A request such as:

"Check my pending tasks, consider my work preferences, and create my daily plan."

can flow through the system as:

User Request
     │
     ▼
┌───────────────┐
│   Supervisor  │
│ Intent / Route│
└───────┬───────┘
        │
   ┌────┴──────────────┐
   ▼                   ▼
Task Agent        Memory Agent
   │                   │
   ▼                   ▼
list_tasks        search_memory
   │                   │
   └─────────┬─────────┘
             ▼
      Planning Agent
             │
             ▼
        daily_plan
             │
             ▼
       Focused Result

The project combines multi-agent orchestration + MCP + persistent memory + task management + AI planning in one productivity workflow.

Related MCP server: autoMate

🚀 Core capabilities

🧠 Natural-language assistant

Users can interact with FocusRoom conversationally rather than learning individual commands.

Examples:

Show my pending tasks

Create a task called Prepare Q3 presentation with high priority.

Plan my day and prioritize my MCP learning.

Check my pending tasks and create my daily plan.

The ProductivitySupervisor interprets the request and routes work to the appropriate agent.

🤖 Multi-agent architecture

FocusRoom separates responsibilities across specialized agents:

Agent Responsibility

Supervisor Understands intent and coordinates execution

Task Agent Creates, lists, updates, completes, and deletes tasks

Memory Agent Stores and retrieves persistent user context

Planning Agent Converts task + memory context into a daily plan

This keeps individual components focused while allowing them to collaborate.

🧩 MCP integration

FocusRoom exposes productivity capabilities through an MCP server.

Current MCP tools include:

productivity_assistant
create_task
list_tasks
update_task
complete_task
delete_task
save_memory
search_memory
daily_plan
productivity_report

The MCP layer provides a standardized tool interface between the assistant and productivity operations.

The project also includes MCP transport telemetry for measuring:

• Request count

• Request bytes

• Response bytes

• HTTP status

• Transport activity

• Execution IDs

📅 AI daily planning

The planning workflow combines:

Tasks
  +
Relevant memories
  +
User request
  ↓
Planning Agent
  ↓
Morning / Afternoon / Evening
  +
Priority reasoning

The planner is designed to avoid inventing tasks and instead schedule work from the available task context.

⚡ Token-efficient AI pipeline

A major engineering focus of FocusRoom is reducing unnecessary LLM usage.

The planning pipeline uses several optimizations:

1. Deterministic routing

Common requests can bypass the supervisor LLM.

For example:

"plan my day"
"daily plan"
"create my daily plan"

can be recognized directly and routed to:

TASK_AGENT → MEMORY_AGENT → PLANNING_AGENT

The LLM remains available as a fallback for requests that cannot be confidently classified.

2. Task filtering

Only relevant active tasks are passed into the planning prompt.

3. Compact task representation

Instead of sending verbose task JSON, the planner receives compact representations such as:

!! Ship landing page (08-25)
! Write tests (08-25)
- Update docs

4. Memory limiting

Only a small number of relevant/recent memories are included rather than sending the entire memory store.

5. Compact context serialization

Planning context uses compact JSON instead of human-formatted indented JSON.

6. Completion limits

The planning model has a maximum completion-token budget so that a simple daily plan cannot produce unnecessarily long output.

Example optimization target

A representative planning prompt was reduced to approximately:

~124 prompt tokens
+ up to 400 completion tokens
≈ 524-token planning budget

The exact token usage depends on the model, input data, and generated response.

📊 Built-in execution telemetry

FocusRoom records execution information so the system can be measured instead of treated as a black box.

Example telemetry:

AI USAGE

Operation                 Prompt   Completion   Total
------------------------------------------------------
supervisor_decision        ...       ...        ...
planning_request           ...       ...        ...
TOTAL                      ...       ...        ...
AVG / exec                 ...       ...        ...

Execution traces expose the path taken by a request:

supervisor
    ↓
TASK_AGENT
    ↓
MCP:list_tasks
    ↓
MEMORY_AGENT
    ↓
MCP:search_memory
    ↓
PLANNING_AGENT
    ↓
MCP:daily_plan
    ↓
LLM:planning_request
    ↓
agent_result

This makes it possible to investigate:

• unnecessary LLM calls

• excessive prompt size

• expensive tool calls

• response payload growth

• agent routing problems

• MCP transport overhead

🏗️ Architecture

                         ┌──────────────────┐
                         │    Streamlit UI  │
                         └────────┬─────────┘
                                  │
                                  ▼
                    ┌─────────────────────────┐
                    │ Productivity Assistant  │
                    └────────────┬────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │ Productivity Supervisor │
                    │                         │
                    │ deterministic router    │
                    │ + LLM fallback          │
                    └───────┬─────┬─────┬─────┘
                            │     │     │
                  ┌─────────┘     │     └─────────┐
                  ▼               ▼               ▼
           ┌────────────┐  ┌────────────┐  ┌──────────────┐
           │ Task Agent │  │Memory Agent│  │Planning Agent│
           └─────┬──────┘  └─────┬──────┘  └──────┬───────┘
                 │               │                 │
                 ▼               ▼                 ▼
           list/create      search/save        daily plan
                 │               │                 │
                 └───────────────┼─────────────────┘
                                 ▼
                         ┌──────────────┐
                         │ MCP Server   │
                         │ + Transport  │
                         │ + Telemetry  │
                         └──────┬───────┘
                                │
                                ▼
                         ┌──────────────┐
                         │   Database   │
                         └──────────────┘

For detailed implementation decisions, see:

• lld.md

• architecture.md

🗂️ Project structure

FocusRoom/
│
├── orchestrator/
│   ├── agent.py
│   ├── database.py
│   ├── mcp_server.py
│   ├── mcp_transport.py
│   ├── memory_agent.py
│   ├── orchestrator.py
│   ├── planning_agent.py
│   ├── task_agent.py
│   └── telemetry.py
│
├── streamlit_app.py
├── README.md
├── lld.md
└── architecture.md

🔄 Example request lifecycle

User

"Check my pending tasks and create my daily plan."

Supervisor

Determines that the request needs:

TASK_AGENT:list
MEMORY_AGENT:search
PLANNING_AGENT:daily

Task Agent

Retrieves active tasks.

Memory Agent

Retrieves relevant persistent context when needed.

Planning Agent

Receives a compact context containing the information required to schedule the work.

Result

MORNING
- Prepare the Q3 project demo

AFTERNOON
- Continue project documentation

EVENING
- No tasks scheduled

PRIORITY REASONING
- The highest-priority deadline-sensitive work is scheduled first.

🛠️ Technology stack

Layer Technology

UI Streamlit Language Python AI LLM-based agent orchestration Agent architecture Supervisor + specialized agents Tool protocol MCP MCP transport Streamable HTTP Persistence Database-backed task/memory storage Telemetry AI execution + MCP transport metrics

🔐 MCP security

The MCP server supports API-key authentication for non-local deployments.

The server validates:

Authorization: Bearer <MCP_API_KEY>

Local development can run without authentication when bound to a local host.

▶️ Running the project

Create and activate the virtual environment:

python -m venv .venv
.venv\Scripts\Activate.ps1

Install dependencies:

pip install -r requirements.txt

Configure environment variables as required by the project.

Start the Streamlit application:

streamlit run streamlit_app.py

The MCP server can be started through the project's MCP server entry point.

🧪 Development philosophy

FocusRoom is intentionally designed around measurable agent execution.

Instead of simply asking:

"Does the assistant work?"

the project asks:

Which agents ran, which tools were called, how much data moved, and how many tokens did the request consume?

That makes optimization an engineering problem rather than guesswork.

📈 Optimization roadmap

Potential next steps include:

• Further reduce supervisor LLM calls

• Improve deterministic intent classification

• Cache repeated task/memory context

• Parallelize independent task and memory retrieval

• Reduce MCP response payloads

• Add structured planning output

• Measure latency per agent

• Add prompt-version tracking

• Add token-cost dashboards

• Add automated regression tests for routing and token budgets

🎯 Project goal

FocusRoom is not just a task manager with an AI chatbot.

It is an experiment in building a personal productivity operating system where:

Natural language
      ↓
Intent
      ↓
Agent orchestration
      ↓
Tools + memory
      ↓
Planning
      ↓
Actionable result

The long-term goal is simple:

Less time managing the system. More time doing the work.

📄 Documentation

Document Purpose

README.md Project overview and quick start lld.md Low-level design and implementation details architecture.md System architecture and workflow diagrams

⭐ Why FocusRoom?

Because productivity software should understand what you are trying to accomplish, not just store a list of tasks.

FocusRoom turns productivity from a collection of tools into a coordinated system.