personal memory agent
refactor(docs): move coding reference into docs
+2
-85
+1
-2
convey/maint_cli.py
+1
-2
convey/maint_cli.py
···
18
18
from datetime import datetime
19
19
from pathlib import Path
20
20
21
-
from think.utils import get_journal, setup_cli
22
-
23
21
from think.maint import (
24
22
get_state_file,
25
23
get_task_by_name,
···
28
26
run_pending_tasks,
29
27
run_task,
30
28
)
29
+
from think.utils import get_journal, setup_cli
31
30
32
31
33
32
def _format_duration(ms: int) -> str:
-82
talent/coding/SKILL.md
-82
talent/coding/SKILL.md
···
1
-
---
2
-
name: coding
3
-
description: >
4
-
Solstone development guidelines, project structure, coding standards,
5
-
testing, and environment. The single source of truth for anyone writing
6
-
code on solstone — Claude Code sessions, hopper lodes, and coder
7
-
sub-agents. Load this skill BEFORE writing, reviewing, exploring, or
8
-
reasoning about any solstone code. TRIGGER: writing code, reading code,
9
-
reviewing code, exploring code, understanding how something works,
10
-
project structure, directory layout, journal layout, segments, streams,
11
-
pipelines, observe, think, convey, apps, scratch scripts, coding
12
-
standards, testing, make commands, development setup, PR review, how
13
-
does X work, where is X, what calls X, tracing code paths.
14
-
---
15
-
16
-
# Development Guidelines
17
-
18
-
**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.
19
-
20
-
## Key Concepts
21
-
22
-
- **Journal**: Central data structure organized as `journal/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here.
23
-
- **Facets**: Project/context organization system that groups related content and provides scoped views of entities, tasks, and activities.
24
-
- **Entities**: Extracted information tracked over time across transcripts and interactions and associated with facets for semantic navigation.
25
-
- **Agents**: AI processors with configurable prompts that analyze content, extract insights, and respond to queries.
26
-
- **Callosum**: Message bus that enables asynchronous communication between components.
27
-
- **Indexer**: Builds and maintains SQLite database from journal data, enabling fast search and retrieval.
28
-
29
-
## Architecture
30
-
31
-
**Core Pipeline**: `observe` (capture) → JSON transcripts → `think` (analyze) → SQLite index → `convey` (web UI)
32
-
33
-
**Data Organization**:
34
-
- Everything organized under `journal/YYYYMMDD/` daily directories.
35
-
- Import segments are anchored to creation/modification time, not content "about" time.
36
-
- Facets provide project-scoped organization and filtering.
37
-
- Entities are extracted from transcripts and tracked across time.
38
-
- Indexer builds SQLite database for fast search and retrieval.
39
-
40
-
**Component Communication**:
41
-
- Callosum message bus enables async communication between services.
42
-
- Cortex orchestrates AI agent execution via `sol cortex`, spawning agent subprocesses with agent configurations.
43
-
- The unified CLI is `sol`. Run `sol` to see status and available commands.
44
-
45
-
## Quick Commands
46
-
47
-
```bash
48
-
make install # Install package (includes all deps)
49
-
make skills # Discover and symlink Agent Skills from talent/ dirs
50
-
make format # Auto-fix formatting, then report remaining issues
51
-
make test # Run unit tests
52
-
make ci # Full CI check (format check + lint + test)
53
-
make dev # Start stack (Ctrl+C to stop)
54
-
```
55
-
56
-
## Agent CLI Boundaries
57
-
58
-
Cogitate agents have access to all `sol` commands. The following infrastructure
59
-
commands must **never** be called by agents — they manage services and data
60
-
pipelines that should only be operated by the supervisor or human operators:
61
-
62
-
- `sol supervisor` / `sol start` — service lifecycle management
63
-
- `sol dream` — full processing pipeline (only heartbeat uses `sol dream --segment` for targeted reprocessing)
64
-
- `sol import` — data injection into journal
65
-
- `sol config` — system configuration changes
66
-
- `sol cortex` — agent process manager (meta-spawning)
67
-
- `sol agents` — direct agent execution
68
-
- `sol callosum` — message bus server
69
-
- `sol observer` / `sol observe-*` — capture services
70
-
- `sol sense` — capture event dispatcher
71
-
- `sol transcribe` / `sol describe` — processing pipelines
72
-
- `sol indexer --reset` — destructive index rebuild (read-only queries via `sol indexer` are fine)
73
-
74
-
Agents should use `sol call` commands for journal interaction and `sol health` /
75
-
`sol talent logs` for diagnostics.
76
-
77
-
## Reference
78
-
79
-
- `reference/project-structure.md` — Directory layout, package organization, CLI routing, file locations.
80
-
- `reference/coding-standards.md` — Style rules, naming conventions, file headers, development principles, dependencies.
81
-
- `reference/testing.md` — Test structure, fixtures, make commands, worktree development.
82
-
- `reference/environment.md` — Journal paths, API keys, error handling, documentation pointers, git practices.
+1
-1
talent/coding/reference/coding-standards.md
docs/coding-standards.md
+1
-1
talent/coding/reference/coding-standards.md
docs/coding-standards.md
···
38
38
- **Conciseness & Maintainability**: Clear code over clever code
39
39
- **Robustness**: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden.
40
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
-
- **Trust system path resolution**: Never set `_SOLSTONE_JOURNAL_OVERRIDE` or bypass `get_journal()` from application code, agent prompts, subprocess environments, or service files. The env var exists only for tests and Makefile sandboxes. See `reference/environment.md`.
41
+
- **Trust system path resolution**: Never set `_SOLSTONE_JOURNAL_OVERRIDE` or bypass `get_journal()` from application code, agent prompts, subprocess environments, or service files. The env var exists only for tests and Makefile sandboxes. See `environment.md`.
42
42
- **Security**: Never expose secrets, validate/sanitize all inputs
43
43
- **Performance**: Profile before optimizing
44
44
- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
talent/coding/reference/environment.md
docs/environment.md
talent/coding/reference/environment.md
docs/environment.md
talent/coding/reference/project-structure.md
docs/project-structure.md
talent/coding/reference/project-structure.md
docs/project-structure.md
talent/coding/reference/testing.md
docs/testing.md
talent/coding/reference/testing.md
docs/testing.md