+16 -28

AGENTS.md

reviewed

··· 19 19 20 20 Understanding these core concepts is essential for working with Sunstone: 21 21 22 22 - * **Journal**: Central data structure organized as `JOURNAL_PATH/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here. See **JOURNAL.md** for detailed structure. 22 22 + * **Journal**: Central data structure organized as `JOURNAL_PATH/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here. See [docs/JOURNAL.md](docs/JOURNAL.md). 23 23 24 24 * **Facets**: Project/context organization system (e.g., "work", "personal", "acme"). Facets group related content and provide scoped views of entities, tasks, and activities. 25 25 26 26 * **Entities**: Extracted information (people, projects, concepts) tracked over time across transcripts and interactions. Entities are associated with facets and enable semantic navigation. 27 27 28 28 - * **Agents**: AI processors with configurable personas that analyze content, extract insights, and respond to queries. Managed by Cortex. See **CORTEX.md** for agent system architecture. 28 28 + * **Agents**: AI processors with configurable personas that analyze content, extract insights, and respond to queries. See [docs/CORTEX.md](docs/CORTEX.md). 29 29 30 30 - * **Callosum**: Message bus that enables asynchronous communication between components (observe, think, convey, cortex). Uses file-based persistence. See **CALLOSUM.md** for protocol details. 30 30 + * **Callosum**: Message bus that enables asynchronous communication between components. See [docs/CALLOSUM.md](docs/CALLOSUM.md). 31 31 32 32 - * **Indexer**: Builds and maintains SQLite database from journal data, enabling fast search and retrieval. Indexes transcripts, summaries, entities, and events. 32 32 + * **Indexer**: Builds and maintains SQLite database from journal data, enabling fast search and retrieval. 33 33 34 34 --- 35 35 ··· 39 39 sunstone/ 40 40 ├── observe/ # Multimodal capture & AI analysis 41 41 ├── think/ # Data post-processing & AI analysis 42 42 - │ ├── indexer/ # Database indexing subsystem 43 43 - │ └── insights/ # Insight generation templates 44 42 ├── convey/ # Web app frontend & backend 45 45 - │ ├── static/ # JavaScript and CSS assets 46 46 - │ ├── templates/ # Jinja2 HTML templates 47 47 - │ └── root.py # Core Flask routes (app-specific views live in apps/, see APPS.md) 48 48 - ├── apps/ # Convey app extensions 43 43 + ├── apps/ # Convey app extensions (see docs/APPS.md) 49 44 ├── muse/ # AI agent system and MCP tooling 50 50 - │ └── agents/ # Agent system prompts and configs 51 51 - ├── tests/ # Comprehensive pytest test suites 52 52 - │ └── integration/# Integration test suite 53 53 - ├── fixtures/ # Test data and examples 54 54 - │ └── journal/ # Mock journal structure for testing 55 55 - ├── Makefile # Build and development automation 56 56 - ├── pyproject.toml # Package configuration and dependencies 57 57 - ├── JOURNAL.md # Journal directory structure documentation 58 58 - ├── README.md # Project overview and quick start 59 59 - ├── APPS.md # App development guide 60 60 - ├── CORTEX.md # Agent system documentation 61 61 - ├── CALLOSUM.md # Callosum connection system documentation 62 62 - └── AGENTS.md # Development guidelines (this file) 45 45 + ├── tests/ # Pytest test suites 46 46 + ├── fixtures/ # Test data (mock journal) 47 47 + ├── docs/ # All documentation (*.md files) 48 48 + ├── AGENTS.md # Development guidelines (this file) 49 49 + ├── CLAUDE.md # Symlink to AGENTS.md for Claude Code 50 50 + └── README.md # Project overview 63 51 ``` 64 52 65 65 - > Note: `fixtures/` is a data directory backing tests/ and intentionally lacks `__init__.py`. 53 53 + Each package has a README.md symlink pointing to its documentation in `docs/`. 66 54 67 55 ### Package Organization 68 56 ··· 194 182 * Update README files for new functionality 195 183 * Code comments explain "why" not "what" 196 184 * Function signatures should include type hints; highlight gaps when touching older modules 197 197 - * **See subsystem docs**: JOURNAL.md, APPS.md, CORTEX.md, CALLOSUM.md, DOCTOR.md 198 198 - * **App/UI work**: APPS.md is required reading before modifying anything under `apps/` (where HTML/JS lives) 185 185 + * **All docs in `docs/`**: JOURNAL.md, APPS.md, CORTEX.md, CALLOSUM.md, DOCTOR.md, etc. 186 186 + * **App/UI work**: [docs/APPS.md](docs/APPS.md) is required reading before modifying `apps/` 199 187 200 188 --- 201 189 ··· 254 242 255 243 ### Getting Help 256 244 * Run `sunstone` for CLI command list 257 257 - * Check **DOCTOR.md** for debugging and diagnostics 258 258 - * Check **JOURNAL.md**, **APPS.md**, **CORTEX.md**, **CALLOSUM.md** for subsystem details 245 245 + * Check [docs/DOCTOR.md](docs/DOCTOR.md) for debugging and diagnostics 246 246 + * Browse `docs/` for all subsystem documentation 259 247 * Review test files in `tests/` for usage examples

+9 -9

APPS.md docs/APPS.md

reviewed

··· 96 96 97 97 **Vendor Libraries:** 98 98 - Use `{{ vendor_lib('marked') }}` for markdown rendering 99 99 - - See `convey/static/vendor/VENDOR.md` for available libraries 99 99 + - See [VENDOR.md](VENDOR.md) for available libraries 100 100 101 101 **Reference implementations:** 102 102 - Minimal: `apps/home/workspace.html` (simple content) ··· 244 244 - `listen(tract, callback)` - Listen to specific tract ('cortex', 'indexer', 'observe', etc.) 245 245 - `listen('*', callback)` - Listen to all events 246 246 - Messages have structure: `{tract: 'cortex', event: 'agent_complete', ...data}` 247 247 - - See **CALLOSUM.md** for event protocol details 247 247 + - See [CALLOSUM.md](CALLOSUM.md) for event protocol details 248 248 249 249 **Reference implementations:** 250 250 - `apps/todos/background.html` - App icon badge with API fetch ··· 312 312 - Keys are namespaced as `{app}:{agent}` (e.g., `my_app:helper`) 313 313 - Agents inherit all system agent capabilities (tools, scheduling, handoffs, multi-facet) 314 314 315 315 - **Metadata format:** Same schema as system agents in `muse/agents/*.json` - includes `title`, `backend`, `model`, `tools`, `schedule`, `priority`, and `multi_facet` fields. See **CORTEX.md** for agent configuration details. 315 315 + **Metadata format:** Same schema as system agents in `muse/agents/*.json` - includes `title`, `backend`, `model`, `tools`, `schedule`, `priority`, and `multi_facet` fields. See [CORTEX.md](CORTEX.md) for agent configuration details. 316 316 317 317 **Reference implementations:** 318 318 - System agent examples: `muse/agents/*.txt` and `*.json` ··· 408 408 ### Entities 409 409 `think/entities.py`: `get_entities(facet)` - Get entities for facet 410 410 411 411 - See **JOURNAL.md**, **CORTEX.md**, **CALLOSUM.md** for subsystem details. 411 411 + See [JOURNAL.md](JOURNAL.md), [CORTEX.md](CORTEX.md), [CALLOSUM.md](CALLOSUM.md) for subsystem details. 412 412 413 413 --- 414 414 ··· 444 444 445 445 **Common tracts:** `cortex`, `indexer`, `observe`, `task` 446 446 447 447 - See **CALLOSUM.md** for complete event protocol. 447 447 + See [CALLOSUM.md](CALLOSUM.md) for complete event protocol. 448 448 449 449 --- 450 450 ··· 593 593 - **`convey/templates/app.html`** - Main app container template 594 594 - **`convey/static/app.js`** - AppServices framework 595 595 - **`convey/static/websocket.js`** - WebSocket event system 596 596 - - **CLAUDE.md** - Project development guidelines and standards 597 597 - - **JOURNAL.md** - Journal directory structure and data organization 598 598 - - **CORTEX.md** - Agent system architecture and spawning agents 599 599 - - **CALLOSUM.md** - Message bus protocol and WebSocket events 596 596 + - [../AGENTS.md](../AGENTS.md) - Project development guidelines and standards 597 597 + - [JOURNAL.md](JOURNAL.md) - Journal directory structure and data organization 598 598 + - [CORTEX.md](CORTEX.md) - Agent system architecture and spawning agents 599 599 + - [CALLOSUM.md](CALLOSUM.md) - Message bus protocol and WebSocket events 600 600 601 601 For Flask documentation, see [https://flask.palletsprojects.com/](https://flask.palletsprojects.com/)

