personal memory agent
solstone docs environment.md
4.1 kB · 72 lines
Markdown
at main

Environment #

Journal Path #

get_journal() / get_journal_info() in solstone.think.utils are the canonical journal resolvers. Trust them unconditionally.

Resolver order (with the source label get_journal_info() returns):

  1. SOLSTONE_JOURNAL env var, when set and non-empty → "env"
  2. ~/.config/solstone/config.toml, when it has a non-empty journal = "..." key → "config"
  3. source-tree fallback: <project_root>/journal when both <project_root>/pyproject.toml and <project_root>/.git exist → "source"
  4. built-in default: ~/journal → "default"

get_journal_info() no longer raises — there is always a resolved path. get_journal() raises SolstoneNotConfigured only when os.makedirs on the resolved path fails.

Who sets SOLSTONE_JOURNAL:

  • Installed runs: the managed wrapper at ~/.local/bin/sol
  • Unit tests: the set_test_journal_path autouse fixture in tests/conftest.py
  • Makefile sandboxes: explicit per-command env injection in make sandbox / verify targets

Who must not set it:

  • application code
  • service files
  • agent prompts
  • ad hoc subprocess environments spawned by app code

If you think you need to set SOLSTONE_JOURNAL from application code, fix the actual resolution problem instead.

Service Installation #

There are two install paths and they handle journal resolution differently. For a fresh source checkout, .venv/bin/journal setup installs managed bash wrappers at ~/.local/bin/sol and ~/.local/bin/journal, then installs solstone as a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. For packaged host installs (pip install solstone-journal, uv tool install solstone-journal && uv tool install solstone, or pipx install solstone-journal && pipx install solstone), journal setup also provisions those managed wrappers in-process, pointing them at the packaged runtime binaries. After setup, the wrappers let you use sol and journal from anywhere; override with .venv/bin/journal setup --port 8000 on the first source-checkout run or journal setup --port 8000 after the wrapper exists. If an existing alias is owned by another install, setup copies it to /tmp/<binary>.old-symlink-<timestamp> before atomically replacing both wrappers. Wrapper provisioning failures are non-fatal warnings so a later journal setup can retry. Both paths install the service.

Installed services invoke ~/.local/bin/journal. They do not write SOLSTONE_JOURNAL into the service env block; the wrapper exports it before execing the venv journal.

Use:

  • journal config show to display the resolved journal path, user-facing source label, and wrapper status
  • journal config journal <path> to atomically rewrite the wrapper's embedded journal path
  • journal service <install|start|stop|restart|status|logs> for service lifecycle management

API Keys #

Store API keys in .env file, never commit to repository.

Error Handling & Logging #

  • Raise specific exceptions with clear messages
  • Use logging module, not print statements
  • Validate all external inputs (paths, owner data)
  • Fail fast with clear errors - avoid silent failures

Documentation #

  • Update README files for new functionality
  • Code comments explain "why" not "what"
  • Function signatures should include type hints; highlight gaps when touching older modules
  • All docs in docs/ plus journal references in solstone/talent/journal/: Browse solstone/talent/journal/SKILL.md, APPS.md, CORTEX.md, CALLOSUM.md, THINK.md, and more
  • Each package has a README.md symlink pointing to its documentation in docs/.
  • App/UI work: docs/APPS.md is required reading before modifying solstone/apps/

Git Practices #

  • Git: Small focused commits, descriptive branch names. Run git commands directly (not git -C) since you're already in the repo.

Getting Help #

  • Run sol for status and CLI command list
  • Check docs/DOCTOR.md for debugging and diagnostics
  • Browse docs/ for all subsystem documentation
  • Review test files in tests/ for usage examples