personal memory agent
1# solstone-convey
2
3Web-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
5## Installation
6
7```bash
8make install
9```
10
11## Usage
12
13Run the server with:
14
15```bash
16convey
17```
18
19### Authentication
20
21Password authentication is configured via the CLI:
22
23```bash
24sol password set
25```
26
27When a password is set, it is stored as a secure hash in `config/journal.json` under `convey.password_hash`.
28
29If no password is set, the login page will prompt you to run `sol password set`.
30
31## Architecture
32
33Convey 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.
34
35```
36convey/
37 __init__.py - Flask app factory, app registry, context processors
38 state.py - global state (journal_root)
39 bridge.py - Callosum WebSocket bridge for real-time events
40 utils.py - shared helpers (format_date, spawn_agent, etc.)
41 views/
42 __init__.py - blueprint registration
43 home.py - authentication (login/logout) and root redirect
44 templates/
45 app.html - main app container template
46 menu_bar.html - dynamic left sidebar menu
47 status_pane.html - WebSocket status indicator
48 login.html - login page
49 macros.html - Jinja macros
50 static/ - shared CSS and JavaScript
51 app.css - app system styles
52 app.js - facet pills, services, notification center
53 websocket.js - WebSocket connection handler
54 error-handler.js - global error handling
55 colors.js - color palette
56 vendor/ - third-party libraries (marked.js)
57
58apps/ - App plugin directory (see APPS.md)
59 {app_name}/
60 app.json - metadata (icon, label)
61 routes.py - Flask blueprint with routes
62 workspace.html - main UI template
63 background.html - (optional) background service script
64```
65
66### App System
67
68All functional views are implemented as apps in `/apps/`. Each app:
69- Has its own directory with `app.json`, `routes.py`, and `workspace.html`
70- Uses blueprint name `app:{name}` with URL prefix `/app/{name}/`
71- Is automatically discovered and registered by `AppRegistry`
72- Can provide facet-scoped views and background services
73
74Browse `/apps/` to see available apps.
75
76### Core Routes
77
78The `convey/views/home.py` module provides essential routes:
79
80- `/` - Redirects to `/app/home/`
81- `/login` - Authentication page
82- `/logout` - Clear session and redirect to login
83- `/favicon.ico` - Serve favicon
84
85All functional views are accessed at `/app/{name}/` URLs.
86
87### Adding a New App
88
89See [APPS.md](APPS.md) for detailed instructions on creating new apps.