CALLOSUM.md docs/CALLOSUM.md

reviewed

CORTEX.md docs/CORTEX.md

reviewed

DOCTOR.md docs/DOCTOR.md

reviewed

+1 -1

JOURNAL.md docs/JOURNAL.md

reviewed

··· 454 454 455 455 This unified approach allows users to reply to any message via the chat continue feature, treating messages and agent outputs identically in the UI. 456 456 457 457 - See **APPS.md** for app storage utilities and access patterns. 457 457 + See [APPS.md](APPS.md) for app storage utilities and access patterns. 458 458 459 459 ## Imported Audio 460 460

+6 -7

README.md

reviewed

··· 144 144 145 145 ## 📚 Documentation 146 146 147 147 - - [JOURNAL.md](JOURNAL.md) - Journal directory structure and data organization 148 147 - [AGENTS.md](AGENTS.md) - Development guidelines and coding standards 149 149 - - [CORTEX.md](CORTEX.md) - Agent system documentation 150 150 - 151 151 - ### Package Documentation 152 152 - - [observe/README.md](observe/README.md) - Multimodal capture and analysis details 153 153 - - [think/README.md](think/README.md) - Data processing and AI analysis details 154 154 - - [convey/README.md](convey/README.md) - Web interface usage and features 148 148 + - [docs/](docs/) - All other documentation: 149 149 + - [JOURNAL.md](docs/JOURNAL.md) - Journal directory structure and data organization 150 150 + - [CORTEX.md](docs/CORTEX.md) - Agent system documentation 151 151 + - [OBSERVE.md](docs/OBSERVE.md) - Multimodal capture and analysis 152 152 + - [THINK.md](docs/THINK.md) - Data processing and AI analysis 153 153 + - [CONVEY.md](docs/CONVEY.md) - Web interface and app development 155 154 156 155 ## 🤝 Contributing 157 156

+1

apps/README.md

reviewed

··· 1 1 + ../docs/APPS.md

+1 -92

convey/README.md

reviewed

··· 1 1 - # sunstone-convey 2 2 - 3 3 - Web-based journal review interface built with Flask. It exposes a few small views for exploring daily summaries and entity data stored inside a **journal** folder. 4 4 - 5 5 - ## Installation 6 6 - 7 7 - ```bash 8 8 - pip install -e . 9 9 - ``` 10 10 - 11 11 - ## Usage 12 12 - 13 13 - Run the server with: 14 14 - 15 15 - ```bash 16 16 - convey 17 17 - ``` 18 18 - 19 19 - ### Authentication 20 20 - 21 21 - Password authentication is configured through the journal config at `config/journal.json`: 22 22 - 23 23 - ```json 24 24 - { 25 25 - "convey": { 26 26 - "password": "your-password-here" 27 27 - } 28 28 - } 29 29 - ``` 30 30 - 31 31 - A password must be configured to use the application. If no password is set, the login page will display an error with configuration instructions. 32 32 - 33 33 - ## Architecture 34 34 - 35 35 - Convey uses an **app plugin system** where all functional views are implemented as independent apps in the `/apps/` directory. The core `convey/` package provides authentication, WebSocket communication, and the app loading infrastructure. 36 36 - 37 37 - ``` 38 38 - convey/ 39 39 - __init__.py - Flask app factory, app registry, context processors 40 40 - state.py - global state (journal_root) 41 41 - bridge.py - Callosum WebSocket bridge for real-time events 42 42 - utils.py - shared helpers (format_date, spawn_agent, etc.) 43 43 - screenshot.py - screenshot utility for testing 44 44 - views/ 45 45 - __init__.py - blueprint registration 46 46 - home.py - authentication (login/logout) and root redirect 47 47 - templates/ 48 48 - app.html - main app container template 49 49 - menu_bar.html - dynamic left sidebar menu 50 50 - status_pane.html - WebSocket status indicator 51 51 - login.html - login page 52 52 - macros.html - Jinja macros 53 53 - static/ - shared CSS and JavaScript 54 54 - app.css - app system styles 55 55 - app.js - facet pills, services, notification center 56 56 - websocket.js - WebSocket connection handler 57 57 - error-handler.js - global error handling 58 58 - colors.js - color palette 59 59 - vendor/ - third-party libraries (marked.js) 60 60 - 61 61 - apps/ - App plugin directory (see apps/README.md) 62 62 - {app_name}/ 63 63 - app.json - metadata (icon, label) 64 64 - routes.py - Flask blueprint with routes 65 65 - workspace.html - main UI template 66 66 - background.html - (optional) background service script 67 67 - ``` 68 68 - 69 69 - ### App System 70 70 - 71 71 - All functional views are implemented as apps in `/apps/`. Each app: 72 72 - - Has its own directory with `app.json`, `routes.py`, and `workspace.html` 73 73 - - Uses blueprint name `app:{name}` with URL prefix `/app/{name}/` 74 74 - - Is automatically discovered and registered by `AppRegistry` 75 75 - - Can provide facet-scoped views and background services 76 76 - 77 77 - **Available apps:** home, todos, inbox, chat, agents, search, calendar, entities, news, stats, tokens, settings, import, live, dev 78 78 - 79 79 - ### Core Routes 80 80 - 81 81 - The `convey/views/home.py` module provides essential routes: 82 82 - 83 83 - - `/` - Redirects to `/app/home/` 84 84 - - `/login` - Authentication page 85 85 - - `/logout` - Clear session and redirect to login 86 86 - - `/favicon.ico` - Serve favicon 87 87 - 88 88 - All functional views are accessed at `/app/{name}/` URLs. 89 89 - 90 90 - ### Adding a New App 91 91 - 92 92 - See `/apps/README.md` for detailed instructions on creating new apps in the plugin system. 1 1 + ../docs/CONVEY.md

