razberri

Private hackathon repository for razberri, a privacy-first, local-first second-brain assistant.

You capture the loose threads you are afraid you'll lose track of — reminders, follow-ups, deadlines, errands, ideas, and "don't let me forget this" family contactents. razberri then uses a local MCP agent layer plus Work IQ-style context (calendar, mail, and message signals) to decide what matters now, resurface it proactively, and turn each thread into one tiny next step.

Two design lenses sit underneath that one product:

• Neurodivergent-aware / ADHD executive-function support — non-judgmental, small-next-action oriented, "stuck is information, not failure."
• Microsoft Work IQ alignment — Outlook, Calendar, and Messages are the first context surfaces, but the executive-function engine is local and service-agnostic.

Core loop:

Capture → Context → Prioritize → Surface → Resolve

📖 Full reference: see DOCUMENTATION.md for the consolidated guide (architecture, MCP tools, web API, CLI, configuration, and roadmap).

What's in the box

razberri runs locally and offline by default. Everything below is on-device; nothing leaves your machine unless you explicitly enable the live Microsoft Graph path.

Surface	Where	Role
MCP server	mcp_server/main.py	FastMCP server exposing 15 ADHD/second-brain tools
Web app + JSON API	mcp_server/web.py	FastAPI app; single-page UI + JSON API
CLI demo	demo.py	Judge-friendly commands (brief, breakdown, best-time, calendar import, portal)
Local memory	mcp_server/thread_store.py, mcp_server/nexus_client.py	SQLite-backed threads + "Nexus" event history
Dev portal	mcp_server/devportal.py	Local admin console to configure the optional integrations

Optional, opt-in capabilities (graceful fallback when absent)

• LLM-assisted breakdown & mission text (mcp_server/llm_client.py) — local Ollama is the default provider; Azure OpenAI is also supported. If the model is unreachable, razberri falls back to a deterministic heuristic and never crashes.
• ML best-time recommender (mcp_server/timing_model.py, mcp_server/timing_engine.py) — a scikit-learn model learns your follow-through hours from local history. Until trained, a statistical profile is used.
• Offline calendar import (mcp_server/calendar_import.py) — import a real .ics so the demo runs on your actual schedule without any live account.
• Live Microsoft Graph calendar (mcp_server/graph_transport.py) — implemented and opt-in via MSAL device-code. Mock mode is the default, and the live path is untested in this build; it degrades to mock fixtures on any auth/transport failure.

See WINDOWS_SETUP.md for turning each optional capability on.

Repository layout

mcp_server/        MCP server, FastAPI web app + API, tools, adapters, local memory
mock_data/         Graph-shaped mock fixtures (Outlook, Calendar, Messages, Planner, To Do, OneNote)
demo.py            CLI demo entry point
tests/             pytest suite (hermetic; ignores your local .env)
docs/              Supporting docs, archive, and planning notes (SPEC, PLAN, PRODUCT_STRATEGY, UI_REFRESH)
ARCHITECTURE.md    Adapter pattern + data flow
WINDOWS_SETUP.md   Turning on Ollama / ML best-time / live Graph
DEMO.md            2–3 minute demo script

Thread persistence

Captured threads are written to a local SQLite database so the running demo retains threads, importance fields, done/snoozed status, and the selected current thread across restarts. The public entry point is mcp_server/storage.py, which re-exports the underlying repository and adds two startup helpers:

• init_storage(path=None) builds the repository (or a disabled one when persistence is off).
• storage_status(repository=None) returns a JSON-serializable snapshot for /api/agent/status.

The FastAPI app wires both through a lifespan context manager so storage init runs once at boot.

• Default path: ./data/threads.db (relative to the working directory).
• Override with RAZBERRI_THREAD_DB_PATH.
• Set it to memory (or off / false / empty) to disable persistence (in-memory only).
• data/*.db and data/*.sqlite are gitignored — the database is a local runtime artifact.

Tests always run with an ephemeral temp-file database configured by tests/conftest.py, so they never touch real user data.

Run the prototype

On the Windows demo machine the validated path is system Python 3.13 with no venv — python -m pip install -r requirements.txt once, then run directly. On other machines, activate a venv first if you use one.

Start everything with one command

python run.py                 # starts the web app and opens the browser
python run.py --portal        # start the dev portal as the control center on :8765
python run.py --install       # pip install -r requirements.txt first, then start

run.py launches the FastAPI web app (UI + API) as a managed child process and stops it cleanly on Ctrl+C. Run python run.py --help for all flags (--host, --port, --reload, --no-browser).

With --portal, the dev portal becomes the control center: it opens on :8765, owns the web UI lifecycle (Start / Stop / Restart from the browser), and shows a live overview of every subsystem — web UI, LLM provider, the Ollama models detected on your machine, Azure, Microsoft sign-on, and the calendar source. The web UI then carries a "dev portal ↗" link back to it.

The MCP stdio server for MCP clients is separate: python mcp_server/main.py.

Or start the web app directly

pip install -r requirements.txt
uvicorn mcp_server.web:app --host 0.0.0.0 --port 8000

Override the database path for the demo:

RAZBERRI_THREAD_DB_PATH=./demo_data/threads.db uvicorn mcp_server.web:app --host 0.0.0.0 --port 8000

Open:

http://127.0.0.1:8000

LAN URL for testing from another device on your network (Wi-Fi IP as of 2026-06-12 — re-check with ipconfig if it changes):

http://192.168.1.188:8000

Development tooling

This project was built in Visual Studio Code with GitHub Copilot assistance. See docs/COPILOT_AND_VSCODE.md for the submission note describing how VS Code and Copilot supported implementation, testing, and documentation.

Validate

pytest -q

Expected: 102 passed. The suite is hermetic — it pins an opt-in-OFF baseline and ignores your local .env, so results do not depend on whether you have Ollama, Azure, or Graph configured.