personal memory agent
1<img src="docs/static/sol-wordmark.svg" alt="solstone" width="300">
2
3# solstone
4
5your co-brain — captures everything you see and hear, processes it with AI, and gives you superhuman memory.
6
7solstone runs in the background on your computer, recording audio and screen activity. AI agents transcribe, extract entities, detect meetings, build knowledge graphs, and surface daily insights — all without any manual input. everything stays on your machine in daily journal directories. open source, local-first, no cloud required.
8
9Python 3.10+, Linux + macOS, AGPL-3.0-only, maintained by [sol pbc](https://solpbc.org).
10
11<img src="docs/static/screenshot-home.png" alt="solstone daily dashboard" width="800">
12
13*Daily dashboard — goal, todos, upcoming events, and detected entities, all generated from passive capture. Facet tabs organize your life by project or context.*
14
15## what you get
16
17**a system of intelligence, not just a system of record.**
18
19- **automatic transcription** — continuous audio capture (via standalone observers) with speaker identification. every conversation, transcribed and searchable.
20- **entity tracking** — people, companies, and projects extracted from your conversations and tracked across time.
21- **knowledge graphs** — relationships between entities mapped automatically. who works with whom, which projects connect to which people.
22- **meeting detection** — meetings identified, summarized, and linked. meeting prep that surfaces what you discussed last time and personal context you'd forget.
23- **commitment tracking** — todos captured from natural conversation. no manual entry.
24- **facet organization** — group everything by project or context (work, personal, client-name) with scoped views across all apps.
25- **AI chat** — talk to your journal. ask anything about your digital life and get answers grounded in your actual data.
26- **full-text search** — find anything you've ever seen or heard.
27- **30 AI agents** — configurable workflows for activities, scheduling, research, media analysis, and more. extensible via the agent skill framework.
28- **local-first** — all data in daily journal directories on your filesystem. configurable AI providers (Google Gemini, OpenAI, Anthropic). no cloud dependency.
29
30<img src="docs/static/screenshot-transcripts.png" alt="solstone transcript viewer" width="800">
31
32*Transcript viewer — dual-timeline navigation, speaker-diarized dialogue, audio playback, screen capture analysis. every conversation browsable by time.*
33
34<img src="docs/static/screenshot-entities.png" alt="solstone entity tracking" width="800">
35
36*Entity tracking — people, companies, and projects automatically extracted and tracked across your journal with mention counts and relationship data.*
37
38## architecture
39
40```text
41 +---------+ +----------------+ +---------+
42 | observe | ----> | journal | ----> | think |
43 | capture | | YYYYMMDD/ dirs | | process |
44 +---------+ | media, jsonl, | | index |
45 | entities | +----+----+
46 +-------+--------+ |
47 ^ |
48 | agent outputs |
49 +----+----+ |
50 | cortex | <--------------+
51 | agents |
52 +---------+
53 |
54 ==== callosum (event bus) | ==========================
55 |
56 +------+------+
57 | convey |
58 | web UI |
59 +-------------+
60```
61
62- **observe** — receives captured audio and screen activity from standalone observers (solstone-linux, solstone-tmux, solstone-macos) via remote ingest. processes FLAC audio, WebM screen recordings, and timestamped metadata.
63- **think** — transcribes audio (faster-whisper), analyzes screen captures, extracts entities, detects meetings, and indexes everything into SQLite. runs 30 configurable agent/generator templates from `muse/`.
64- **cortex** — orchestrates agent execution. receives events, dispatches agents, writes results back to the journal.
65- **callosum** — async message bus connecting all services. enables event-driven coordination between observe, think, cortex, and convey.
66- **convey** — Flask-based web interface with 17 pluggable apps for navigating journal data.
67- **journal** — `journal/YYYYMMDD/` daily directories. the single source of truth — transcripts, media, entities, agent outputs, and the SQLite index all live here.
68
69## quick start
70
71```bash
72git clone https://github.com/solpbc/solstone.git
73cd solstone
74make install
75
76# Configure environment
77cp .env.example .env
78# Add at minimum: GOOGLE_API_KEY=your-key
79# See docs/PROVIDERS.md for all supported providers
80
81# Install as a background service (starts on login, port 5015)
82make install-service
83
84# Or start manually for development
85sol supervisor
86```
87
88See [docs/INSTALL.md](docs/INSTALL.md) for platform-specific dependencies, detailed configuration, and first-run guidance.
89
90## CLI
91
92solstone is operated through the unified `sol` command (33 subcommands).
93
94```bash
95sol # Status overview and command list
96sol supervisor # Start the full stack (capture + processing + web)
97sol chat # Interactive AI chat from the terminal
98sol transcribe <file> # Transcribe an audio file
99sol indexer # Rebuild the search index
100sol screenshot / # Capture a screenshot of the web UI
101```
102
103Run `sol help` for the full command reference.
104
105## documentation
106
107| Topic | Document |
108|-------|----------|
109| Installation and setup | [docs/INSTALL.md](docs/INSTALL.md) |
110| Journal structure and data model | [docs/JOURNAL.md](docs/JOURNAL.md) |
111| Capture pipeline | [docs/OBSERVE.md](docs/OBSERVE.md) |
112| Processing and agents | [docs/THINK.md](docs/THINK.md) |
113| Web interface | [docs/CONVEY.md](docs/CONVEY.md) |
114| App development | [docs/APPS.md](docs/APPS.md) |
115| Agent runtime | [docs/CORTEX.md](docs/CORTEX.md) |
116| Message bus | [docs/CALLOSUM.md](docs/CALLOSUM.md) |
117| AI provider configuration | [docs/PROVIDERS.md](docs/PROVIDERS.md) |
118| Troubleshooting | [docs/DOCTOR.md](docs/DOCTOR.md) |
119| Project direction | [docs/ROADMAP.md](docs/ROADMAP.md) |
120
121## development
122
123See [AGENTS.md](AGENTS.md) for development guidelines, coding standards, and testing instructions.
124
125Use `make dev` to run the full stack against test fixtures, `make ci` for pre-commit checks, and `sol screenshot` for UI testing workflows.
126
127## contributing
128
129See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.
130
131## license
132
133AGPL-3.0-only. See [LICENSE](LICENSE) for details.
134Maintained by [sol pbc](https://solpbc.org).