+1 -79

convey/static/vendor/VENDOR.md

reviewed

··· 1 1 - # Third-Party Vendor Libraries 2 2 - 3 3 - This directory contains third-party JavaScript libraries used across Sunstone apps. 4 4 - 5 5 - ## Purpose 6 6 - 7 7 - The `vendor/` directory provides: 8 8 - - Centralized location for third-party libraries 9 9 - - Version tracking and documentation 10 10 - - Consistent access pattern for all apps 11 11 - - Local copies for reliability (no CDN dependencies) 12 12 - 13 13 - ## Available Libraries 14 14 - 15 15 - ### marked (v15.0.12) 16 16 - 17 17 - **Purpose**: Markdown parsing and rendering 18 18 - 19 19 - **License**: MIT (included in file header) 20 20 - 21 21 - **Source**: https://github.com/markedjs/marked 22 22 - 23 23 - **CDN Alternative**: `https://cdn.jsdelivr.net/npm/marked/marked.min.js` 24 24 - 25 25 - **Usage in App Templates**: 26 26 - ```html 27 27 - <!-- Using helper function (recommended) --> 28 28 - <script src="{{ vendor_lib('marked') }}"></script> 29 29 - 30 30 - <!-- Using explicit path --> 31 31 - <script src="{{ url_for('static', filename='vendor/marked/marked.min.js') }}"></script> 32 32 - ``` 33 33 - 34 34 - **Example**: 35 35 - ```javascript 36 36 - // Basic markdown rendering 37 37 - const html = marked.parse('# Hello World'); 38 38 - 39 39 - // With options 40 40 - const html = marked.parse(markdown, { 41 41 - breaks: true, // Convert \n to <br> 42 42 - gfm: true, // GitHub Flavored Markdown 43 43 - headerIds: false, // Disable auto-generated header IDs 44 44 - mangle: false // Disable email mangling 45 45 - }); 46 46 - ``` 47 47 - 48 48 - **Currently Used By** (legacy references): 49 49 - - `convey/templates/chat.html` (via `convey/static/marked.min.js`) 50 50 - - `convey/templates/facet_detail.html` (via CDN) 51 51 - - `convey/templates/agents.html` (via CDN) 52 52 - 53 53 - ## Adding New Libraries 54 54 - 55 55 - When adding a new third-party library: 56 56 - 57 57 - 1. **Create subdirectory**: `vendor/{library_name}/` 58 58 - 2. **Add minified file**: Copy production-ready `.min.js` file 59 59 - 3. **Check license**: Ensure license is MIT-compatible and included 60 60 - 4. **Update this manifest**: Add entry with version, purpose, and usage 61 61 - 5. **Test**: Verify library loads and works in development 62 62 - 63 63 - ## Updating Libraries 64 64 - 65 65 - When updating a library version: 66 66 - 67 67 - 1. **Replace file** in vendor directory 68 68 - 2. **Update version** in this manifest 69 69 - 3. **Test all apps**: Check apps listed in "Currently Used By" 70 70 - 4. **Commit**: Use message format: `chore: update {library} to v{version}` 71 71 - 72 72 - ## Guidelines 73 73 - 74 74 - - **Prefer local copies** over CDN for reliability and offline development 75 75 - - **Use minified versions** for production-ready performance 76 76 - - **Include licenses** either in file headers or separate LICENSE files 77 77 - - **Document usage patterns** in this manifest 78 78 - - **Track versions** to enable security updates 79 79 - - **One library per subdirectory** for clean organization 1 1 + ../../../../docs/VENDOR.md

+92

docs/CONVEY.md

reviewed

··· 1 1 + # sunstone-convey 2 2 + 3 3 + Web-based journal review interface built with Flask. It exposes a few small views for exploring daily summaries and entity data stored inside a **journal** folder. 4 4 + 5 5 + ## Installation 6 6 + 7 7 + ```bash 8 8 + pip install -e . 9 9 + ``` 10 10 + 11 11 + ## Usage 12 12 + 13 13 + Run the server with: 14 14 + 15 15 + ```bash 16 16 + convey 17 17 + ``` 18 18 + 19 19 + ### Authentication 20 20 + 21 21 + Password authentication is configured through the journal config at `config/journal.json`: 22 22 + 23 23 + ```json 24 24 + { 25 25 + "convey": { 26 26 + "password": "your-password-here" 27 27 + } 28 28 + } 29 29 + ``` 30 30 + 31 31 + A password must be configured to use the application. If no password is set, the login page will display an error with configuration instructions. 32 32 + 33 33 + ## Architecture 34 34 + 35 35 + Convey uses an **app plugin system** where all functional views are implemented as independent apps in the `/apps/` directory. The core `convey/` package provides authentication, WebSocket communication, and the app loading infrastructure. 36 36 + 37 37 + ``` 38 38 + convey/ 39 39 + __init__.py - Flask app factory, app registry, context processors 40 40 + state.py - global state (journal_root) 41 41 + bridge.py - Callosum WebSocket bridge for real-time events 42 42 + utils.py - shared helpers (format_date, spawn_agent, etc.) 43 43 + screenshot.py - screenshot utility for testing 44 44 + views/ 45 45 + __init__.py - blueprint registration 46 46 + home.py - authentication (login/logout) and root redirect 47 47 + templates/ 48 48 + app.html - main app container template 49 49 + menu_bar.html - dynamic left sidebar menu 50 50 + status_pane.html - WebSocket status indicator 51 51 + login.html - login page 52 52 + macros.html - Jinja macros 53 53 + static/ - shared CSS and JavaScript 54 54 + app.css - app system styles 55 55 + app.js - facet pills, services, notification center 56 56 + websocket.js - WebSocket connection handler 57 57 + error-handler.js - global error handling 58 58 + colors.js - color palette 59 59 + vendor/ - third-party libraries (marked.js) 60 60 + 61 61 + apps/ - App plugin directory (see APPS.md) 62 62 + {app_name}/ 63 63 + app.json - metadata (icon, label) 64 64 + routes.py - Flask blueprint with routes 65 65 + workspace.html - main UI template 66 66 + background.html - (optional) background service script 67 67 + ``` 68 68 + 69 69 + ### App System 70 70 + 71 71 + All functional views are implemented as apps in `/apps/`. Each app: 72 72 + - Has its own directory with `app.json`, `routes.py`, and `workspace.html` 73 73 + - Uses blueprint name `app:{name}` with URL prefix `/app/{name}/` 74 74 + - Is automatically discovered and registered by `AppRegistry` 75 75 + - Can provide facet-scoped views and background services 76 76 + 77 77 + **Available apps:** home, todos, inbox, chat, agents, search, calendar, entities, news, stats, tokens, settings, import, live, dev 78 78 + 79 79 + ### Core Routes 80 80 + 81 81 + The `convey/views/home.py` module provides essential routes: 82 82 + 83 83 + - `/` - Redirects to `/app/home/` 84 84 + - `/login` - Authentication page 85 85 + - `/logout` - Clear session and redirect to login 86 86 + - `/favicon.ico` - Serve favicon 87 87 + 88 88 + All functional views are accessed at `/app/{name}/` URLs. 89 89 + 90 90 + ### Adding a New App 91 91 + 92 92 + See [APPS.md](APPS.md) for detailed instructions on creating new apps.

