personal memory agent
docs(install): document cogitate CLI binary prerequisites
Tool-using agents (entity detection, entity assist, etc.) shell out to
provider CLI binaries (gemini/claude/codex/opencode) as subprocesses,
but generate paths use the SDK directly. Until the first cogitate
talent runs, missing CLIs are invisible — users see drained dreams
but no entities, with sol top Agents Health as the only signal.
Adds a Cogitate CLI Binaries section to docs/INSTALL.md under API Keys
with the cogitate/generate split, per-provider install table, Node.js
prereqs, smoke tests, and the sol service restart reminder. Top-level
INSTALL.md gets a one-line pointer in Prerequisites. Settings UI gets
a one-liner on the API keys tab so users hit the prereq at the point
of configuration.
Closes req_kawxra2b (VPE/extro-hub). Sibling: req_2q2ofizo (cogitate
GOOGLE_API_KEY env mirror, commit c9b74b8a).
+38
+2
INSTALL.md
+2
INSTALL.md
···
22
22
23
23
the only hard requirement is `uv` — the Makefile checks for it and errors with install instructions if missing.
24
24
25
+
tool-using agents (entity detection, entity assist, etc.) additionally shell out to provider CLI binaries — `gemini`, `claude`, `codex`, or `opencode` — one per configured provider. install them after setting your API keys; see [docs/INSTALL.md § Cogitate CLI Binaries](docs/INSTALL.md#cogitate-cli-binaries-required-for-tool-using-agents) for the table.
26
+
25
27
### linux
26
28
27
29
```bash
+1
apps/settings/workspace.html
+1
apps/settings/workspace.html
···
2230
2230
<section class="settings-section" id="section-apikeys" role="tabpanel" aria-labelledby="tab-apikeys">
2231
2231
<h2>API keys</h2>
2232
2232
<p class="settings-section-desc">configure API keys for AI providers. keys are stored in your journal config.</p>
2233
+
<p class="settings-section-desc" style="margin-top:-0.5em">tool-using agents (entity detection, etc.) also need each provider's CLI binary installed (`gemini`, `claude`, `codex`, `opencode`) — see <a href="https://github.com/solpbc/solstone/blob/main/docs/INSTALL.md#cogitate-cli-binaries-required-for-tool-using-agents" target="_blank">install docs</a>.</p>
2233
2234
2234
2235
<form class="settings-form" onsubmit="return false;">
2235
2236
<div style="margin-bottom: 1em;">
+35
docs/INSTALL.md
+35
docs/INSTALL.md
···
129
129
130
130
---
131
131
132
+
## Cogitate CLI Binaries (Required for Tool-Using Agents)
133
+
134
+
solstone runs two distinct AI workloads, and they have different prerequisites:
135
+
136
+
- **Generate** — direct text generation (transcription, vision analysis, insights, descriptions). Uses each provider's SDK and works as soon as the API key is set. No extra binaries.
137
+
- **Cogitate** — tool-using agents (entity detection, entity assist, entity describe, and any talent under `apps/entities/talent/*.md` with `"type": "cogitate"`). solstone shells out to the provider's official CLI binary as a subprocess. The binary must be installed and on `PATH`.
138
+
139
+
Because cogitate-type talents only run when an entity-related dream completes, missing CLI binaries are invisible during initial install — generate-only paths produce transcripts and summaries, but **entities never appear**. `sol top` Agents Health flags this with messages like `"Google generate passes but Google cogitate fails: gemini CLI not installed"`. Install the binary for **each provider whose API key you configured above**. If you only set `GOOGLE_API_KEY`, you only need `gemini`.
140
+
141
+
| provider | binary | install |
142
+
|-----------|------------|-----------------------------------------------------------------|
143
+
| google | `gemini` | `npm install -g @google/gemini-cli` (Node 20+) |
144
+
| anthropic | `claude` | `npm install -g @anthropic-ai/claude-code` (Node 18+) |
145
+
| openai | `codex` | `npm install -g @openai/codex` (Node 16+) |
146
+
| ollama | `opencode` | `curl -fsSL https://opencode.ai/install \| bash` |
147
+
148
+
If you don't have Node.js: `brew install node` on macOS, your distro's package manager on Linux (e.g. `sudo dnf install nodejs`, `sudo apt install nodejs npm`). Verify each binary is on `PATH` after install:
149
+
150
+
```bash
151
+
gemini --version
152
+
claude --version
153
+
codex --version
154
+
opencode --version
155
+
```
156
+
157
+
After installing a CLI binary while solstone is running, restart the service so cortex picks up the new `PATH`:
158
+
159
+
```bash
160
+
sol service restart
161
+
```
162
+
163
+
`sol doctor` reports per-provider readiness, including whether the cogitate CLI is found.
164
+
165
+
---
166
+
132
167
## First Run
133
168
134
169
### Install as a Background Service