personal memory agent
Simplify INSTALL.md — let convey onboarding handle config
Removed the manual config-writing section entirely — convey's
first-run wizard handles password, identity, and API key setup.
Prerequisites simplified to just git + uv (Makefile handles the
rest). Observer install defers to observer repo INSTALL.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+17
-123
+17
-123
INSTALL.md
+17
-123
INSTALL.md
···
2
2
3
3
these instructions are for a coding agent and human working together. solstone is an AI life journal — it captures everything you see and hear on your computer, processes it with AI, and gives you superhuman memory. open source, made by sol pbc.
4
4
5
-
your data resides on your computer. sol pbc is a public benefit corporation with irrevocable legal covenants: your data can never be sold, the company can never be acquired. the code is open source — you can verify every claim.
6
-
7
5
**supported platforms:** linux (primary), macOS. windows is not yet supported.
8
6
9
7
the latest version of these instructions is at https://solstone.app/install
···
13
11
check if solstone is already installed and running:
14
12
15
13
```bash
16
-
sol --version 2>&1 && sol service status 2>&1 && sol health 2>&1
14
+
sol --version 2>&1 && sol service status 2>&1
17
15
```
18
16
19
17
if `sol` isn't found, try `~/.local/bin/sol`. if solstone is running and healthy, skip to [install an observer](#install-an-observer).
20
18
21
-
## what to sort out together
22
-
23
-
- **a Google AI Studio API key.** required for transcription and vision processing. the human needs to go to https://aistudio.google.com/apikey, sign in, and create one.
24
-
- **a password for the web interface.** protects the journal's web UI on localhost. any password they'll remember.
25
-
- **system dependencies.** some packages require sudo — if you don't have it, walk your human through the install commands.
19
+
## prerequisites
26
20
27
-
## platform prerequisites
28
-
29
-
detect the platform:
30
-
31
-
```bash
32
-
uname -s
33
-
```
21
+
the only hard requirement is `uv` — the Makefile checks for it and errors with install instructions if missing.
34
22
35
23
### linux
36
24
37
-
check what's already installed:
38
-
39
25
```bash
40
-
python3 --version 2>&1; git --version 2>&1; ffmpeg -version 2>&1 | head -1; uv --version 2>&1
41
-
```
42
-
43
-
you need python 3.10+, git, ffmpeg, and uv. install anything that's missing.
44
-
45
-
**fedora / rhel:**
46
-
```bash
47
-
sudo dnf install python3 git ffmpeg
48
-
```
49
-
50
-
**debian / ubuntu:**
51
-
```bash
52
-
sudo apt install python3 git ffmpeg
53
-
```
54
-
55
-
**arch:**
56
-
```bash
57
-
sudo pacman -S python git ffmpeg
26
+
git --version 2>&1; uv --version 2>&1
58
27
```
59
28
60
-
install uv if not present:
61
-
29
+
if git is missing, install it via your distro's package manager. install uv if not present:
62
30
```bash
63
31
curl -LsSf https://astral.sh/uv/install.sh | sh
64
32
```
65
-
66
-
uv installs to `~/.local/bin/uv` or `~/.cargo/bin/uv`. it may not be in PATH yet — call it by full path if needed.
67
33
68
34
### macOS
69
35
70
-
several of these steps require human interaction — password prompts, app store installs, and dialogs the agent can't click through.
36
+
your human may need to handle interactive steps here — app store installs and password prompts.
71
37
72
-
**Xcode:** the macOS observer requires the full Xcode IDE (not just command line tools). your human needs to install it from the Mac App Store if they haven't already. then install command line tools:
38
+
**Xcode:** required for the macOS observer. check with `xcodebuild -version`. if missing, the human installs from the Mac App Store, then: `xcode-select --install`
73
39
74
-
```bash
75
-
xcode-select --install
76
-
```
77
-
78
-
**homebrew:** check if installed with `brew --version`. if not, the human needs to install it from https://brew.sh (requires their password).
40
+
**homebrew:** check with `brew --version`. if missing, the human installs from https://brew.sh.
79
41
80
42
```bash
81
-
brew install python git ffmpeg uv
82
-
```
83
-
84
-
### verify
85
-
86
-
```bash
87
-
python3 --version && git --version && ffmpeg -version 2>&1 | head -1 && uv --version
43
+
brew install git uv
88
44
```
89
45
90
-
all should produce version output. python must be 3.10+.
91
-
92
46
## install
93
47
94
48
```bash
95
49
make install
96
50
```
97
51
98
-
`make install` creates a python virtual environment, installs dependencies, and symlinks `sol` to `~/.local/bin/sol`.
99
-
100
-
verify:
101
-
102
-
```bash
103
-
.venv/bin/sol --help
104
-
```
105
-
106
-
if `sol` is not in PATH, use `.venv/bin/sol` for the remaining steps. the human can add `~/.local/bin` to their shell profile's PATH to fix this permanently.
107
-
108
-
## configure
109
-
110
-
collect the API key and password from your human, then write the config:
111
-
112
-
```bash
113
-
mkdir -p journal/config
114
-
```
115
-
116
-
write `journal/config/journal.json`:
52
+
sets up the python environment, installs all dependencies, and symlinks `sol` to `~/.local/bin/sol`.
117
53
118
-
```json
119
-
{
120
-
"convey": {
121
-
"password": "THE_PASSWORD_THEY_CHOSE"
122
-
},
123
-
"env": {
124
-
"GOOGLE_API_KEY": "THE_GEMINI_KEY_THEY_PROVIDED"
125
-
}
126
-
}
127
-
```
128
-
129
-
if you have access to an API key for your own platform, you can also add it so solstone can use your provider for chat and agent features — confirm with your human before adding:
130
-
131
-
- claude code / anthropic: add `"ANTHROPIC_API_KEY"` to the `env` section
132
-
- codex / openai: add `"OPENAI_API_KEY"` to the `env` section
133
-
134
-
lock down the config — it contains secrets:
135
-
136
-
```bash
137
-
chmod 600 journal/config/journal.json
138
-
```
54
+
if `sol` isn't in PATH after install, use `.venv/bin/sol` — the human can add `~/.local/bin` to their shell profile later.
139
55
140
56
## start solstone
141
57
···
143
59
make install-service
144
60
```
145
61
146
-
this installs, enables, and starts a background service (systemd on linux, launchd on macOS) with the web interface on port 5015.
147
-
148
-
verify:
149
-
150
-
```bash
151
-
sol service status
152
-
sol health
153
-
```
62
+
starts a background service (systemd on linux, launchd on macOS) with the web interface on port 5015.
154
63
155
-
the web interface should be available at `http://localhost:5015`.
64
+
let your human know: **open http://localhost:5015 in a browser.** the first-run setup wizard walks them through choosing a password, setting their identity, and connecting a Gemini API key. once they've completed it, solstone is configured and ready.
156
65
157
-
if the service fails to start, check the logs with `sol service logs`. common causes: missing or invalid API key, missing system dependencies, permission issues.
66
+
if the service fails to start, check `sol service logs`.
158
67
159
68
## install an observer
160
69
161
-
solstone doesn't capture anything on its own — it needs an observer for the platform. detect which one to install:
70
+
solstone doesn't capture anything on its own — it needs an observer for the platform.
162
71
163
72
```bash
164
73
uname -s
165
74
```
166
75
167
-
- **Linux** — solstone-linux (screen + audio via PipeWire/GStreamer)
168
-
- **Darwin** — solstone-macos (native swift menu bar app)
169
-
170
76
clone the observer into solstone's observers directory and follow its INSTALL.md:
171
77
172
78
```bash
···
185
91
```
186
92
then read `solstone-macos/INSTALL.md` and follow it.
187
93
188
-
## hand off to the human
189
-
190
-
solstone and its observer are installed and running. let your human know:
191
-
192
-
1. **solstone runs as a background service** that starts automatically on login. manage it with:
193
-
- `sol service status` — check if running
194
-
- `sol service restart` — restart
195
-
- `sol service stop` — stop
196
-
- `sol service logs -f` — follow logs
197
-
198
-
2. **the web interface** is at `http://localhost:5015`. log in with the password they chose.
199
-
200
-
3. **after logging in**, they should go to Settings (gear icon) and fill in their identity — name, preferred name, pronouns, timezone. this helps solstone identify them in transcripts and personalize AI responses.
94
+
## done
201
95
202
-
4. **what solstone does from here:** it captures screen and audio continuously, transcribes conversations, extracts people and projects, builds a knowledge graph, and makes everything searchable. all data stays in `journal/` directories — one per day.
96
+
once the observer is running, solstone captures screen and audio continuously, transcribes conversations, extracts people and projects, builds a knowledge graph, and makes everything searchable at http://localhost:5015. all data stays in `journal/` directories — one per day.
203
97
204
98
source code: https://github.com/solpbc/solstone
205
99
company: https://solpbc.org