+66

docs/INTEGRATION_TESTS.md

reviewed

··· 1 1 + # Integration Tests 2 2 + 3 3 + This directory contains integration tests for Sunstone that are separate from the unit tests in the parent `tests/` directory. 4 4 + 5 5 + ## Purpose 6 6 + 7 7 + Integration tests verify that different components of the system work together correctly. Unlike unit tests, these tests: 8 8 + 9 9 + - May require external services or APIs 10 10 + - Test complete workflows across multiple modules 11 11 + - May take longer to execute 12 12 + - Test real file I/O and system interactions 13 13 + 14 14 + ## Running Integration Tests 15 15 + 16 16 + ```bash 17 17 + # Run all integration tests 18 18 + make test-integration 19 19 + 20 20 + # Run with coverage 21 21 + make test-integration-cov 22 22 + 23 23 + # Run a specific integration test 24 24 + make test-integration-only TEST=test_example_integration.py 25 25 + 26 26 + # Run all tests (unit + integration) 27 27 + make test-all 28 28 + ``` 29 29 + 30 30 + ## Test Markers 31 31 + 32 32 + Tests can be marked with pytest markers to categorize them: 33 33 + 34 34 + - `@pytest.mark.integration` - General integration test marker 35 35 + - `@pytest.mark.slow` - Tests that take > 5 seconds 36 36 + - `@pytest.mark.requires_api` - Tests requiring external API access 37 37 + - `@pytest.mark.requires_journal` - Tests requiring full journal setup 38 38 + 39 39 + ## Writing Integration Tests 40 40 + 41 41 + 1. Place test files in this directory with `test_` prefix 42 42 + 2. Use the `integration_journal_path` fixture for temporary journal operations 43 43 + 3. Mark tests appropriately with pytest markers 44 44 + 4. Document any special setup requirements in the test docstring 45 45 + 46 46 + ## Example 47 47 + 48 48 + ```python 49 49 + import pytest 50 50 + from pathlib import Path 51 51 + 52 52 + @pytest.mark.integration 53 53 + @pytest.mark.slow 54 54 + def test_complete_workflow(integration_journal_path): 55 55 + """Test the complete capture-to-analysis workflow.""" 56 56 + # Your integration test code here 57 57 + pass 58 58 + ``` 59 59 + 60 60 + ## Exclusion from Default Tests 61 61 + 62 62 + These tests are automatically excluded from `make test` through the `--ignore=tests/integration` flag. They run only when explicitly requested via: 63 63 + 64 64 + - `make test-integration` 65 65 + - `make test-all` 66 66 + - Direct pytest invocation with `pytest tests/integration/`

+50

docs/MUSE.md

reviewed

··· 1 1 + # Muse Module 2 2 + 3 3 + AI agent system and MCP tooling for Sunstone. 4 4 + 5 5 + ## Commands 6 6 + 7 7 + | Command | Purpose | 8 8 + |---------|---------| 9 9 + | `muse-cortex` | Agent orchestration service | 10 10 + | `muse-mcp-tools` | MCP tool server (runs inside Cortex) | 11 11 + | `muse-agents` | Direct agent invocation (testing only) | 12 12 + 13 13 + ## Architecture 14 14 + 15 15 + ``` 16 16 + Cortex (orchestrator) 17 17 + ├── Callosum connection (events) 18 18 + ├── MCP HTTP server (tools) 19 19 + └── Agent subprocess management 20 20 + ↓ 21 21 + Backend runners (openai, google, anthropic, claude) 22 22 + ``` 23 23 + 24 24 + ## Agent Backends 25 25 + 26 26 + | Backend | Module | Features | 27 27 + |---------|--------|----------| 28 28 + | OpenAI | `muse/openai.py` | GPT models via Agents SDK | 29 29 + | Google | `muse/google.py` | Gemini models | 30 30 + | Anthropic | `muse/anthropic.py` | Claude via Anthropic SDK | 31 31 + | Claude | `muse/claude.py` | Claude Code SDK with filesystem tools | 32 32 + 33 33 + All backends implement `AgentSession` with `run()` and `add_history()` methods. 34 34 + 35 35 + ## Key Components 36 36 + 37 37 + - **cortex.py** - Central agent manager, file watcher, event distribution 38 38 + - **cortex_client.py** - Client functions: `cortex_request()`, `cortex_agents()` 39 39 + - **mcp.py** - FastMCP server with journal search tools 40 40 + - **agents.py** - CLI and shared `AgentSession` interface 41 41 + 42 42 + ## Agent Personas 43 43 + 44 44 + System prompts in `muse/agents/*.txt` with metadata in matching `.json` files. Apps can add custom agents in `apps/{app}/agents/`. 45 45 + 46 46 + ## Documentation 47 47 + 48 48 + - [CORTEX.md](CORTEX.md) - Full API, event schemas, request format 49 49 + - [CALLOSUM.md](CALLOSUM.md) - Message bus protocol 50 50 + - [THINK.md](THINK.md) - Cortex usage examples

+43

docs/OBSERVE.md

reviewed

··· 1 1 + # Observe Module 2 2 + 3 3 + Multimodal capture and AI-powered analysis of desktop activity. 4 4 + 5 5 + ## Commands 6 6 + 7 7 + | Command | Purpose | 8 8 + |---------|---------| 9 9 + | `observe-gnome` | Screen and audio capture on Linux/GNOME | 10 10 + | `observe-macos` | Screen and audio capture on macOS | 11 11 + | `observe-transcribe` | Audio transcription with speaker diarization | 12 12 + | `observe-describe` | Visual analysis of screen recordings | 13 13 + | `observe-sense` | Unified observation coordination | 14 14 + 15 15 + ## Architecture 16 16 + 17 17 + ``` 18 18 + observe-gnome/macos (capture) 19 19 + ↓ 20 20 + Raw media files (*.flac, *.webm) 21 21 + ↓ 22 22 + observe-sense (coordination) 23 23 + ├── observe-transcribe → audio.jsonl 24 24 + └── observe-describe → screen.jsonl 25 25 + ``` 26 26 + 27 27 + ## Key Components 28 28 + 29 29 + - **gnome/observer.py**, **macos/observer.py** - Platform-specific capture using native APIs 30 30 + - **sense.py** - File watcher that dispatches transcription and description jobs 31 31 + - **transcribe.py** - Audio processing with Whisper/Rev.ai and pyannote diarization 32 32 + - **describe.py** - Vision analysis with Gemini, category-based prompts 33 33 + - **categories/** - Category-specific prompts for screen content (see [SCREEN_CATEGORIES.md](SCREEN_CATEGORIES.md)) 34 34 + 35 35 + ## Output Formats 36 36 + 37 37 + See [JOURNAL.md](JOURNAL.md) for detailed extract schemas: 38 38 + - Audio transcripts: `audio.jsonl` with speaker turns and timestamps 39 39 + - Screen analysis: `screen.jsonl` with frame-by-frame categorization 40 40 + 41 41 + ## Configuration 42 42 + 43 43 + Requires `JOURNAL_PATH` environment variable. API keys for transcription/vision services configured in `.env`.

