personal memory agent
1# Installation Guide
2
3Complete setup instructions for solstone on Linux and macOS.
4
5## Prerequisites
6
7- Python 3.11 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 later:
55
56```bash
57sol service stop
58sol service uninstall
59sol skills uninstall
60python -m think.install_guard uninstall
61```
62
63To reset the repo-local development environment:
64
65```bash
66make clean-install
67```
68
692. Your journal lives at `journal/` inside the solstone directory. It's created automatically on first run.
70
71---
72
73## API Keys
74
75solstone requires API keys for AI services. All keys are configured in `journal/config/journal.json` — this is the only key configuration method.
76
77Create the config file:
78
79```bash
80mkdir -p journal/config
81cat > journal/config/journal.json << 'EOF'
82{
83 "convey": {},
84 "env": {
85 "GOOGLE_API_KEY": "your-key-here"
86 }
87}
88EOF
89chmod 600 journal/config/journal.json
90```
91
92Run `sol password set` to configure web authentication. Replace `your-key-here` with your Google AI API key.
93
94### Google AI (Gemini) - Required
95
96Primary backend for transcription, vision analysis, and insights.
97
981. Go to [Google AI Studio](https://aistudio.google.com/apikey)
992. Sign in with your Google account
1003. Click "Create API Key"
1014. Add the key to the `env` section of `journal/config/journal.json`
102
103### OpenAI (Optional)
104
105Alternative backend for chat and agents. Add `"OPENAI_API_KEY": "your-key"` to the `env` section.
106
107### Anthropic (Optional)
108
109Alternative backend for chat and agents. Add `"ANTHROPIC_API_KEY": "your-key"` to the `env` section.
110
111### Rev.ai for Imports (Optional)
112
113For 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.
114
115### Example with multiple providers
116
117```json
118{
119 "convey": {},
120 "env": {
121 "GOOGLE_API_KEY": "your-gemini-key",
122 "OPENAI_API_KEY": "your-openai-key",
123 "ANTHROPIC_API_KEY": "your-anthropic-key"
124 }
125}
126```
127
128**Important:** `journal.json` contains your API keys and credentials. It should always have restricted permissions (`chmod 600`).
129
130---
131
132## First Run
133
134### Install as a Background Service
135
136The recommended way to run solstone is through setup, which installs the runtime artifacts and starts the service:
137
138```bash
139.venv/bin/sol setup
140```
141
142This creates or refreshes the `~/.local/bin/sol` wrapper for source-checkout installs, installs the global `solstone` skill for Claude Code when Claude is configured, and installs, enables, and starts a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. After the first run, the wrapper at `~/.local/bin/sol` lets you use just `sol` from anywhere. Service installation runs only on source-checkout installs in v1; packaged installs skip the service step. Re-running it is safe. To use a custom port on the first run:
143
144```bash
145.venv/bin/sol setup --port 8000
146```
147
148Manage the service with:
149
150```bash
151sol service status # Check if running
152sol service restart # Restart
153sol service stop # Stop
154sol service logs -f # Follow logs
155sol up # Install + start (if not already)
156sol down # Stop
157```
158
159### Start Manually (Development)
160
161For development, run the supervisor directly in a terminal:
162
163```bash
164sol supervisor # Auto-selects an available port
165sol supervisor 8000 # Use a specific port
166```
167
168This starts:
169- **Sense** - File detection and processing dispatch
170- **Callosum** - Message bus for inter-service communication
171- **Cortex** - Agent execution
172
173### Verify Services
174
175Check that services are running:
176
177```bash
178sol health
179```
180
181---
182
183## Web Interface
184
185### Access the Interface
186
187Open the Convey URL shown in the terminal (port is dynamically assigned) and log in with your password.
188
189### Configure Your Identity
190
191After logging in:
192
1931. Click the **Settings** app in the left menu (gear icon)
1942. Fill in your identity information:
195 - **Full Name** - Your legal name
196 - **Preferred Name** - How you want to be addressed
197 - **Pronouns** - Select from dropdown
198 - **Timezone** - Auto-detected, adjust if needed
199
200This helps the system identify you in transcripts and personalize AI responses.
201
202---
203
204## Health Check
205
206Verify everything is working:
207
208```bash
209# Check services are running
210pgrep -af "sol:sense|sol:supervisor"
211
212# Check Callosum socket exists
213ls -la journal/health/callosum.sock
214
215# View service logs
216tail -f journal/health/*.log
217```
218
219See [DOCTOR.md](DOCTOR.md) for troubleshooting.
220
221---
222
223## Observers
224
225Observers run alongside each platform and send observations to the solstone server. The `sol observer install` command handles the normal local setup path.
226
227### Install
228
229```bash
230sol observer install
231sol observer install laptop
232sol observer install laptop --platform linux
233sol observer install laptop --platform tmux
234sol observer install --dry-run
235```
236
237With no name, `sol observer install` uses the machine hostname. Pass a name for a stable stream name, pass `--platform` to choose linux or tmux explicitly, and use `--dry-run` to see the plan before anything changes.
238
239Linux installs from `https://github.com/solpbc/solstone-linux.git`; tmux installs from `https://github.com/solpbc/solstone-tmux.git`. If a system package is missing, the command reports the distro-specific install command and stops before changing observer state.
240
241### macOS Observer
242
243```bash
244sol observer install --platform macos
245```
246
247macOS is delivered as a signed app bundle. The command directs you to https://solstone.app/observers.
248
249For manual build-from-source troubleshooting, use each observer repo's `INSTALL.md`. The linux repo includes distro package details and desktop notes; the tmux repo covers its pure-python service path.
250
251---
252
253## Next Steps
254
255- Create your first facet (project/context) in the web interface
256- Review captured content in the Calendar and Transcripts apps
257- Chat with the AI about your journal content
258
259For development setup, see [AGENTS.md](../AGENTS.md).