solpbc.org
personal memory agent
1# Environment
2
3## Journal Path
4
5The journal lives at `journal/` in the project root. `get_journal()` from `think.utils` returns the path — trust it unconditionally. Never set `_SOLSTONE_JOURNAL_OVERRIDE` from application code, service files, agent prompts, or subprocess environments. The env var exists exclusively for external use: test harnesses (`monkeypatch.setenv`) and Makefile sandboxes. If you think you need to override the journal path, you don't — fix the actual problem instead.
6
7## Service Installation
8
9`make install-service` installs solstone as a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. Override with `make install-service PORT=8000`. Managed via `sol service <install|start|stop|restart|status|logs>`.
10
11## API Keys
12
13Store API keys in `.env` file, never commit to repository.
14
15## Error Handling & Logging
16
17- Raise specific exceptions with clear messages
18- Use logging module, not print statements
19- Validate all external inputs (paths, owner data)
20- Fail fast with clear errors - avoid silent failures
21
22## Documentation
23
24- Update README files for new functionality
25- Code comments explain "why" not "what"
26- Function signatures should include type hints; highlight gaps when touching older modules
27- **All docs in `docs/`**: Browse for JOURNAL.md, APPS.md, CORTEX.md, CALLOSUM.md, THINK.md, and more
28- Each package has a README.md symlink pointing to its documentation in `docs/`.
29- **App/UI work**: [docs/APPS.md](docs/APPS.md) is required reading before modifying `apps/`
30
31## Git Practices
32
33- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
34
35## Getting Help
36
37- Run `sol` for status and CLI command list
38- Check [docs/DOCTOR.md](docs/DOCTOR.md) for debugging and diagnostics
39- Browse `docs/` for all subsystem documentation
40- Review test files in `tests/` for usage examples