+67

docs/SCREEN_CATEGORIES.md

reviewed

··· 1 1 + # Screen Description Categories 2 2 + 3 3 + This directory contains category definitions for vision analysis of screencast frames. 4 4 + 5 5 + ## Adding a New Category 6 6 + 7 7 + Each category requires a `.json` file with metadata, and optionally a `.txt` prompt file for follow-up analysis. 8 8 + 9 9 + ### 1. `<category>.json` (required) 10 10 + 11 11 + Defines the category and its behavior: 12 12 + 13 13 + ```json 14 14 + { 15 15 + "description": "One-line description for categorization prompt", 16 16 + "followup": true, 17 17 + "output": "markdown", 18 18 + "iq": "lite" 19 19 + } 20 20 + ``` 21 21 + 22 22 + | Field | Required | Default | Description | 23 23 + |-------|----------|---------|-------------| 24 24 + | `description` | Yes | - | Single-line description used in the categorization prompt | 25 25 + | `followup` | No | `false` | Whether to run follow-up analysis for this category | 26 26 + | `output` | No | `"markdown"` | Response format: `"json"` or `"markdown"` | 27 27 + | `iq` | No | `"lite"` | Model tier: `"lite"`, `"flash"`, or `"pro"` | 28 28 + 29 29 + ### 2. `<category>.txt` (required if `followup: true`) 30 30 + 31 31 + The vision prompt template sent to the model for detailed analysis. Should instruct the model to: 32 32 + - Analyze the screenshot for this specific category 33 33 + - Return content in the format specified by `output` (markdown or JSON) 34 34 + 35 35 + ### 3. `<category>.py` (optional) 36 36 + 37 37 + Custom formatter for rich markdown output. If not provided, default formatting applies: 38 38 + - Markdown content: displayed with category header 39 39 + - JSON content: displayed in a code block 40 40 + 41 41 + To add a custom formatter, create a `format` function: 42 42 + 43 43 + ```python 44 44 + def format(content: Any, context: dict) -> str: 45 45 + """Format category content to markdown. 46 46 + 47 47 + Args: 48 48 + content: The category content (str for markdown, dict for JSON) 49 49 + context: Dict with: 50 50 + - frame: Full frame dict from JSONL 51 51 + - file_path: Path to JSONL file 52 52 + - timestamp_str: Formatted time like "14:30:22" 53 53 + 54 54 + Returns: 55 55 + Formatted markdown string (empty string to skip) 56 56 + """ 57 57 + # Your formatting logic here 58 58 + return "**Header:**\n\nFormatted content..." 59 59 + ``` 60 60 + 61 61 + ## How It Works 62 62 + 63 63 + 1. `observe/describe.py` discovers all `.json` files and builds the categorization prompt dynamically 64 64 + 2. Initial categorization identifies primary/secondary categories from the screenshot 65 65 + 3. For categories with `followup: true`, a follow-up request extracts detailed content using the `.txt` prompt 66 66 + 4. Results are stored in JSONL under the category name (e.g., `"meeting": {...}`) 67 67 + 5. `observe/screen.py` formats JSONL to markdown, using custom formatters when available

+176

docs/THINK.md

reviewed

