solpbc.org
personal memory agent
1# Project Structure
2
3## Directory Layout
4
5```text
6solstone/
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├── talent/ # Agent/generator configs + Agent Skills (talent/*/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
20Each 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`talent/*.md` stores agent personas and generator templates. Apps can add their own in `apps/*/talent/*.md`. Skills live at `talent/*/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**: `talent/*.md` (apps can add their own in `talent/`, see [docs/APPS.md](docs/APPS.md))
45- **Generator Templates**: `talent/*.md` (apps can add their own in `talent/`, see [docs/APPS.md](docs/APPS.md))
46- **Agent Skills**: `talent/*/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