<img src="docs/static/sol-wordmark.svg" alt="solstone" width="300">

# solstone — the journal

a memory your agents can work from. sol — the app on your devices — experiences your day with you and keeps it all in your journal. your journal is always private, only yours.

this repo is the journal: the memory that holds everything, plus the thin `sol` access client. it's the python core of the solstone platform — the [sol apps](https://solstone.app) on your devices pair with a journal running on a computer you choose. AI agents transcribe, extract entities, detect meetings, build knowledge graphs, and surface daily insights — all without any manual input. everything stays in daily journal directories on your machine. open source, local-first, no cloud required.

Python 3.11+, Linux + macOS, AGPL-3.0-only, maintained by [sol pbc](https://solpbc.org).

<img src="docs/static/screenshot-home.png" alt="solstone daily dashboard" width="800">

*Daily dashboard — goal, todos, upcoming events, and detected entities, all generated from observations. Facet tabs organize your life by project or context.*

## what you get

**a system of intelligence, not just storage.**

- **automatic transcription** — sol hears what you hear and keeps every conversation in your journal, transcribed with speaker identification and searchable.
- **people and projects** — extracted from your conversations and remembered across time.
- **knowledge graphs** — relationships between entities mapped automatically. who works with whom, which projects connect to which people.
- **meeting detection** — meetings identified, summarized, and linked. meeting prep that surfaces what you discussed last time and personal context you'd forget.
- **commitments** — todos extracted from natural conversation. no manual entry.
- **facet organization** — group everything by project or context (work, personal, client-name) with scoped views across all apps.
- **AI chat** — talk to your journal. ask anything about your digital life and get answers grounded in your actual data.
- **full-text search** — find anything you've ever seen or heard.
- **30 AI agents** — configurable workflows for activities, scheduling, research, media analysis, and more. extensible via the agent skill framework.
- **local-first** — all data in daily journal directories on your filesystem. configurable AI providers (Google Gemini, OpenAI, Anthropic). no cloud dependency.

<img src="docs/static/screenshot-transcripts.png" alt="solstone transcript viewer" width="800">

*Transcript viewer — dual-timeline navigation, speaker-diarized dialogue, audio playback, screen analysis. every conversation browsable by time.*

<img src="docs/static/screenshot-entities.png" alt="solstone people and projects" width="800">

*People and projects — automatically extracted and remembered across your journal with mention counts and relationship data.*

## architecture

```text
  +---------+       +----------------+       +---------+
  | observe | ----> |    journal     | ----> |  think  |
  | inputs  |       | YYYYMMDD/ dirs |       | process |
  +---------+       | media, jsonl,  |       | index   |
                    | entities       |       +----+----+
                    +-------+--------+            |
                            ^                     |
                            |  agent outputs      |
                       +----+----+                |
                       | cortex  | <--------------+
                       | agents  |
                       +---------+
                            |
  ==== callosum (event bus) | ==========================
                            |
                     +------+------+
                     |   convey    |
                     | web UI      |
                     +-------------+
```

- **observe** — receives audio and screen observations from standalone observers (solstone-linux, solstone-tmux, solstone-macos) via observer ingest. processes FLAC audio, WebM screen media, and timestamped metadata.
- **think** — transcribes audio with Parakeet, analyzes screen observations, surfaces entities, detects meetings, and indexes everything into SQLite. runs 30 configurable agent/generator templates from `solstone/talent/`.
- **cortex** — orchestrates agent execution. receives events, dispatches agents, writes results back to the journal.
- **callosum** — async message bus connecting all services. enables event-driven coordination between observe, think, cortex, and convey.
- **convey** — Flask-based web interface with 17 pluggable apps for navigating journal data.
- **journal** — `journal/YYYYMMDD/` daily directories. the single source of truth — transcripts, media, entities, agent outputs, and the SQLite index all live here.

## quick start

run a journal here — the full host:

```bash
uv tool install solstone-journal && uv tool install solstone
journal setup
```

pip and pipx equivalents, followed by `journal setup`:

```bash
pip install solstone-journal
pipx install solstone-journal && pipx install solstone
```

A `pip install solstone-journal` puts `journal` and `mlx-vlm-server` on PATH natively; `uv tool` and `pipx` expose each tool's own commands, so the journal install is two commands — the journal tool plus the thin `solstone` tool. For GPU transcription, install `solstone-journal-cuda` instead.

want only the thin `sol` client — to talk to a journal running elsewhere? `uv tool install solstone` (no extras), or `uvx solstone` for an ephemeral one-shot.

not sure a computer is up to running the journal? `uvx solstone check` gives a one-shot readiness verdict — GPU, memory, and disk — before you install anything.

then open http://localhost:5015 in a browser; the first-run wizard sets up your identity and gets sol thinking — locally by default, or on your own provider key if you'd rather use a cloud lane.

see [INSTALL.md](INSTALL.md) for prerequisites, observer install, and troubleshooting; see [CONTRIBUTING.md](CONTRIBUTING.md) if you want to develop on solstone from a source checkout.

## CLI

solstone is operated through `sol` for day-to-day journal access and `journal` for host operations.

```bash
sol                    # Status overview and command list
journal supervisor         # Start the full stack (observe + processing + web)
sol chat               # Interactive AI chat from the terminal
journal transcribe <file>  # Transcribe an audio file
journal indexer            # Rebuild the search index
```

Run `sol help` for the full command reference.

## documentation

| Topic | Document |
|-------|----------|
| Installation and setup | [INSTALL.md](INSTALL.md) |
| Developing from source | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Journal structure and data model | [solstone/talent/journal/SKILL.md](solstone/talent/journal/SKILL.md) |
| Observe pipeline | [docs/OBSERVE.md](docs/OBSERVE.md) |
| Processing and agents | [docs/THINK.md](docs/THINK.md) |
| Web interface | [docs/CONVEY.md](docs/CONVEY.md) |
| App development | [docs/APPS.md](docs/APPS.md) |
| Agent runtime | [docs/CORTEX.md](docs/CORTEX.md) |
| Message bus | [docs/CALLOSUM.md](docs/CALLOSUM.md) |
| AI provider configuration | [docs/PROVIDERS.md](docs/PROVIDERS.md) |
| What solstone sends to your AI provider | [DATA-FLOW.md](DATA-FLOW.md) |
| Troubleshooting | [docs/DOCTOR.md](docs/DOCTOR.md) |
| Project direction | [docs/ROADMAP.md](docs/ROADMAP.md) |

## development

See [AGENTS.md](AGENTS.md) for development guidelines, coding standards, and testing instructions.

Use `make dev` to run the full stack against test fixtures, focused test targets
during development, and `make ci` on the final tree before merge or release.

## feedback

Questions, feedback, or a bug? **Follow and tag [@solstone.app](https://bsky.app/profile/solstone.app) on Bluesky** for discussion and updates, open an issue at [github.com/solpbc/solstone-journal/issues](https://github.com/solpbc/solstone-journal/issues) for bugs, or reach support at [support.solstone.app](https://support.solstone.app). You don't need to know anyone — those are the front doors.

## contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.

## license

AGPL-3.0-only. See [LICENSE](LICENSE) for details.
Bundled third-party model notices: [solstone/THIRD_PARTY_NOTICES.md](solstone/THIRD_PARTY_NOTICES.md).
Maintained by [sol pbc](https://solpbc.org).