··· 1 1 + # sunstone-think 2 2 + 3 3 + Post-processing utilities for clustering and summarising captured data. The tools leverage the Gemini API to analyse transcriptions and screenshots. All commands work with a **journal** directory that holds daily folders in `YYYYMMDD` format. 4 4 + 5 5 + ## Installation 6 6 + 7 7 + ```bash 8 8 + pip install -e . 9 9 + ``` 10 10 + 11 11 + All dependencies are listed in `pyproject.toml`. 12 12 + 13 13 + ## Usage 14 14 + 15 15 + The package exposes several commands: 16 16 + 17 17 + - `think-insight` builds a Markdown summary of a day's recordings using a Gemini prompt. 18 18 + - `think-cluster` groups audio and screen JSON files into report sections. Use `--start` and 19 19 + `--length` to limit the report to a specific time range. 20 20 + - `think-dream` runs the above tools for a single day. 21 21 + - `think-supervisor` monitors observation heartbeats. Use `--no-observers` to skip starting them automatically. 22 22 + - `muse-mcp-tools` starts an MCP server exposing search capabilities for both summary text and raw transcripts. 23 23 + - `muse-cortex` starts a WebSocket API server for managing AI agent instances. 24 24 + 25 25 + ```bash 26 26 + think-insight YYYYMMDD [-f PROMPT] [-p] [-c] [--force] [-v] 27 27 + think-cluster YYYYMMDD [--start HHMMSS --length MINUTES] 28 28 + think-dream [--day YYYYMMDD] [--force] [--rebuild] 29 29 + think-supervisor [--no-observers] 30 30 + muse-mcp-tools [--transport http] [--port PORT] [--path PATH] 31 31 + muse-cortex [--host HOST] [--port PORT] [--path PATH] 32 32 + ``` 33 33 + 34 34 + `-p` is a switch enabling the Gemini Pro model. Use `-c` to count tokens only, 35 35 + `--force` to overwrite existing files and `-v` for verbose logs. 36 36 + 37 37 + Set `GOOGLE_API_KEY` before running any command that contacts Gemini. 38 38 + `JOURNAL_PATH` and `GOOGLE_API_KEY` can also be provided in a `.env` file which 39 39 + is loaded automatically by most commands. 40 40 + 41 41 + ## Service Discovery 42 42 + 43 43 + The MCP HTTP server now runs inside Cortex itself. When Cortex starts it passes 44 44 + the URL directly to each agent request (`mcp_server_url`). Utilities that need 45 45 + tool metadata, such as `think-planner`, query the registered tools directly and 46 46 + no discovery files or environment variables are required. 47 47 + 48 48 + ## Automating daily processing 49 49 + 50 50 + The `think-dream` command can be triggered by a systemd timer. Below is a 51 51 + minimal service and timer that process yesterday's folder every morning at 52 52 + 06:00: 53 53 + 54 54 + ```ini 55 55 + [Unit] 56 56 + Description=Process sunstone journal 57 57 + 58 58 + [Service] 59 59 + Type=oneshot 60 60 + ExecStart=/usr/local/bin/think-dream 61 61 + 62 62 + [Install] 63 63 + WantedBy=multi-user.target 64 64 + ``` 65 65 + 66 66 + ```ini 67 67 + [Unit] 68 68 + Description=Run think-dream daily 69 69 + 70 70 + [Timer] 71 71 + OnCalendar=*-*-* 06:00:00 72 72 + Persistent=true 73 73 + Unit=think-dream.service 74 74 + 75 75 + [Install] 76 76 + WantedBy=timers.target 77 77 + ``` 78 78 + 79 79 + ## Agent System 80 80 + 81 81 + ### Cortex: Central Agent Manager 82 82 + 83 83 + The Cortex service (`muse-cortex`) is the central system for managing AI agent instances. It monitors the journal's `agents/` directory for new requests and manages agent execution. All agent spawning should go through Cortex for proper event tracking and management. 84 84 + 85 85 + To spawn agents programmatically, use the cortex_client functions: 86 86 + 87 87 + ```python 88 88 + from muse.cortex_client import cortex_request 89 89 + from think.callosum import CallosumConnection 90 90 + 91 91 + # Create a request 92 92 + agent_id = cortex_request( 93 93 + prompt="Your task here", 94 94 + persona="default", 95 95 + backend="openai" # or "google", "anthropic", "claude" 96 96 + ) 97 97 + 98 98 + # Watch for agent events via Callosum 99 99 + def on_event(message): 100 100 + # Filter for cortex tract events 101 101 + if message.get('tract') != 'cortex': 102 102 + return 103 103 + 104 104 + print(f"Event: {message['event']}") 105 105 + if message.get('event') == 'finish': 106 106 + print(f"Result: {message.get('result')}") 107 107 + 108 108 + watcher = CallosumConnection(callback=on_event) 109 109 + watcher.connect() 110 110 + # ... later, when done: 111 111 + watcher.close() 112 112 + ``` 113 113 + 114 114 + ### Direct CLI Usage (Testing Only) 115 115 + 116 116 + The `muse-agents` command is primarily used internally by Cortex. For testing purposes, it can be invoked directly: 117 117 + 118 118 + ```bash 119 119 + muse-agents [TASK_FILE] [--backend PROVIDER] [--model MODEL] [--max-tokens N] [-o OUT_FILE] 120 120 + ``` 121 121 + 122 122 + The provider can be ``openai`` (default), ``google`` or ``anthropic``. Set the corresponding API key environment variable (`OPENAI_API_KEY`, 123 123 + `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY`) along with `JOURNAL_PATH`. 124 124 + 125 125 + ### Common interface 126 126 + 127 127 + The `AgentSession` context manager powers all the CLIs. Use 128 128 + `muse.openai.AgentSession`, `muse.google.AgentSession` or 129 129 + `muse.anthropic.AgentSession` depending on the backend. The shared 130 130 + `BaseAgentSession` interface lives in `muse.agents`: 131 131 + 132 132 + ```python 133 133 + async with AgentSession() as agent: 134 134 + agent.add_history("user", "previous message") 135 135 + result = await agent.run("new request") 136 136 + print(agent.history) 137 137 + ``` 138 138 + 139 139 + `run()` returns the final text result. `add_history()` queues prior messages to 140 140 + provide context and `history` exposes all messages seen during the session. The 141 141 + same code works with any implementation, allowing you to choose between OpenAI, 142 142 + Gemini or Claude at runtime. 143 143 + 144 144 + ## Insight map keys 145 145 + 146 146 + `think.utils.get_insights()` reads the prompt files under `think/insights` and 147 147 + returns a dictionary keyed by insight name. Each entry contains: 148 148 + 149 149 + - `path` – the prompt text file path 150 150 + - `color` – UI color hex string 151 151 + - `mtime` – modification time of the `.txt` file 152 152 + - Any additional keys from the matching `<insight>.json` metadata file such as 153 153 + `title`, `description` or `occurrences` 154 154 + 155 155 + ## Cortex API 156 156 + 157 157 + Cortex is the central agent management system that all agent spawning should go through. See [CORTEX.md](CORTEX.md) for complete documentation of the Cortex WebSocket API and agent event structures. 158 158 + 159 159 + ### Using cortex_client 160 160 + 161 161 + The `muse.cortex_client` module provides functions for interacting with Cortex: 162 162 + 163 163 + ```python 164 164 + from muse.cortex_client import cortex_request, cortex_agents 165 165 + 166 166 + # Create an agent request 167 167 + request_file = cortex_request( 168 168 + prompt="Your prompt", 169 169 + persona="default", 170 170 + backend="openai" 171 171 + ) 172 172 + 173 173 + # List running and completed agents 174 174 + agents_info = cortex_agents(limit=10, agent_type="live") 175 175 + print(f"Found {agents_info['live_count']} running agents") 176 176 + ```

+79

docs/VENDOR.md

reviewed

··· 1 1 + # Third-Party Vendor Libraries 2 2 + 3 3 + This directory contains third-party JavaScript libraries used across Sunstone apps. 4 4 + 5 5 + ## Purpose 6 6 + 7 7 + The `vendor/` directory provides: 8 8 + - Centralized location for third-party libraries 9 9 + - Version tracking and documentation 10 10 + - Consistent access pattern for all apps 11 11 + - Local copies for reliability (no CDN dependencies) 12 12 + 13 13 + ## Available Libraries 14 14 + 15 15 + ### marked (v15.0.12) 16 16 + 17 17 + **Purpose**: Markdown parsing and rendering 18 18 + 19 19 + **License**: MIT (included in file header) 20 20 + 21 21 + **Source**: https://github.com/markedjs/marked 22 22 + 23 23 + **CDN Alternative**: `https://cdn.jsdelivr.net/npm/marked/marked.min.js` 24 24 + 25 25 + **Usage in App Templates**: 26 26 + ```html 27 27 + <!-- Using helper function (recommended) --> 28 28 + <script src="{{ vendor_lib('marked') }}"></script> 29 29 + 30 30 + <!-- Using explicit path --> 31 31 + <script src="{{ url_for('static', filename='vendor/marked/marked.min.js') }}"></script> 32 32 + ``` 33 33 + 34 34 + **Example**: 35 35 + ```javascript 36 36 + // Basic markdown rendering 37 37 + const html = marked.parse('# Hello World'); 38 38 + 39 39 + // With options 40 40 + const html = marked.parse(markdown, { 41 41 + breaks: true, // Convert \n to <br> 42 42 + gfm: true, // GitHub Flavored Markdown 43 43 + headerIds: false, // Disable auto-generated header IDs 44 44 + mangle: false // Disable email mangling 45 45 + }); 46 46 + ``` 47 47 + 48 48 + **Currently Used By** (legacy references): 49 49 + - `convey/templates/chat.html` (via `convey/static/marked.min.js`) 50 50 + - `convey/templates/facet_detail.html` (via CDN) 51 51 + - `convey/templates/agents.html` (via CDN) 52 52 + 53 53 + ## Adding New Libraries 54 54 + 55 55 + When adding a new third-party library: 56 56 + 57 57 + 1. **Create subdirectory**: `vendor/{library_name}/` 58 58 + 2. **Add minified file**: Copy production-ready `.min.js` file 59 59 + 3. **Check license**: Ensure license is MIT-compatible and included 60 60 + 4. **Update this manifest**: Add entry with version, purpose, and usage 61 61 + 5. **Test**: Verify library loads and works in development 62 62 + 63 63 + ## Updating Libraries 64 64 + 65 65 + When updating a library version: 66 66 + 67 67 + 1. **Replace file** in vendor directory 68 68 + 2. **Update version** in this manifest 69 69 + 3. **Test all apps**: Check apps listed in "Currently Used By" 70 70 + 4. **Commit**: Use message format: `chore: update {library} to v{version}` 71 71 + 72 72 + ## Guidelines 73 73 + 74 74 + - **Prefer local copies** over CDN for reliability and offline development 75 75 + - **Use minified versions** for production-ready performance 76 76 + - **Include licenses** either in file headers or separate LICENSE files 77 77 + - **Document usage patterns** in this manifest 78 78 + - **Track versions** to enable security updates 79 79 + - **One library per subdirectory** for clean organization

