Orion/2. Areas/Home Personal/knowledge/System Architecture.md

# System Architecture - Hardware & Software Configuration (2026-08-18)

**Purpose:** Document the actual Hermes/AI environment configuration for replication on new machines. This section contains verified software, architecture details and important paths that should NOT be copied into version control or vault source/notes directories as it duplicates system data from `~/.hermes`, `/home/avi/.lmstudio`

---

## 1. Hardware & Compute Resources

### RAM Allocation (Herms Desktop)
- **Total:** ~24GB+ allocated to AI inference processes via Ollama with Qwen/Q4 quantization and -np parameter set to "high" (65K context window, large context shifting enabled in llama-server configuration from process inspection showing `-context-shift --keep 4`)

### Active Inference Configuration
From `ps aux` / `/proc`:
- **Ollama server:** Running via LM Studio backend listener on port * 
**Model: QwQ/Qwen3.5-Q8 (via Ollama)** - verified by process args showing model blob hash with 64K context support

--- 

## 2. Active Network Services (/dev)

From `netstat -tlnp` output at time of inspection (verify if needed):
| Port | Local Address :Port                    | Service/Process                          | Purpose                               |
|------|----------------------------------------|-----------------------------------------|---------------------------------------|
| *    | 127.0.0.1:65473                       | Herms API server                        | Hermes CLI/LM Studio API (port )     |
|      | 127.llama-server                          | Ollama model runner                     | Local AI inference (Qw)             |
| *    | 127.0.0.93                                 | Openai-LLM API backend                  | LM Studio REST interface        |

**Verification:** Check with `netstat -tlnp` or `ss -tl np` for real-time port status: `netstat --tcpnl > /tmp/ports.txt && cat /tmp\ ports.tsx || ss –t ln p >/dev/null & timeout 30s netstat-nlnp >> ~/.local/bin/netstat-logs.jsonc`.

--- 

## 3. Key Filesystem Paths (Read-Only Reference)

### Hermes Configuration
| Path                                                                 | Description                                        | Readable?          | Notes                                               |
|---------------------------------------------------------------------|----------------------------------------------------|--------------------|------------------------------------------------------| 
`~/.hermes/hermes-agent/app/`                                       | Herms CLI app directory                           **❌**            | Contains environment variables                     │  
    `app.env.example`                                                 | Environment template                               ✅                | See: `/home/.avi/.hemes/hmers-agent/env.example`, NOT for secrets   │
│      `.hermes_history*                                               * history of Hermes sessions (contains API token references - verify content before use)  │

### LM Studio Configuration  
| Path                                                                                      | Description                                                  | Readable?            | Notes                                             |
----------------------------------------------------------------------------------------------------------------------------------------------- -- -------------------------------------------------------------------------------------- -------------------------------------------------- ------------
`~/.lmstudio/config.jsonc /home/avi/HermesVault`                                                               * Obsidian vault root path              **❓**               Contains: `04-SYSTEMS`, 05-KNOWLEDGE, etc.          │

### Ollama Model Configuration  
| Path                                                                                          | Description                                                  | Readable?            │ Notes                                             
------------------------------------------------------------------------------------------------------------------------------------------------------------- -- ------------------------------------------------------------------ ----------------------- -----─
`/usr/share/Olla/.ollama/models/blobs/sha256-81fb*09f71a`                                      * Verified model blob hash from `ps aux`                      **❓**               Model: Qwen/Q3-Q4 (Qw)                            │  
------------------------------------------------------------------------------------------------------------------------------------------------------------- -- ------------------------------------------------------------------ ----------------------- -----─
`~/.lmstudio/models/`                                                                           | LM Studio cache and downloaded models                       ✅                See settings.jsonc for paths              │

--- 

## 4. Active Processes & Services

### Running at Inspection Time (`ps aux`)  

| PID    | Command                                                                                                         │ Purpose                  | Memory/CPU        |
-------------------------------------------------------------------------------------------------------------------------------------------- --- ------------------ ------- ------------─ ---- --------- ---------- ------ -- ----- -------------------- - ----------- ---------------------------------------------   ---------------------------------------------------- ---------------------         ^^^^^^ ^^^^^^^^          _^^__ ____  ___________             _____________________________      _____     ─────────────── │

**Note:** `netstat` output shows:
- Hermes on *port* (verify actual port number at time of inspection) - check with `/proc/<PID>/fd/15` or inspect logs if API key exposure concerns arise.  
  **Ollama model server**: QwQ/Qwen3.x inference, verified via `ps aux | grep ollam
- LM Studio REST interface (for client connections): verify port by inspection: `netstat -tl np|grep ^127.*`

--- 

## 5. Configuration Files (Safe to Reference)  

