personal memory agent
1# Installation Guide
2
3Complete setup instructions for solstone on Linux and macOS.
4
5## Prerequisites
6
7- Python 3.10 or later
8- [uv](https://docs.astral.sh/uv/) (Python package manager)
9- Git
10- ffmpeg (for audio processing)
11
12### Linux (Fedora/RHEL)
13
14```bash
15sudo dnf install python3 git ffmpeg pipewire gstreamer1-plugins-base gstreamer1-plugin-pipewire pulseaudio-utils
16curl -LsSf https://astral.sh/uv/install.sh | sh
17```
18
19### Linux (Ubuntu/Debian)
20
21```bash
22sudo apt install python3 git ffmpeg pipewire gstreamer1.0-tools gstreamer1.0-pipewire pulseaudio-utils
23curl -LsSf https://astral.sh/uv/install.sh | sh
24```
25
26### Linux (Arch)
27
28```bash
29sudo pacman -S python git ffmpeg pipewire gstreamer gst-plugin-pipewire libpulse
30curl -LsSf https://astral.sh/uv/install.sh | sh
31```
32
33### macOS
34
35```bash
36xcode-select --install # Command line tools
37brew install python git ffmpeg uv
38```
39
40---
41
42## Installation
43
441. Clone and install:
45
46```bash
47git clone https://github.com/solpbc/solstone.git
48cd solstone
49make install
50```
51
52This creates an isolated virtual environment in `.venv/` for local development. Your system Python remains untouched, and no user-level CLI alias or service is installed yet.
53
54To remove installed user/system artifacts:
55
56```bash
57make uninstall-service
58```
59
60To reset the repo-local development environment:
61
62```bash
63make clean-install
64```
65
662. Your journal lives at `journal/` inside the solstone directory. It's created automatically on first run.
67
68---
69
70## API Keys
71
72solstone requires API keys for AI services. All keys are configured in `journal/config/journal.json` — this is the only key configuration method.
73
74Create the config file:
75
76```bash
77mkdir -p journal/config
78cat > journal/config/journal.json << 'EOF'
79{
80 "convey": {},
81 "env": {
82 "GOOGLE_API_KEY": "your-key-here"
83 }
84}
85EOF
86chmod 600 journal/config/journal.json
87```
88
89Run `sol password set` to configure web authentication. Replace `your-key-here` with your Google AI API key.
90
91### Google AI (Gemini) - Required
92
93Primary backend for transcription, vision analysis, and insights.
94
951. Go to [Google AI Studio](https://aistudio.google.com/apikey)
962. Sign in with your Google account
973. Click "Create API Key"
984. Add the key to the `env` section of `journal/config/journal.json`
99
100### OpenAI (Optional)
101
102Alternative backend for chat and agents. Add `"OPENAI_API_KEY": "your-key"` to the `env` section.
103
104### Anthropic (Optional)
105
106Alternative backend for chat and agents. Add `"ANTHROPIC_API_KEY": "your-key"` to the `env` section.
107
108### Rev.ai for Imports (Optional)
109
110For transcribing imported audio files. Sign up at [Rev.ai](https://www.rev.ai/), get a token from [Access Token](https://www.rev.ai/access_token), and add `"REVAI_ACCESS_TOKEN": "your-token"` to the `env` section.
111
112### Example with multiple providers
113
114```json
115{
116 "convey": {},
117 "env": {
118 "GOOGLE_API_KEY": "your-gemini-key",
119 "OPENAI_API_KEY": "your-openai-key",
120 "ANTHROPIC_API_KEY": "your-anthropic-key"
121 }
122}
123```
124
125**Important:** `journal.json` contains your API keys and credentials. It should always have restricted permissions (`chmod 600`).
126
127---
128
129## First Run
130
131### Install as a Background Service
132
133The recommended way to run solstone is as a system service that starts automatically on login:
134
135```bash
136make install-service
137```
138
139This creates or refreshes the `~/.local/bin/sol` alias, installs the global `solstone` skill for claude-code, and installs, enables, and starts a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. Re-running it upgrades an existing install instead of conflicting. To use a custom port:
140
141```bash
142make install-service PORT=8000
143```
144
145Manage the service with:
146
147```bash
148sol service status # Check if running
149sol service restart # Restart
150sol service stop # Stop
151sol service logs -f # Follow logs
152sol up # Install + start (if not already)
153sol down # Stop
154```
155
156### Start Manually (Development)
157
158For development, run the supervisor directly in a terminal:
159
160```bash
161sol supervisor # Auto-selects an available port
162sol supervisor 8000 # Use a specific port
163```
164
165This starts:
166- **Sense** - File detection and processing dispatch
167- **Callosum** - Message bus for inter-service communication
168- **Cortex** - Agent execution
169
170### Verify Services
171
172Check that services are running:
173
174```bash
175sol health
176```
177
178---
179
180## Web Interface
181
182### Access the Interface
183
184Open the Convey URL shown in the terminal (port is dynamically assigned) and log in with your password.
185
186### Configure Your Identity
187
188After logging in:
189
1901. Click the **Settings** app in the left menu (gear icon)
1912. Fill in your identity information:
192 - **Full Name** - Your legal name
193 - **Preferred Name** - How you want to be addressed
194 - **Pronouns** - Select from dropdown
195 - **Timezone** - Auto-detected, adjust if needed
196
197This helps the system identify you in transcripts and personalize AI responses.
198
199---
200
201## Health Check
202
203Verify everything is working:
204
205```bash
206# Check services are running
207pgrep -af "sol:sense|sol:supervisor"
208
209# Check Callosum socket exists
210ls -la journal/health/callosum.sock
211
212# View service logs
213tail -f journal/health/*.log
214```
215
216See [DOCTOR.md](DOCTOR.md) for troubleshooting.
217
218---
219
220## Observers
221
222Observers capture screen and audio and upload to the solstone server. Each platform has its own standalone observer. Packages are not yet on PyPI — install from source.
223
224### Linux Observer
225
226```bash
227git clone https://github.com/solpbc/solstone-linux.git
228cd solstone-linux
229pipx install --system-site-packages .
230solstone-linux setup
231solstone-linux install-service
232```
233
234`--system-site-packages` is required for PyGObject/GStreamer access.
235
236**Note:** Activity detection (idle, lock, power save) requires GNOME desktop. Other desktops: capture works but activity-based segment boundaries won't trigger.
237
238### tmux Observer
239
240```bash
241git clone https://github.com/solpbc/solstone-tmux.git
242cd solstone-tmux
243pipx install .
244solstone-tmux setup
245solstone-tmux install-service
246```
247
248### macOS Observer
249
250See [solstone-macos](https://github.com/solpbc/solstone-macos) — requires Xcode (full IDE, not just CLI tools).
251
252---
253
254## Next Steps
255
256- Create your first facet (project/context) in the web interface
257- Review captured content in the Calendar and Transcripts apps
258- Chat with the AI about your journal content
259
260For development setup, see [AGENTS.md](../AGENTS.md).