+1

muse/README.md

reviewed

··· 1 1 + ../docs/MUSE.md

+1

observe/README.md

reviewed

··· 1 1 + ../docs/OBSERVE.md

+1 -67

observe/categories/README.md

reviewed

··· 1 1 - # Screen Description Categories 2 2 - 3 3 - This directory contains category definitions for vision analysis of screencast frames. 4 4 - 5 5 - ## Adding a New Category 6 6 - 7 7 - Each category requires a `.json` file with metadata, and optionally a `.txt` prompt file for follow-up analysis. 8 8 - 9 9 - ### 1. `<category>.json` (required) 10 10 - 11 11 - Defines the category and its behavior: 12 12 - 13 13 - ```json 14 14 - { 15 15 - "description": "One-line description for categorization prompt", 16 16 - "followup": true, 17 17 - "output": "markdown", 18 18 - "iq": "lite" 19 19 - } 20 20 - ``` 21 21 - 22 22 - | Field | Required | Default | Description | 23 23 - |-------|----------|---------|-------------| 24 24 - | `description` | Yes | - | Single-line description used in the categorization prompt | 25 25 - | `followup` | No | `false` | Whether to run follow-up analysis for this category | 26 26 - | `output` | No | `"markdown"` | Response format: `"json"` or `"markdown"` | 27 27 - | `iq` | No | `"lite"` | Model tier: `"lite"`, `"flash"`, or `"pro"` | 28 28 - 29 29 - ### 2. `<category>.txt` (required if `followup: true`) 30 30 - 31 31 - The vision prompt template sent to the model for detailed analysis. Should instruct the model to: 32 32 - - Analyze the screenshot for this specific category 33 33 - - Return content in the format specified by `output` (markdown or JSON) 34 34 - 35 35 - ### 3. `<category>.py` (optional) 36 36 - 37 37 - Custom formatter for rich markdown output. If not provided, default formatting applies: 38 38 - - Markdown content: displayed with category header 39 39 - - JSON content: displayed in a code block 40 40 - 41 41 - To add a custom formatter, create a `format` function: 42 42 - 43 43 - ```python 44 44 - def format(content: Any, context: dict) -> str: 45 45 - """Format category content to markdown. 46 46 - 47 47 - Args: 48 48 - content: The category content (str for markdown, dict for JSON) 49 49 - context: Dict with: 50 50 - - frame: Full frame dict from JSONL 51 51 - - file_path: Path to JSONL file 52 52 - - timestamp_str: Formatted time like "14:30:22" 53 53 - 54 54 - Returns: 55 55 - Formatted markdown string (empty string to skip) 56 56 - """ 57 57 - # Your formatting logic here 58 58 - return "**Header:**\n\nFormatted content..." 59 59 - ``` 60 60 - 61 61 - ## How It Works 62 62 - 63 63 - 1. `observe/describe.py` discovers all `.json` files and builds the categorization prompt dynamically 64 64 - 2. Initial categorization identifies primary/secondary categories from the screenshot 65 65 - 3. For categories with `followup: true`, a follow-up request extracts detailed content using the `.txt` prompt 66 66 - 4. Results are stored in JSONL under the category name (e.g., `"meeting": {...}`) 67 67 - 5. `observe/screen.py` formats JSONL to markdown, using custom formatters when available 1 1 + ../../docs/SCREEN_CATEGORIES.md

+1 -66

tests/integration/README.md

reviewed

··· 1 1 - # Integration Tests 2 2 - 3 3 - This directory contains integration tests for Sunstone that are separate from the unit tests in the parent `tests/` directory. 4 4 - 5 5 - ## Purpose 6 6 - 7 7 - Integration tests verify that different components of the system work together correctly. Unlike unit tests, these tests: 8 8 - 9 9 - - May require external services or APIs 10 10 - - Test complete workflows across multiple modules 11 11 - - May take longer to execute 12 12 - - Test real file I/O and system interactions 13 13 - 14 14 - ## Running Integration Tests 15 15 - 16 16 - ```bash 17 17 - # Run all integration tests 18 18 - make test-integration 19 19 - 20 20 - # Run with coverage 21 21 - make test-integration-cov 22 22 - 23 23 - # Run a specific integration test 24 24 - make test-integration-only TEST=test_example_integration.py 25 25 - 26 26 - # Run all tests (unit + integration) 27 27 - make test-all 28 28 - ``` 29 29 - 30 30 - ## Test Markers 31 31 - 32 32 - Tests can be marked with pytest markers to categorize them: 33 33 - 34 34 - - `@pytest.mark.integration` - General integration test marker 35 35 - - `@pytest.mark.slow` - Tests that take > 5 seconds 36 36 - - `@pytest.mark.requires_api` - Tests requiring external API access 37 37 - - `@pytest.mark.requires_journal` - Tests requiring full journal setup 38 38 - 39 39 - ## Writing Integration Tests 40 40 - 41 41 - 1. Place test files in this directory with `test_` prefix 42 42 - 2. Use the `integration_journal_path` fixture for temporary journal operations 43 43 - 3. Mark tests appropriately with pytest markers 44 44 - 4. Document any special setup requirements in the test docstring 45 45 - 46 46 - ## Example 47 47 - 48 48 - ```python 49 49 - import pytest 50 50 - from pathlib import Path 51 51 - 52 52 - @pytest.mark.integration 53 53 - @pytest.mark.slow 54 54 - def test_complete_workflow(integration_journal_path): 55 55 - """Test the complete capture-to-analysis workflow.""" 56 56 - # Your integration test code here 57 57 - pass 58 58 - ``` 59 59 - 60 60 - ## Exclusion from Default Tests 61 61 - 62 62 - These tests are automatically excluded from `make test` through the `--ignore=tests/integration` flag. They run only when explicitly requested via: 63 63 - 64 64 - - `make test-integration` 65 65 - - `make test-all` 66 66 - - Direct pytest invocation with `pytest tests/integration/` 1 1 + ../../docs/INTEGRATION_TESTS.md

+1 -176

think/README.md

reviewed

