🧩 MOSAIC — My Own Stories and Ideas Compilation

A privacy-first local diary agent that collects your fragmented daily inputs via Telegram, and turns them into diary entries, idea lists, mood insights, and conversations — fully offline, no API key required.

Features • Quick Start • Architecture • Contributing • Acknowledgements

About

MOSAIC is a personal side project built for three reasons:

1. Personal use — a private, always-local diary tool that actually fits into daily life
2. Easy to self-host — clone, configure, and run in minutes on any machine with Ollama
3. Learning by building — a hands-on exploration of core Agent components: Memory, RAG, Tools, Skills, Planning, and multi-turn conversation

If you are learning about LLM Agents or want a lightweight journaling tool that runs entirely on your own hardware, MOSAIC might be a good starting point.

Features

• 📝 Frictionless logging — send any text to the Telegram Bot and it is saved instantly
• 🖥️ Desktop/Web UI included — built-in browser frontend for input, write, browse, and chat
• 📲 Telegram mobile workflow — capture fragments, trigger generation, query history, and chat directly in Telegram
• 📖 Diary generation — daily diary entries assembled from your story records
• 💡 Ideas & TODOs — structured idea lists with actionable TODOs and thoughts
• 😌 Mood insights — emotional trend analysis over any time window
• 💬 Conversational AI — chat with MOSAIC about your records, with multi-turn memory and planning
• 🔒 Fully local — runs entirely on your machine via Ollama, no data leaves your device
• 💰 No token costs — no API key required, no usage fees, works completely offline
• 🔧 Model-agnostic — swap the LLM or embedding model to any Ollama-supported model

Telegram Demo

Telegram is not only for capture: you can log entries, trigger diary/ideas/mood generation, query records, and chat with MOSAIC directly from mobile.

Web Frontend

The web UI is for structured review, writing, and reflection.

• 📝 Input: capture quick daily fragments and save by date.
• ✍️ Write: edit manual markdown content for diary, ideas, and mood.
• 💬 Chat: reflect with RAG-assisted conversation over your own records.
• 📖 Diary: browse generated and manual diary history by calendar.
• 💡 Ideas: review structured idea notes and TODO-style outputs.
• 😌 Mood: inspect emotional trends and day-level mood details.
• 📜 Time Reel: read-only timeline table for raw entry browsing.

Calendar Interaction Rules

• 🗓️ Calendar icons = data exists: when a day shows icons, that day already has corresponding records/files.
• 👀 Click day to inspect board: clicking a calendar date loads that date's data board on the right side.
• ⚡ Input/Write writes immediately: in Input and Write, selecting a date and submitting writes data to the backend/database immediately.
• 🧭 Write supports type selection: in Write, you can choose which non-fragment type to save (diary / ideas / mood).
• 🧩 Manual vs LLM output are visually separated: calendar views use different icons to distinguish user-written non-fragment records vs LLM-generated non-fragment records.

Data Locality & Privacy

• 🔐 All user data stays local: SQLite database, vector store, generated markdown, and manual files are all stored on your own machine.
• 🏠 Privacy-first by design: no cloud API dependency, no automatic external upload, and you keep full control of your data files.

⚠️ Note: Response speed depends on your hardware and the model you choose. MOSAIC is tested on a mid-range CPU laptop with Qwen2.5:7B. Currently supports text input only.

Quick Start

Prerequisites

• Python 3.11+
• Ollama installed and running
• A Telegram Bot token (via @BotFather)

1. Clone the repo

git clone https://github.com/your-username/MOSAIC.git
cd MOSAIC

2. Install dependencies

pip install uv
uv sync

3. Pull models (or replace with any Ollama-supported model)

ollama pull qwen2.5:7b
ollama pull shaw/dmeta-embedding-zh

4. Set up environment

cp .env.example .env
# Add your TELEGRAM_TOKEN to .env

5. Start Ollama

ollama serve

6. Start the web server (frontend + API)

uvicorn api.server:app --reload --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 in your browser.

7. (Optional) Start Telegram Bot

python -m bot.telegram_bot

Then open Telegram, find your bot, and send /start.

Frontend Usage

• Open http://127.0.0.1:8000 to access the built-in frontend.
• Use Input / Write to create or edit daily records.
• Use Diary / Ideas / Mood / Time Reel to browse generated and raw history.
• Use Chat for RAG-assisted reflection over your records.

Architecture

MOSAIC/
├── api/
│   ├── server.py                # FastAPI app (serves API + frontend static files)
│   └── routes/
│       ├── entries.py           # Entries by date/month + read-only browse table
│       ├── write.py             # Manual markdown read/write endpoints
│       ├── generate.py          # Trigger diary/ideas/mood generation
│       ├── diaries.py           # Diary history/detail endpoints
│       ├── mood.py              # Mood calendar/detail/file endpoints
│       └── chat.py              # Chat API + conversation reset
│
├── bot/
│   └── telegram_bot.py          # Telegram Bot: message handling and command routing
│
├── core/
│   ├── database.py              # SQLite schema and CRUD helpers
│   ├── llm.py                   # LLMClient via Ollama
│   ├── processor.py             # Background pending-entry analyzer
│   ├── rag.py                   # ChromaDB vector retrieval
│   ├── tools.py                 # Utility tools for agent/runtime
│   ├── state.py                 # Multi-turn conversation state
│   ├── planner.py               # Multi-step intent planning
│   └── agents/                  # Main/Diary/Ideas/Mood/Chat agents
│
├── frontend/
│   ├── index.html               # Web UI layout
│   ├── app.js                   # Alpine.js state, tabs, loading logic
│   └── style.css                # Pixel theme + EN/CN typography
│
├── prompts/
│   ├── analyze_prompt.py
│   ├── planning_prompt.py
│   └── routing_prompt.py
│
├── skills/
│   ├── diary/                   # SKILL.md + scripts/generate.py
│   ├── ideas/                   # SKILL.md + scripts/generate.py
│   └── mood/                    # SKILL.md + scripts/generate.py
│
├── scripts/
│   ├── seed_english_data.py     # Seed English sample data
│   └── curate_march_data.py     # Curate March sample density/mix
│
├── tests/                       # Unit tests
├── img/                         # README demo GIF assets
├── data/                        # Runtime data (gitignored: db, vectors, generated/manual markdown)
├── .env                         # Environment variables (TELEGRAM_TOKEN, etc.)
├── pyproject.toml
└── README.md

Skill System

MOSAIC's skill system is inspired by Anthropic's Agent Skills specification, but adapted for local LLM constraints.

Each skill consists of:

• SKILL.md — a Markdown instruction file with a structured frontmatter (name, description) that the agent uses for intent routing, and a prompt body that guides the LLM during execution
• scripts/ — Python execution logic that orchestrates tool calls, database queries, and LLM generation

Unlike the official specification where the LLM directly triggers scripts, MOSAIC uses a two-stage approach:

1. Intent routing: main_agent.py reads all SKILL.md descriptions and routes to the appropriate skill
2. Execution: Python code calls the selected skill's script, which uses SKILL.md as the LLM prompt

This design improves reliability with smaller local models (7B parameters).

Acknowledgements

Built with the assistance of Claude (Anthropic) and Cursor (Anysphere).