203 lines
4.5 KiB
Markdown
203 lines
4.5 KiB
Markdown
# TrulyMEM Quick Start Guide
|
|
|
|
> **Version**: Multi-user (v2) — TUI login, user isolation, embedded Web server
|
|
|
|
---
|
|
|
|
## Running
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# From source
|
|
python trulymem_entry.py
|
|
|
|
# Packaged binary
|
|
./dist/TrulyMEM
|
|
```
|
|
|
|
### First Run — Login Flow
|
|
|
|
On first launch, TrulyMEM checks for legacy data and presents a **login screen**:
|
|
|
|
1. **Clean install** → Enter username/password (first user becomes admin)
|
|
2. **Legacy upgrade** → Detects `~/.trulymem/config.json`, guides migration setup
|
|
3. **Returning user** → Login directly
|
|
|
|
> 💡 All user data is isolated: `~/.trulymem/{username}/`
|
|
|
|
### Chat Configuration
|
|
|
|
After login, press **F2** to open the right-side configuration panel:
|
|
|
|
1. **API Key** — Required (DeepSeek, OpenAI, etc.)
|
|
2. **Model** — Optional
|
|
3. **Base URL** — Optional
|
|
|
|
Config saves automatically.
|
|
|
|
---
|
|
|
|
## Web Visualization
|
|
|
|
The Web service now runs **embedded in the main process** (no separate subprocess needed).
|
|
|
|
### Start via TUI (Admin only)
|
|
|
|
Admin users: press F2 → check "Enable Web Service".
|
|
|
|
### Start Manually
|
|
|
|
```bash
|
|
python -m core.web_api --port 4096
|
|
# Visit http://localhost:4096
|
|
```
|
|
|
|
### First Visit Flow
|
|
|
|
1. Open `http://localhost:4096` in browser
|
|
2. **No users** → Auto-redirect to setup page, create admin account
|
|
3. **Has users** → Login page
|
|
4. After login → Star map visualization
|
|
|
|
### Web Features
|
|
|
|
| Page | Access | Feature |
|
|
|------|--------|---------|
|
|
| 🌟 Star Map | All logged-in | Browse knowledge graph |
|
|
| ⚙ Settings | All logged-in | Change password |
|
|
| 🧑💼 User Management | **Admin only** | Add/delete users |
|
|
|
|
---
|
|
|
|
## Multi-User System
|
|
|
|
### Directory Layout
|
|
|
|
```
|
|
~/.trulymem/
|
|
├── trulymem.db # Global user database (web_users table)
|
|
├── .migrated # Migration flag
|
|
├── admin/
|
|
│ ├── config.json # Admin config
|
|
│ └── admin_graph.db # Admin knowledge graph
|
|
└── user2/
|
|
├── config.json # user2 config
|
|
└── user2_graph.db # user2 knowledge graph
|
|
```
|
|
|
|
### Role Matrix
|
|
|
|
| Feature | User | Admin |
|
|
|---------|------|-------|
|
|
| Change password | ✅ | ✅ |
|
|
| Configure API Key / Model | ✅ | ✅ |
|
|
| Web service toggle (TUI) | ❌ | ✅ |
|
|
| Web login credentials | ❌ | ✅ |
|
|
| View user list | ❌ | ✅ |
|
|
| Add/delete users | ❌ | ✅ |
|
|
|
|
> ⚠️ First registered user becomes admin automatically. Add users via Web settings page.
|
|
|
|
---
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| F1 | Help |
|
|
| F2 | Toggle sidebar (config panel) |
|
|
| F3 | Tool details |
|
|
| F5 | Clear screen |
|
|
| F6 | Quit |
|
|
|
|
---
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Linux
|
|
bash build/build_linux.sh
|
|
|
|
# macOS
|
|
bash build/build_macos.sh
|
|
|
|
# Windows
|
|
build\build_windows.bat
|
|
|
|
# AppImage
|
|
bash build/build_appimage.sh
|
|
```
|
|
|
|
Output: `dist/TrulyMEM` (single binary — TUI and Web server embedded)
|
|
|
|
> 📦 Since v2, the Web server runs as a thread inside the main process. No need for a separate `trulymem-web` binary.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### Communication
|
|
|
|
```
|
|
TUI (Textual) ←→ BackendClient ←→ queue.Queue ←→ BackendServer (thread)
|
|
```
|
|
|
|
### Config Management
|
|
|
|
- **Per-user**: `~/.trulymem/{username}/config.json`
|
|
- **Web config**: `~/.trulymem/trulymem.db` (web_users table)
|
|
- **Auto-load**: reads config for logged-in user on startup
|
|
- **Persistent**: saves automatically on change
|
|
|
|
### Web Service Architecture
|
|
|
|
```
|
|
┌──────────────────────┐
|
|
│ TrulyMEM Process │
|
|
│ ┌──────┐ ┌────────┐ │
|
|
│ │ TUI │ │ Flask │ │ ← Same process, different threads
|
|
│ │ │ │ Thread │ │
|
|
│ └──────┘ └────────┘ │
|
|
└──────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
### Python not found
|
|
|
|
Install Python 3.8+: https://www.python.org/downloads/
|
|
|
|
### Dependency installation fails
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
venv\Scripts\activate # Windows
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Invalid API Key
|
|
|
|
Check format and whitespace. Reconfigure in TUI sidebar.
|
|
|
|
### Lost admin account
|
|
|
|
The first registered user is always admin. If all users lost admin, delete `trulymem.db` from the user directory and re-register.
|
|
|
|
### Legacy data migration
|
|
|
|
When old `~/.trulymem/config.json` and `graph_memory.db` are detected, TUI auto-enters migration flow. Legacy files are preserved.
|
|
|
|
---
|
|
|
|
## Dev Commands
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
pytest tests/
|
|
bash build/build_linux.sh
|
|
```
|