personal memory agent
Add INSTALL.md for agent-human collaborative setup
Full installation guide written for a coding agent working with
a human. Surfaces collaborative decisions (install location, API
key, password), defers observer install to observer repo INSTALL.md
files via sol root/observers, includes idempotency check.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+205
+205
INSTALL.md
+205
INSTALL.md
···
1
+
# installing solstone
2
+
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
+
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
+
**supported platforms:** linux (primary), macOS. windows is not yet supported.
8
+
9
+
the latest version of these instructions is at https://solstone.app/install
10
+
11
+
## before you begin
12
+
13
+
check if solstone is already installed and running:
14
+
15
+
```bash
16
+
sol --version 2>&1 && sol service status 2>&1 && sol health 2>&1
17
+
```
18
+
19
+
if `sol` isn't found, try `~/.local/bin/sol`. if solstone is running and healthy, skip to [install an observer](#install-an-observer).
20
+
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.
26
+
27
+
## platform prerequisites
28
+
29
+
detect the platform:
30
+
31
+
```bash
32
+
uname -s
33
+
```
34
+
35
+
### linux
36
+
37
+
check what's already installed:
38
+
39
+
```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
58
+
```
59
+
60
+
install uv if not present:
61
+
62
+
```bash
63
+
curl -LsSf https://astral.sh/uv/install.sh | sh
64
+
```
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
+
68
+
### macOS
69
+
70
+
several of these steps require human interaction — password prompts, app store installs, and dialogs the agent can't click through.
71
+
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:
73
+
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).
79
+
80
+
```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
88
+
```
89
+
90
+
all should produce version output. python must be 3.10+.
91
+
92
+
## install
93
+
94
+
```bash
95
+
make install
96
+
```
97
+
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`:
117
+
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
+
```
139
+
140
+
## start solstone
141
+
142
+
```bash
143
+
make install-service
144
+
```
145
+
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
+
```
154
+
155
+
the web interface should be available at `http://localhost:5015`.
156
+
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.
158
+
159
+
## install an observer
160
+
161
+
solstone doesn't capture anything on its own — it needs an observer for the platform. detect which one to install:
162
+
163
+
```bash
164
+
uname -s
165
+
```
166
+
167
+
- **Linux** — solstone-linux (screen + audio via PipeWire/GStreamer)
168
+
- **Darwin** — solstone-macos (native swift menu bar app)
169
+
170
+
clone the observer into solstone's observers directory and follow its INSTALL.md:
171
+
172
+
```bash
173
+
cd "$(sol root)/observers"
174
+
```
175
+
176
+
**linux:**
177
+
```bash
178
+
git clone https://github.com/solpbc/solstone-linux.git
179
+
```
180
+
then read `solstone-linux/INSTALL.md` and follow it.
181
+
182
+
**macOS:**
183
+
```bash
184
+
git clone https://github.com/solpbc/solstone-macos.git
185
+
```
186
+
then read `solstone-macos/INSTALL.md` and follow it.
187
+
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.
201
+
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.
203
+
204
+
source code: https://github.com/solpbc/solstone
205
+
company: https://solpbc.org