@intent-systems/nexus 2026.1.5-5 → 2026.1.5-8

package/skills/guides/onboarding/docs/canonical/03_STATE_ARCHITECTURE.md

@@ -0,0 +1,357 @@
+# State Architecture
+
+> File paths, schemas, and storage conventions.
+
+---
+
+## Directory Structure
+
+```
+~/nexus/
+├── AGENTS.md                         # Root agent instructions
+├── .cursor/rules                     # Cursor-specific config
+├── .cursor/hooks.json                # Cursor hooks config
+│   └── hooks/                        # Hook scripts
+│       └── nexus-session-start.js
+│
+├── skills/                           # Skill definitions (curated + managed)
+│   ├── tools/{name}/
+│   │   ├── SKILL.md
+│   │   ├── scripts/
+│   │   └── references/
+│   ├── connectors/{name}/
+│   │   ├── SKILL.md
+│   │   ├── scripts/
+│   │   └── references/
+│   ├── guides/{name}/
+│   │   ├── SKILL.md
+│   │   ├── scripts/
+│   │   └── references/
+│   └── managed/{slug}/               # Hub-installed skills
+│
+├── state/                            # All runtime state
+│   ├── user/
+│   │   └── IDENTITY.md
+│   │
+│   ├── agents/
+│   │   └── {name}/
+│   │       ├── IDENTITY.md
+│   │       ├── SOUL.md
+│   │       └── MEMORY.md
+│   │
+│   ├── credentials/
+│   │   ├── index.json
+│   │   └── {service}/
+│   │       ├── config.json           # Optional: shared config (OAuth client)
+│   │       └── accounts/
+│   │           └── {account}/
+│   │               └── auth/
+│   │                   └── {type}.json
+│   │
+│   ├── skills/
+│   │   └── {name}/
+│   │       ├── state.json
+│   │       └── usage.log
+│   │
+│   └── nexus/
+│       ├── config.json               # Workspace config
+│       └── workspace.json            # OS, platform info
+│
+└── home/                             # User's personal space
+    ├── memory/                       # Daily logs
+    │   └── YYYY-MM-DD.md
+    └── projects/                     # User's repos
+```
+
+---
+
+## Cursor Hooks
+
+Nexus uses Cursor's sessionStart hook to inject identity and memory into the
+agent context before the first response.
+
+**Paths:**
+- `.cursor/hooks.json`
+- `.cursor/hooks/nexus-session-start.js`
+
+See `07_AGENT_BINDINGS.md` for the full binding flow.
+
+---
+
+## Identity Files
+
+### User Profile
+
+**Path:** `state/user/IDENTITY.md`
+
+```markdown
+# User Profile
+
+## Identity
+- **Name**: Tyler
+- **Timezone**: America/Chicago
+
+## Preferences
+- Communication style: direct
+- Notification preference: minimal
+
+## Context
+- Developer (TypeScript, Go)
+- Projects: nexus, eve, comms
+```
+
+### Agent Identity
+
+**Path:** `state/agents/{name}/IDENTITY.md`
+
+```markdown
+# Agent Identity
+
+- **Name**: Echo
+- **Nature**: Owl companion
+- **Emoji**: 🦉
+- **Created**: 2026-01-12
+```
+
+### Agent Soul
+
+**Path:** `state/agents/{name}/SOUL.md`
+
+```markdown
+# Agent Soul
+
+## Personality
+- Casual and friendly
+- Slightly snarky
+- Direct, not verbose
+
+## Values
+- Honesty over comfort
+- Ask before major actions
+- Protect user privacy
+
+## Boundaries
+- Never exfiltrate data
+- Ask before external actions
+```
+
+### Agent Memory
+
+**Path:** `state/agents/{name}/MEMORY.md`
+
+```markdown
+# Long-term Memory
+
+## Important Facts
+- User prefers raw SQL over ORMs
+- User's mom is named [name]
+
+## Lessons Learned
+- [Date]: Learned that...
+
+## Active Projects
+- nexus CLI development
+```
+
+---
+
+## Credential Storage
+
+### Design Principles
+
+1. **No plaintext secrets** - Credentials link to secure storage (Keychain, 1Password)
+2. **Service → Account → Auth** hierarchy
+3. **Account = real identifier** - Email or username, not "personal"
+
+### Index File
+
+**Path:** `state/credentials/index.json`
+
+Fast lookup cache. CLI rebuilds from tree if needed.
+
+```json
+{
+  "version": 1,
+  "lastUpdated": "2026-01-14T10:00:00Z",
+  "services": {
+    "google": {
+      "type": "oauth-provider",
+      "accounts": [
+        { "id": "tyler@gmail.com", "auths": ["oauth"] }
+      ]
+    },
+    "anthropic": {
+      "type": "llm-provider",
+      "accounts": [
+        { "id": "tyler@anthropic.com", "auths": ["api-key"] }
+      ]
+    }
+  }
+}
+```
+
+### Credential File
+
+**Path:** `state/credentials/{service}/accounts/{account}/auth/{type}.json`
+
+```json
+{
+  "type": "api-key",
+  "service": "anthropic",
+  "account": "tyler@anthropic.com",
+  "created": "2026-01-12T10:00:00Z",
+  "lastVerified": "2026-01-14T10:00:00Z",
+  
+  "storage": {
+    "provider": "keychain",
+    "command": "security find-generic-password -s nexus.anthropic.tyler@anthropic.com -a api_key -w"
+  }
+}
+```
+
+### Storage Providers
+
+| Provider | Platform | Notes |
+|----------|----------|-------|
+| `keychain` | macOS | Default. Uses `security` command |
+| `1password` | All | Requires `op` CLI |
+| `env` | All | Reads from environment variable |
+| `external` | All | Custom command that outputs secret |
+
+**Keychain example:**
+```json
+{
+  "storage": {
+    "provider": "keychain",
+    "command": "security find-generic-password -s nexus.anthropic -a api_key -w"
+  }
+}
+```
+
+**1Password example:**
+```json
+{
+  "storage": {
+    "provider": "1password",
+    "command": "op read \"op://Nexus/Anthropic API Key/api_key\""
+  }
+}
+```
+
+**Environment variable example:**
+```json
+{
+  "storage": {
+    "provider": "env",
+    "var": "ANTHROPIC_API_KEY"
+  }
+}
+```
+
+---
+
+## Skill State
+
+### Per-Skill State
+
+**Path:** `state/skills/{name}/state.json`
+
+```json
+{
+  "version": 1,
+  "type": "tool",
+  "configured": true,
+  "configuredAt": "2026-01-10T15:30:00Z",
+  "lastVerified": "2026-01-14T08:00:00Z",
+  "lastUsed": "2026-01-14T12:05:00Z",
+  "totalInvocations": 47,
+  "successRate": 0.95
+}
+```
+
+### Usage Log
+
+**Path:** `state/skills/{name}/usage.log`
+
+JSON Lines format (append-only):
+
+```jsonl
+{"ts":"2026-01-14T12:05:00Z","type":"use","ms":50}
+{"ts":"2026-01-14T12:10:00Z","type":"use","ms":45}
+```
+
+**Note:** This logs when the skill guide was accessed, not tool invocations (we don't wrap those).
+
+---
+
+## Workspace Config
+
+**Path:** `state/nexus/config.json`
+
+```json
+{
+  "version": "0.1.0",
+  "credentialStore": "keychain",
+  "1password": {
+    "vault": "Nexus"
+  }
+}
+```
+
+**Path:** `state/nexus/workspace.json`
+
+```json
+{
+  "os": "darwin",
+  "arch": "arm64",
+  "created": "2026-01-12T10:00:00Z"
+}
+```
+
+---
+
+## Daily Memory
+
+**Path:** `home/memory/YYYY-MM-DD.md`
+
+```markdown
+# 2026-01-14
+
+## Session 1 (10:00 AM)
+- Worked on nexus CLI
+- Fixed credential storage bug
+
+## Session 2 (2:00 PM)
+- User asked about email setup
+- Configured google-oauth
+```
+
+Agent reads today + yesterday at session start.
+
+---
+
+## Skill Resolution Order
+
+When looking for a skill by name:
+
+1. `skills/tools/{name}/SKILL.md`
+2. `skills/connectors/{name}/SKILL.md`
+3. `skills/guides/{name}/SKILL.md`
+
+First match wins. Use explicit paths if names conflict.
+
+---
+
+## Summary
+
+| Data | Location |
+|------|----------|
+| User profile | `state/user/IDENTITY.md` |
+| Agent identity | `state/agents/{name}/IDENTITY.md` |
+| Agent soul | `state/agents/{name}/SOUL.md` |
+| Agent memory | `state/agents/{name}/MEMORY.md` |
+| Credentials | `state/credentials/{service}/accounts/{account}/auth/{type}.json` |
+| Skill state | `state/skills/{name}/state.json` |
+| Skill usage | `state/skills/{name}/usage.log` |
+| Workspace config | `state/nexus/config.json` |
+| Daily logs | `home/memory/YYYY-MM-DD.md` |