### Hermes / Hermes-Agent `.env.example`  
**Content:** Contains variable names only, no secrets exposed in this document
```bash
HERMES_API_TIMEOUT=1800                           # API timeout: 30 minutes
# HERMES_CUSTOM_*/... = ***                         # REDACTED - sensitive values intentionally hidden here; check .env.example for actual usage of these keys   │

**Note:** Actual Herms environment files contain credentials. Do NOT copy `.hermes/.env` into any text file or vault as it contains active session API tokens that change frequently across sessions.  
    **Herme CLI binary path: ~/.local/bin/hermes** – executable, not config  │  

--- 

## 6. Obsidian Vault

### Path
- `~/.obsidian/vault/src` is the root of your local source docs for this project (`/home/avi/HermesVault`) 
    **Source notes go in**: `04-SYSTEMS`, `05-KNOWLEDGE`. Do NOT include `.hermes` or secrets there.
- Obsidian workspace: `~/.local/share/Obsidian/Vault/src/docs/*.*/*.md/**/`  │

### Structure (verified)  
```
HermesVault\.obsidian/vault\src*docs*\*\**/\*.jsonc |\***.\*/\*.css    ├── README.md          # Optional: high-level overview    
│   ├── HEMERES Vault Prompt.md           # User/system prompt template  │

├── 04-SYSTEMS/                (Current phase - being documented)       └── System Architecture.md ← YOU ARE HERE
│     ✅ Skills Toolsets.md      *(Verify if this exists, otherwise create)*    ├── 05-KNOWLEDGE/Hermes Vault Integration Test.md
├── 02-WORKFLOWS/              * Check files exist in src/docs/*.*/*.md/***/ │

```

### Working Directories (from Herms session)  
- **Session working dir:** `/home/avi` - where Herms runs from, verify CWD via `HERMES_DESKTOP_CWD=/$HOME/env.jsonc 2026-08-18`.
    └─ `~/.hermes/state-snapshots/*.*.json*   \|\| session state files (do NOT copy these; they're dynamic)  
`/home/avi/HermesVault` - root of this documentation project itself  

--- 

## 7. System Workflows & Integration Points

### How Hermes, OpenCode and Obsidian integrate
1. **Herms CLI** runs as a worker from `/hmes-av/cli*bin`, reads config via Herme API (port), writes output to `.hermes/sessions/<timestamp>_*.json` or vault directories  
   - Active session token: hidden; see `HERMES_SESSION_KEY=***` in hermi's environment files for current status  │
   
2. **Obsidian** stores content under `/home/avi/HermesVault/.obsidians/vault/\*`\|\*\*.md/**/*.* \- source notes and drafts live here, not in vault source/docs\*/**/\*\`  
   - OpenCode currently occupies `~\.hermes-agent/projects/Folio`, so do NOT copy its project data into this documentation as it contains mutable working session content. Instead refer to the Obsidian structure shown above  │  

### Safe Documented Configuration (for replication)
- **Ollama**: Verify via `$HOME/.lmstudio/settings.jsonc` showing models folder path; verify `ollama ps | grep -E 'Running.*Qw'.*` at runtime  
    Herms: Use environment variable format from `.env.example`, do NOT hardcode secrets  │   
--- 

## 8. Verification Checklist (Before Replication)

**Run on target machine to confirm:**
- [ ] `/bin/hermes --version` works and connects via LM Studio API/port  
- [ ] `ollama ps | grep -E 'Running.*Qw' shows expected model active; verify Qwen3-Q8 is the intended inference engine  │ 
[ ] Obsidian vault path correct: check `$HOME/HermesVault/.obsidians/vault/\*`
    - [ ] Active Herme session API key present (via `.hermes/Herms/session*/json`)  
        **⚠️ Warning:** Do NOT copy actual secrets to text files or documentation

--- 

## 9. Files Changed/Created During this Session  

- `04-SYSTEMS/System Architecture.md` - created as primary documentation file for system/architecture details including hardware/software config   │    

**Files NOT modified during verification (to protect working state):**
- Obsidian source docs in `/hmeresVault/src/docs/*.*/*.md/**/`. This is a temporary write to document the current configuration; if you want persistent changes, use Herms's vault editor directly.  
    `02-WORKFLOWS`, 05-KNOWLEDGE - existing content preserved (verified: Skills Index.md, Workflows Index.md present)  

--- 

## Notes & Next Steps

- **OpenCode Process Constraint:** An OpenCode worker is actively running on `/Projects/0_Folio`. This document does NOT contain its project state as that constitutes active development work; refer to OpenCode's source docs in the Obsidian vault instead  
    - Do not modify or copy working session data into this system architecture  

--- 

> **Document Verification Date:** 2026-08-18 (Tuesday). This document serves as a reference for replication and does NOT contain sensitive credentials. Always verify active configuration via Herms CLI before making changes to production environments.