personal memory agent
Rewrite README to represent solstone's full scope and capabilities
Replace the 65-line generic boilerplate with a comprehensive project page
covering architecture (observe/think/convey pipeline with callosum and
cortex), 17 web apps, 30 agent configs, and local-first data ownership.
Add home dashboard and transcript viewer screenshots. Align pyproject.toml
description to canonical tagline.
+100
-31
+99
-30
README.md
+99
-30
README.md
···
4
4
5
5
Navigate Life Intelligently
6
6
7
-
solstone is an open source project maintained by [sol pbc](https://solpbc.org).
7
+
solstone is an open-source, local-first AI journaling toolkit. It captures screen and audio activity, processes it with AI agents, and presents everything through a searchable web interface. All data stays on your machine in daily journal directories — no cloud, no subscriptions, full ownership.
8
+
9
+
Python 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
+
*The daily dashboard with facet tabs, daily goal, todos, upcoming events, and detected entities.*
14
+
15
+
## Architecture
16
+
17
+
```text
18
+
+---------+ +----------------+ +---------+
19
+
| observe | ----> | journal | ----> | think |
20
+
| capture | | YYYYMMDD/ dirs | | process |
21
+
+---------+ | media, jsonl, | | index |
22
+
| entities | +----+----+
23
+
+-------+--------+ |
24
+
^ |
25
+
| agent outputs |
26
+
+----+----+ |
27
+
| cortex | <--------------+
28
+
| agents |
29
+
+---------+
30
+
|
31
+
==== callosum (event bus) | ==========================
32
+
|
33
+
+------+------+
34
+
| convey |
35
+
| web UI |
36
+
+-------------+
37
+
```
38
+
39
+
- **observe** — Captures audio (PipeWire on Linux, sck-cli on macOS) and screen activity. Produces FLAC audio, WebM screen recordings, and timestamped metadata.
40
+
- **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/`.
41
+
- **cortex** — Orchestrates agent execution. Receives events, dispatches agents, writes results back to the journal.
42
+
- **callosum** — Async message bus connecting all services. Enables event-driven coordination between observe, think, cortex, and convey.
43
+
- **convey** — Flask-based web interface with 17 pluggable apps for navigating journal data.
44
+
- **journal** — `JOURNAL_PATH/YYYYMMDD/` daily directories. The single source of truth — transcripts, media, entities, agent outputs, and the SQLite index all live here.
8
45
9
-
A Python-based desktop journaling toolkit that captures screen and audio activity, processes it with AI, and provides intelligent navigation through a web interface. All data is organized in a local journal directory with daily folders, enabling temporal analysis and full ownership of your information.
46
+
## Key Features
10
47
11
-
## Platform Support
48
+
- **Multimodal capture** — Continuous audio recording with voice activity detection, plus periodic screen capture with AI-powered categorization.
49
+
- **Transcription and speaker identification** — faster-whisper transcription with voice embeddings (resemblyzer) for speaker diarization.
50
+
- **Entity extraction** — People, projects, and concepts extracted from transcripts and tracked across time.
51
+
- **Facet organization** — Group content by project or context (e.g., work, personal, client-name) with scoped views across all apps.
52
+
- **AI agents** — 30 agent configurations for activities, meetings, scheduling, knowledge graphs, research, media analysis, and more. Extensible via the agent skill framework.
53
+
- **Searchable index** — Full-text search across transcripts, entities, and agent outputs via SQLite.
54
+
- **Local-first** — All data in daily journal directories on your filesystem. No cloud dependency. Configurable AI providers (Google Gemini, OpenAI, Anthropic).
12
55
13
-
- Linux
14
-
- macOS
56
+
## Web Interface
57
+
58
+
Convey currently includes 17 discoverable apps for browsing, operating, and maintaining your journal.
59
+
60
+
<img src="docs/static/screenshot-transcripts.png" alt="solstone transcript viewer" width="800">
61
+
62
+
- Daily dashboard, calendar, and scheduling.
63
+
- Transcript browser with dual-timeline navigation.
64
+
- AI chat with configurable providers.
65
+
- Entity tracking, search, and statistics.
66
+
- Speaker identification and management.
67
+
- Health monitoring, token usage, and system settings.
68
+
69
+
## Quick Start
15
70
16
-
## Key Capabilities
71
+
```bash
72
+
git clone https://github.com/solpbc/solstone.git
73
+
cd solstone
74
+
make install
17
75
18
-
- **Multimodal Capture** - Screen recording and audio capture with automatic segmentation
19
-
- **AI Transcription** - Audio transcription with faster-whisper and voice embeddings
20
-
- **Visual Analysis** - AI-powered screen content categorization and extraction
21
-
- **Intelligent Insights** - Automated daily summaries, meeting detection, and entity extraction
22
-
- **Facet Organization** - Group content by project or context (work, personal, etc.)
23
-
- **Web Interface** - Review transcripts, calendar views, entity tracking, and AI chat
24
-
- **Agent System** - Extensible AI agents with callable tool workflows
76
+
# Configure environment
77
+
cp .env.example .env
78
+
# Add at minimum: GOOGLE_API_KEY=your-key
79
+
# See docs/PROVIDERS.md for all supported providers
25
80
26
-
## Architecture
81
+
# Start the full stack
82
+
sol supervisor
27
83
28
-
```
29
-
observe (capture) --> think (analyze) --> convey (view)
30
-
| | |
31
-
raw media JSON extracts Flask web UI
32
-
(flac, webm) (jsonl)
33
-
|
34
-
think (AI agents)
84
+
# Open the web interface
85
+
# (prints URL on startup, default http://localhost:<port>)
35
86
```
36
87
37
-
## Getting Started
88
+
See [docs/INSTALL.md](docs/INSTALL.md) for platform-specific dependencies, detailed configuration, and first-run guidance.
38
89
39
-
See **[docs/INSTALL.md](docs/INSTALL.md)** for complete setup instructions including system dependencies, API keys, and first-run configuration.
90
+
## CLI
91
+
92
+
solstone is operated through the unified `sol` command (33 subcommands).
93
+
94
+
```bash
95
+
sol # Status overview and command list
96
+
sol supervisor # Start the full stack (capture + processing + web)
97
+
sol chat # Interactive AI chat from the terminal
98
+
sol transcribe <file> # Transcribe an audio file
99
+
sol indexer # Rebuild the search index
100
+
sol screenshot / # Capture a screenshot of the web UI
101
+
```
102
+
103
+
Run `sol help` for the full command reference.
40
104
41
105
## Documentation
42
106
43
107
| Topic | Document |
44
108
|-------|----------|
45
-
| **Installation and setup** | [docs/INSTALL.md](docs/INSTALL.md) |
46
-
| Journal structure and data formats | [docs/JOURNAL.md](docs/JOURNAL.md) |
47
-
| Capture and observation | [docs/OBSERVE.md](docs/OBSERVE.md) |
48
-
| Processing and insights | [docs/THINK.md](docs/THINK.md) |
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) |
49
113
| Web interface | [docs/CONVEY.md](docs/CONVEY.md) |
50
114
| App development | [docs/APPS.md](docs/APPS.md) |
51
-
| AI agents and Cortex | [docs/CORTEX.md](docs/CORTEX.md) |
52
-
| Message bus protocol | [docs/CALLOSUM.md](docs/CALLOSUM.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) |
53
118
| Troubleshooting | [docs/DOCTOR.md](docs/DOCTOR.md) |
119
+
| Project direction | [docs/ROADMAP.md](docs/ROADMAP.md) |
54
120
55
121
## Development
56
122
57
123
See [AGENTS.md](AGENTS.md) for development guidelines, coding standards, and testing instructions.
58
124
125
+
Use `make dev` to run the full stack against test fixtures, `make ci` for pre-commit checks, and `sol screenshot` for UI testing workflows.
126
+
59
127
## Contributing
60
128
61
129
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.
62
130
63
131
## License
64
132
65
-
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See [LICENSE](LICENSE) for details.
133
+
AGPL-3.0-only. See [LICENSE](LICENSE) for details.
134
+
Maintained by [sol pbc](https://solpbc.org).
docs/static/screenshot-home.png
docs/static/screenshot-home.png
This is a binary file and will not be displayed.
docs/static/screenshot-transcripts.png
docs/static/screenshot-transcripts.png
This is a binary file and will not be displayed.
+1
-1
pyproject.toml
+1
-1
pyproject.toml
···
5
5
[project]
6
6
name = "solstone"
7
7
version = "0.1.0"
8
-
description = "Navigate Intelligently - A collection of utilities for multimodal navigation and analysis"
8
+
description = "Navigate Life Intelligently"
9
9
readme = "README.md"
10
10
requires-python = ">=3.10"
11
11
license = {text = "AGPL-3.0-only"}