# 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).
*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.
*Transcript viewer — dual-timeline navigation, speaker-diarized dialogue, audio playback, screen analysis. every conversation browsable by time.*
*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 # 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).