personal memory agent
Merge branch 'hopper-idnbr5ky-body-skill'
+246
+51
muse/body/SKILL.md
+51
muse/body/SKILL.md
···
1
+
---
2
+
name: body
3
+
description: Development guidelines, project structure, coding standards, testing, and environment for solstone. TRIGGER when contributing code, reviewing PRs, setting up development environment, or asking about project conventions.
4
+
---
5
+
6
+
# Development Guidelines
7
+
8
+
**solstone** is a Python-based AI-driven desktop journaling toolkit with three packages: `observe/` for multimodal capture and AI-powered analysis, `think/` for data post-processing, AI agent orchestration, and intelligent insights, and `convey/` for the web application, with `apps/` for extensions. The project uses a modular architecture where each package can operate independently while sharing common utilities and data formats through the journal system.
9
+
10
+
## Key Concepts
11
+
12
+
- **Journal**: Central data structure organized as `journal/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here.
13
+
- **Facets**: Project/context organization system that groups related content and provides scoped views of entities, tasks, and activities.
14
+
- **Entities**: Extracted information tracked over time across transcripts and interactions and associated with facets for semantic navigation.
15
+
- **Agents**: AI processors with configurable prompts that analyze content, extract insights, and respond to queries.
16
+
- **Callosum**: Message bus that enables asynchronous communication between components.
17
+
- **Indexer**: Builds and maintains SQLite database from journal data, enabling fast search and retrieval.
18
+
19
+
## Architecture
20
+
21
+
**Core Pipeline**: `observe` (capture) → JSON transcripts → `think` (analyze) → SQLite index → `convey` (web UI)
22
+
23
+
**Data Organization**:
24
+
- Everything organized under `journal/YYYYMMDD/` daily directories.
25
+
- Import segments are anchored to creation/modification time, not content "about" time.
26
+
- Facets provide project-scoped organization and filtering.
27
+
- Entities are extracted from transcripts and tracked across time.
28
+
- Indexer builds SQLite database for fast search and retrieval.
29
+
30
+
**Component Communication**:
31
+
- Callosum message bus enables async communication between services.
32
+
- Cortex orchestrates AI agent execution via `sol cortex`, spawning agent subprocesses with agent configurations.
33
+
- The unified CLI is `sol`. Run `sol` to see status and available commands.
34
+
35
+
## Quick Commands
36
+
37
+
```bash
38
+
make install # Install package (includes all deps)
39
+
make skills # Discover and symlink Agent Skills from muse/ dirs
40
+
make format # Auto-fix formatting, then report remaining issues
41
+
make test # Run unit tests
42
+
make ci # Full CI check (format check + lint + test)
43
+
make dev # Start stack (Ctrl+C to stop)
44
+
```
45
+
46
+
## Reference
47
+
48
+
- `reference/project-structure.md` — Directory layout, package organization, CLI routing, file locations.
49
+
- `reference/coding-standards.md` — Style rules, naming conventions, file headers, development principles, dependencies.
50
+
- `reference/testing.md` — Test structure, fixtures, make commands, worktree development.
51
+
- `reference/environment.md` — Journal paths, API keys, error handling, documentation pointers, git practices.
+51
muse/body/reference/coding-standards.md
+51
muse/body/reference/coding-standards.md
···
1
+
# Coding Standards
2
+
3
+
## Language & Tools
4
+
5
+
- **Ruff** (`make format`) - Formatting, linting, and import sorting
6
+
- **mypy** (`make check`) - Type checking
7
+
- Configuration in `pyproject.toml`
8
+
9
+
## Naming Conventions
10
+
11
+
- **Modules/Functions/Variables**: `snake_case`
12
+
- **Classes**: `PascalCase`
13
+
- **Constants**: `UPPER_SNAKE_CASE`
14
+
- **Private Members**: `_leading_underscore`
15
+
16
+
## Code Organization
17
+
18
+
- **Imports**: Prefer absolute imports, grouped (stdlib, third-party, local), one per line
19
+
- **Docstrings**: Google or NumPy style with parameter/return descriptions
20
+
- **Type Hints**: Should be included on function signatures (legacy helpers may still need updates)
21
+
- **File Structure**: Constants → helpers → classes → main/CLI
22
+
23
+
## File Headers
24
+
25
+
All source code files (but not text or markdown files or prompts) must begin with a license and copyright header:
26
+
27
+
```
28
+
# SPDX-License-Identifier: AGPL-3.0-only
29
+
# Copyright (c) 2026 sol pbc
30
+
```
31
+
32
+
Use `//` comments for JavaScript files.
33
+
34
+
## Development Principles
35
+
36
+
- **DRY, KISS, YAGNI**: Extract common logic, prefer simple solutions, don't over-engineer
37
+
- **Single Responsibility**: Functions/classes do one thing well
38
+
- **Conciseness & Maintainability**: Clear code over clever code
39
+
- **Robustness**: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden.
40
+
- **Self-Contained Codebase**: All code that depends on this project lives within this repository—never add backwards-compatibility shims, fallback aliases, re-exports for moved symbols, deprecated parameter handling, or legacy support code. When renaming or removing something, update all usages directly. For journal data format changes, write a migration script (see [docs/APPS.md](docs/APPS.md) for `maint` commands) instead of adding compatibility layers.
41
+
- **Security**: Never expose secrets, validate/sanitize all inputs
42
+
- **Performance**: Profile before optimizing
43
+
- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
44
+
45
+
## Dependencies
46
+
47
+
- **Minimize Dependencies**: Use standard library when possible
48
+
- **All Dependencies**: Add to `dependencies` in `pyproject.toml`
49
+
- **Package Manager**: [uv](https://docs.astral.sh/uv/) — lock file (`uv.lock`) is committed, `make install` syncs from it
50
+
- **Installation**: `make install` (creates isolated `.venv/`, syncs deps from lock file, symlinks `sol` to `~/.local/bin`)
51
+
- **Updating**: `make update` upgrades all deps to latest and regenerates the lock file
+36
muse/body/reference/environment.md
+36
muse/body/reference/environment.md
···
1
+
# Environment
2
+
3
+
## Journal Path
4
+
5
+
The journal lives at `journal/` in the project root. `get_journal()` from `think.utils` returns the path. For tests, set `_SOLSTONE_JOURNAL_OVERRIDE` to override.
6
+
7
+
## API Keys
8
+
9
+
Store API keys in `.env` file, never commit to repository.
10
+
11
+
## Error Handling & Logging
12
+
13
+
- Raise specific exceptions with clear messages
14
+
- Use logging module, not print statements
15
+
- Validate all external inputs (paths, user data)
16
+
- Fail fast with clear errors - avoid silent failures
17
+
18
+
## Documentation
19
+
20
+
- Update README files for new functionality
21
+
- Code comments explain "why" not "what"
22
+
- Function signatures should include type hints; highlight gaps when touching older modules
23
+
- **All docs in `docs/`**: Browse for JOURNAL.md, APPS.md, CORTEX.md, CALLOSUM.md, THINK.md, and more
24
+
- Each package has a README.md symlink pointing to its documentation in `docs/`.
25
+
- **App/UI work**: [docs/APPS.md](docs/APPS.md) is required reading before modifying `apps/`
26
+
27
+
## Git Practices
28
+
29
+
- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
30
+
31
+
## Getting Help
32
+
33
+
- Run `sol` for status and CLI command list
34
+
- Check [docs/DOCTOR.md](docs/DOCTOR.md) for debugging and diagnostics
35
+
- Browse `docs/` for all subsystem documentation
36
+
- Review test files in `tests/` for usage examples
+47
muse/body/reference/project-structure.md
+47
muse/body/reference/project-structure.md
···
1
+
# Project Structure
2
+
3
+
## Directory Layout
4
+
5
+
```text
6
+
solstone/
7
+
├── sol.py # Unified CLI entry point (run: sol <command>)
8
+
├── observe/ # Multimodal capture & AI analysis
9
+
├── think/ # Data post-processing, AI agents & orchestration
10
+
├── convey/ # Web app frontend & backend
11
+
├── apps/ # Convey app extensions (see docs/APPS.md)
12
+
├── muse/ # Agent/generator configs + Agent Skills (muse/*/SKILL.md)
13
+
├── tests/ # Pytest test suites + test fixtures under tests/fixtures/
14
+
├── docs/ # All documentation (*.md files)
15
+
├── AGENTS.md # Development guidelines (this file)
16
+
├── CLAUDE.md # Symlink to AGENTS.md for Claude Code
17
+
└── README.md # Project overview
18
+
```
19
+
20
+
Each package has a README.md symlink pointing to its documentation in `docs/`.
21
+
22
+
## Package Organization
23
+
24
+
- **Python**: Requires Python 3.10+
25
+
- **Modules**: Each top-level folder is a Python package with `__init__.py` unless it is data-only (e.g., `tests/fixtures/`)
26
+
- **Imports**: Prefer absolute imports (e.g., `from think.utils import setup_cli`) whenever feasible
27
+
- **Entry Points**: Commands are registered in `sol.py`'s `COMMANDS` dict (pyproject.toml just defines the `sol` entry point)
28
+
- **Journal**: Data stored under `journal/` at the project root
29
+
- **Calling**: When calling other modules as a separate process always use `sol <command>` and never call using `python -m ...` (e.g., use `sol indexer`, NOT `python -m think.indexer`)
30
+
31
+
## CLI Routing
32
+
33
+
`sol.py`'s `COMMANDS` dict maps command names to module paths. The unified CLI is `sol`. Run `sol` to see status and available commands. `sol call` routes to `think/call.py`, which discovers `apps/*/call.py` Typer sub-apps and mounts them as subcommands.
34
+
35
+
## Agent & Skill Organization
36
+
37
+
`muse/*.md` stores agent personas and generator templates. Apps can add their own in `apps/*/muse/*.md`. Skills live at `muse/*/SKILL.md` and are symlinked to `.agents/skills/` and `.claude/skills/` via `make skills`.
38
+
39
+
## File Locations
40
+
41
+
- **Entry Points**: `sol.py` `COMMANDS` dict
42
+
- **Test Fixtures**: `tests/fixtures/journal/` - complete mock journal
43
+
- **Live Logs**: `journal/health/<service>.log`
44
+
- **Agent Personas**: `muse/*.md` (apps can add their own in `muse/`, see [docs/APPS.md](docs/APPS.md))
45
+
- **Generator Templates**: `muse/*.md` (apps can add their own in `muse/`, see [docs/APPS.md](docs/APPS.md))
46
+
- **Agent Skills**: `muse/*/SKILL.md` - symlinked to `.agents/skills/` and `.claude/skills/` via `make skills`, read https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices to create the best skills
47
+
- **Scratch Space**: `scratch/` - git-ignored local workspace
+61
muse/body/reference/testing.md
+61
muse/body/reference/testing.md
···
1
+
# Testing
2
+
3
+
## Test Structure
4
+
5
+
- **Framework**: pytest with coverage reporting
6
+
- **Unit Tests**: `tests/` root directory
7
+
- Fast, no external API calls
8
+
- Use `tests/fixtures/journal/` mock data
9
+
- Test individual functions and modules
10
+
- **Integration Tests**: `tests/integration/` subdirectory
11
+
- Test real backends (Anthropic, OpenAI, Google)
12
+
- Require API keys in `.env`
13
+
- Test end-to-end workflows
14
+
- **Naming**: Files `test_*.py`, functions `test_*`
15
+
- **Fixtures**: Shared fixtures in `tests/conftest.py`
16
+
17
+
## Fixture Journal
18
+
19
+
```python
20
+
# Use comprehensive mock journal data for testing
21
+
os.environ["_SOLSTONE_JOURNAL_OVERRIDE"] = "tests/fixtures/journal"
22
+
# Now all journal operations work with test data
23
+
```
24
+
25
+
The `tests/fixtures/journal/` directory contains a complete mock journal structure with sample facets, agents, transcripts, and indexed data for testing.
26
+
27
+
## Running Tests
28
+
29
+
- `make test` for unit tests
30
+
- `make test-apps` to run app tests
31
+
- `make test-integration` for integration tests
32
+
- `make test-all` to run all tests (core + apps + integration)
33
+
- `make test-only TEST=path` to run specific tests
34
+
- `make coverage` to generate a coverage report
35
+
- `make ci` before committing (formats, lints, tests)
36
+
- Always run `sol restart-convey` after editing `convey/` or `apps/` to reload code
37
+
- Use `sol screenshot <route>` to capture UI screenshots for visual testing
38
+
39
+
## Worktree Development
40
+
41
+
Run the full stack (supervisor + callosum + sense + cortex + convey) against test fixture data:
42
+
43
+
```bash
44
+
make dev # Start stack (Ctrl+C to stop)
45
+
```
46
+
47
+
In a second terminal, take screenshots or hit endpoints:
48
+
49
+
```bash
50
+
export _SOLSTONE_JOURNAL_OVERRIDE=tests/fixtures/journal
51
+
export PATH=$(pwd)/.venv/bin:$PATH
52
+
sol screenshot / -o scratch/home.png
53
+
curl -s http://localhost:$(cat tests/fixtures/journal/health/convey.port)/
54
+
```
55
+
56
+
Notes:
57
+
58
+
- Agents won't execute without API keys — this is expected in worktrees
59
+
- Output artifacts go in `scratch/` (git-ignored)
60
+
- Service logs: `tests/fixtures/journal/health/<service>.log`
61
+
- `make dev` writes runtime artifacts (stats cache, health logs, task logs) into the fixtures journal — these are covered by `tests/fixtures/journal/.gitignore` and should never be committed