··· 1 1 - # sunstone-think 2 2 - 3 3 - Post-processing utilities for clustering and summarising captured data. The tools leverage the Gemini API to analyse transcriptions and screenshots. All commands work with a **journal** directory that holds daily folders in `YYYYMMDD` format. 4 4 - 5 5 - ## Installation 6 6 - 7 7 - ```bash 8 8 - pip install -e . 9 9 - ``` 10 10 - 11 11 - All dependencies are listed in `pyproject.toml`. 12 12 - 13 13 - ## Usage 14 14 - 15 15 - The package exposes several commands: 16 16 - 17 17 - - `think-insight` builds a Markdown summary of a day's recordings using a Gemini prompt. 18 18 - - `think-cluster` groups audio and screen JSON files into report sections. Use `--start` and 19 19 - `--length` to limit the report to a specific time range. 20 20 - - `think-dream` runs the above tools for a single day. 21 21 - - `think-supervisor` monitors observation heartbeats. Use `--no-observers` to skip starting them automatically. 22 22 - - `muse-mcp-tools` starts an MCP server exposing search capabilities for both summary text and raw transcripts. 23 23 - - `muse-cortex` starts a WebSocket API server for managing AI agent instances. 24 24 - 25 25 - ```bash 26 26 - think-insight YYYYMMDD [-f PROMPT] [-p] [-c] [--force] [-v] 27 27 - think-cluster YYYYMMDD [--start HHMMSS --length MINUTES] 28 28 - think-dream [--day YYYYMMDD] [--force] [--rebuild] 29 29 - think-supervisor [--no-observers] 30 30 - muse-mcp-tools [--transport http] [--port PORT] [--path PATH] 31 31 - muse-cortex [--host HOST] [--port PORT] [--path PATH] 32 32 - ``` 33 33 - 34 34 - `-p` is a switch enabling the Gemini Pro model. Use `-c` to count tokens only, 35 35 - `--force` to overwrite existing files and `-v` for verbose logs. 36 36 - 37 37 - Set `GOOGLE_API_KEY` before running any command that contacts Gemini. 38 38 - `JOURNAL_PATH` and `GOOGLE_API_KEY` can also be provided in a `.env` file which 39 39 - is loaded automatically by most commands. 40 40 - 41 41 - ## Service Discovery 42 42 - 43 43 - The MCP HTTP server now runs inside Cortex itself. When Cortex starts it passes 44 44 - the URL directly to each agent request (`mcp_server_url`). Utilities that need 45 45 - tool metadata, such as `think-planner`, query the registered tools directly and 46 46 - no discovery files or environment variables are required. 47 47 - 48 48 - ## Automating daily processing 49 49 - 50 50 - The `think-dream` command can be triggered by a systemd timer. Below is a 51 51 - minimal service and timer that process yesterday's folder every morning at 52 52 - 06:00: 53 53 - 54 54 - ```ini 55 55 - [Unit] 56 56 - Description=Process sunstone journal 57 57 - 58 58 - [Service] 59 59 - Type=oneshot 60 60 - ExecStart=/usr/local/bin/think-dream 61 61 - 62 62 - [Install] 63 63 - WantedBy=multi-user.target 64 64 - ``` 65 65 - 66 66 - ```ini 67 67 - [Unit] 68 68 - Description=Run think-dream daily 69 69 - 70 70 - [Timer] 71 71 - OnCalendar=*-*-* 06:00:00 72 72 - Persistent=true 73 73 - Unit=think-dream.service 74 74 - 75 75 - [Install] 76 76 - WantedBy=timers.target 77 77 - ``` 78 78 - 79 79 - ## Agent System 80 80 - 81 81 - ### Cortex: Central Agent Manager 82 82 - 83 83 - The Cortex service (`muse-cortex`) is the central system for managing AI agent instances. It monitors the journal's `agents/` directory for new requests and manages agent execution. All agent spawning should go through Cortex for proper event tracking and management. 84 84 - 85 85 - To spawn agents programmatically, use the cortex_client functions: 86 86 - 87 87 - ```python 88 88 - from muse.cortex_client import cortex_request 89 89 - from think.callosum import CallosumConnection 90 90 - 91 91 - # Create a request 92 92 - agent_id = cortex_request( 93 93 - prompt="Your task here", 94 94 - persona="default", 95 95 - backend="openai" # or "google", "anthropic", "claude" 96 96 - ) 97 97 - 98 98 - # Watch for agent events via Callosum 99 99 - def on_event(message): 100 100 - # Filter for cortex tract events 101 101 - if message.get('tract') != 'cortex': 102 102 - return 103 103 - 104 104 - print(f"Event: {message['event']}") 105 105 - if message.get('event') == 'finish': 106 106 - print(f"Result: {message.get('result')}") 107 107 - 108 108 - watcher = CallosumConnection(callback=on_event) 109 109 - watcher.connect() 110 110 - # ... later, when done: 111 111 - watcher.close() 112 112 - ``` 113 113 - 114 114 - ### Direct CLI Usage (Testing Only) 115 115 - 116 116 - The `muse-agents` command is primarily used internally by Cortex. For testing purposes, it can be invoked directly: 117 117 - 118 118 - ```bash 119 119 - muse-agents [TASK_FILE] [--backend PROVIDER] [--model MODEL] [--max-tokens N] [-o OUT_FILE] 120 120 - ``` 121 121 - 122 122 - The provider can be ``openai`` (default), ``google`` or ``anthropic``. Set the corresponding API key environment variable (`OPENAI_API_KEY`, 123 123 - `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY`) along with `JOURNAL_PATH`. 124 124 - 125 125 - ### Common interface 126 126 - 127 127 - The `AgentSession` context manager powers all the CLIs. Use 128 128 - `muse.openai.AgentSession`, `muse.google.AgentSession` or 129 129 - `muse.anthropic.AgentSession` depending on the backend. The shared 130 130 - `BaseAgentSession` interface lives in `muse.agents`: 131 131 - 132 132 - ```python 133 133 - async with AgentSession() as agent: 134 134 - agent.add_history("user", "previous message") 135 135 - result = await agent.run("new request") 136 136 - print(agent.history) 137 137 - ``` 138 138 - 139 139 - `run()` returns the final text result. `add_history()` queues prior messages to 140 140 - provide context and `history` exposes all messages seen during the session. The 141 141 - same code works with any implementation, allowing you to choose between OpenAI, 142 142 - Gemini or Claude at runtime. 143 143 - 144 144 - ## Insight map keys 145 145 - 146 146 - `think.utils.get_insights()` reads the prompt files under `think/insights` and 147 147 - returns a dictionary keyed by insight name. Each entry contains: 148 148 - 149 149 - - `path` – the prompt text file path 150 150 - - `color` – UI color hex string 151 151 - - `mtime` – modification time of the `.txt` file 152 152 - - Any additional keys from the matching `<insight>.json` metadata file such as 153 153 - `title`, `description` or `occurrences` 154 154 - 155 155 - ## Cortex API 156 156 - 157 157 - Cortex is the central agent management system that all agent spawning should go through. See [CORTEX.md](/CORTEX.md) for complete documentation of the Cortex WebSocket API and agent event structures. 158 158 - 159 159 - ### Using cortex_client 160 160 - 161 161 - The `muse.cortex_client` module provides functions for interacting with Cortex: 162 162 - 163 163 - ```python 164 164 - from muse.cortex_client import cortex_request, cortex_agents 165 165 - 166 166 - # Create an agent request 167 167 - request_file = cortex_request( 168 168 - prompt="Your prompt", 169 169 - persona="default", 170 170 - backend="openai" 171 171 - ) 172 172 - 173 173 - # List running and completed agents 174 174 - agents_info = cortex_agents(limit=10, agent_type="live") 175 175 - print(f"Found {agents_info['live_count']} running agents") 176 176 - ``` 1 1 + ../docs/THINK.md