# SophiaClaw System Requirements **Version:** 2.0.0 **Classification:** Public (Open Source) **Last Updated:** 2026-03-11 --- ## 1. Executive Summary SophiaClaw is a local-first AI governance and agent orchestration platform that enables secure, auditable AI assistant deployments across multiple messaging channels. The system implements a three-layer governance architecture (Intent → Policy → Gate → Execute → Audit) to ensure transparent, controlled AI operations suitable for enterprise and personal use. ### 1.1 System Vision Provide a production-ready AI gateway that: - Executes AI-powered tasks through multiple communication channels - Enforces governance controls on all AI actions - Maintains immutable audit trails for compliance - Operates primarily on local infrastructure for privacy - Scales from single-user to multi-team deployments --- ## 2. Functional Requirements ### 2.1 Core Agent Runtime | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------------------------------------- | -------- | -------------------- | | FR-001 | The system SHALL execute AI agent tasks using the ReAct (Reasoning + Acting) pattern | P0 | Core architecture | | FR-002 | The system SHALL support dynamic tool selection from a registered tool registry | P0 | Tool loop | | FR-003 | The system SHALL maintain conversation context with configurable token limits (4K-8K default) | P0 | Memory management | | FR-004 | The system SHALL route requests to appropriate LLM models based on task complexity | P1 | Model routing | | FR-005 | The system SHALL support multiple LLM providers (OpenRouter, local models, cloud APIs) | P1 | Provider abstraction | | FR-006 | The system SHALL implement automatic session compaction for conversations exceeding 1000 messages | P2 | Performance | ### 2.2 Governance Services #### 2.2.1 Intent Service | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------------------------- | -------- | --------------------- | | FR-101 | The system SHALL capture user intent at session initiation | P0 | Intent capture | | FR-102 | The system SHALL structure raw input into: what, why, scope, risk level, deliverables | P0 | Rule-based extraction | | FR-103 | The system SHALL allow users to correct misunderstood intent before execution | P0 | User control | | FR-104 | The system SHALL bind intent to session for audit trail | P1 | Traceability | | FR-105 | The system SHALL support LLM-enhanced intent extraction (future) | P2 | Planned enhancement | #### 2.2.2 Policy Engine | ID | Requirement | Priority | Notes | | ------ | ---------------------------------------------------------------------------------- | -------- | ------------------ | | FR-111 | The system SHALL evaluate all actions against registered policies before execution | P0 | Policy enforcement | | FR-112 | The system SHALL support custom policy rules defined by users | P0 | Extensibility | | FR-113 | The system SHALL return allow/block/require_approval decisions | P0 | Decision types | | FR-114 | The system SHALL evaluate policies in order: custom rules → standard policies | P1 | Precedence | | FR-115 | The system SHALL support policy overrides and exceptions | P2 | Flexibility | | FR-116 | The system SHALL load policies from `~/.sophiaclaw/policies.json` | P1 | Persistence | #### 2.2.3 Gate Engine | ID | Requirement | Priority | Notes | | ------ | ---------------------------------------------------------------------------------------------- | -------- | ---------------- | | FR-121 | The system SHALL intercept high-risk actions for human approval | P0 | Approval gates | | FR-122 | The system SHALL trigger gates for: >10 file deletions, >$5 spending, non-allowlisted commands | P0 | Default triggers | | FR-123 | The system SHALL support approve/modify/reject user responses | P0 | User options | | FR-124 | The system SHALL escalate policy violations to human review | P1 | Escalation | | FR-125 | The system SHALL support custom gate checkers via plugin interface | P2 | Extensibility | #### 2.2.4 Bulletin Service (Audit) | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------------------------------------ | -------- | ---------------- | | FR-131 | The system SHALL log all governance events to an immutable audit log | P0 | Audit trail | | FR-132 | The system SHALL record: timestamp, session, user, intent, policies checked, tools used, results | P0 | Event schema | | FR-133 | The system SHALL store bulletin events in append-only SQLite tables | P0 | Immutability | | FR-134 | The system SHALL support export of audit logs to JSON/Markdown | P1 | Compliance | | FR-135 | The system SHALL retain security logs for 1 year, audit logs for 90 days | P2 | Retention policy | #### 2.2.5 Claims Service | ID | Requirement | Priority | Notes | | ------ | ---------------------------------------------------------------------------------- | -------- | ------------------ | | FR-141 | The system SHALL detect when multiple sessions attempt to modify the same resource | P1 | Conflict detection | | FR-142 | The system SHALL implement file-level locking for critical resources | P1 | Resource locks | | FR-143 | The system SHALL notify users of detected conflicts before proceeding | P1 | User notification | | FR-144 | The system SHALL support lock timeouts and automatic release | P2 | Lock management | ### 2.3 Channel Integration | ID | Requirement | Priority | Notes | | ------ | -------------------------------------------------------------------------- | -------- | ------------------ | | FR-201 | The system SHALL support Telegram via Bot API with webhook or polling | P0 | Primary channel | | FR-202 | The system SHALL support Discord via WebSocket gateway | P0 | Team collaboration | | FR-203 | The system SHALL support Slack via Socket Mode | P0 | Business workflows | | FR-204 | The system SHALL support WhatsApp via web (puppeteer-based) | P1 | Universal access | | FR-205 | The system SHALL support Signal via signald local socket | P2 | Privacy-focused | | FR-206 | The system SHALL support iMessage via macOS bridge (BlueBubbles) | P2 | Apple ecosystem | | FR-207 | The system SHALL support Web interface via WebSocket | P0 | Browser access | | FR-208 | The system SHALL normalize all channel messages to unified internal format | P0 | Abstraction | | FR-209 | The system SHALL support extension channels via plugin SDK | P1 | Extensibility | ### 2.4 Tool System #### 2.4.1 Native Tools | ID | Requirement | Priority | Notes | | ------ | --------------------------------------------------------------------------- | -------- | ---------------- | | FR-301 | The system SHALL provide file operations: read, write, search, list, delete | P0 | Core tools | | FR-302 | The system SHALL provide shell command execution with allowlist enforcement | P0 | System access | | FR-303 | The system SHALL provide web fetch (HTTP requests) with timeout limits | P0 | Network access | | FR-304 | The system SHALL provide browser automation via Puppeteer | P1 | Web interaction | | FR-305 | The system SHALL provide SQLite database queries | P1 | Data access | | FR-306 | The system SHALL provide memory retrieval and vector search | P1 | Knowledge access | #### 2.4.2 Tool Execution | ID | Requirement | Priority | Notes | | ------ | --------------------------------------------------------------------- | -------- | ------------------- | | FR-311 | The system SHALL validate all tool parameters using Zod schemas | P0 | Input validation | | FR-312 | The system SHALL enforce tool execution timeouts (default 60 seconds) | P0 | Resource protection | | FR-313 | The system SHALL limit tool output size (default 10MB) | P1 | Memory protection | | FR-314 | The system SHALL sandbox tool execution within workspace jail | P0 | Security | | FR-315 | The system SHALL log all tool executions to bulletin | P0 | Audit | #### 2.4.3 MCP Integration | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------------ | -------- | ----------------- | | FR-321 | The system SHALL support Model Context Protocol (MCP) server integration | P1 | External tools | | FR-322 | The system SHALL load MCP servers from `~/.sophiaclaw/mcp-servers.json` | P1 | Configuration | | FR-323 | The system SHALL expose MCP tools through the standard tool registry | P1 | Unified interface | ### 2.5 Memory Management | ID | Requirement | Priority | Notes | | ------ | --------------------------------------------------------------------------------------- | -------- | ------------------- | | FR-401 | The system SHALL implement four-layer memory: ephemeral, working, persistent, reference | P0 | Memory architecture | | FR-402 | The system SHALL store sessions in JSONL format under `~/.sophiaclaw/sessions/` | P0 | Session storage | | FR-403 | The system SHALL auto-compact sessions after 1000 messages | P1 | Performance | | FR-404 | The system SHALL maintain a SQLite index for session search | P1 | Fast retrieval | | FR-405 | The system SHALL support semantic (vector) search for persistent memory | P2 | Advanced search | | FR-406 | The system SHALL expire sessions after 90 days (configurable) | P2 | Lifecycle | ### 2.6 Gateway Services | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------------------- | -------- | ----------------- | | FR-501 | The system SHALL run a WebSocket server on port 37521 (default) | P0 | Primary interface | | FR-502 | The system SHALL support binary WebSocket with JSON message framing | P0 | Protocol | | FR-503 | The system SHALL implement heartbeat with 30-second ping/pong | P0 | Connection health | | FR-504 | The system SHALL support automatic reconnection with exponential backoff | P1 | Reliability | | FR-505 | The system SHALL provide HTTP API for external integrations | P1 | REST access | | FR-506 | The system SHALL support TLS 1.3 (minimum TLS 1.2) for WSS | P0 | Security | | FR-507 | The system SHALL authenticate all WebSocket connections with HMAC-signed tokens | P0 | Auth | | FR-508 | The system SHALL support 1000+ concurrent WebSocket connections | P2 | Scale | ### 2.7 CLI Interfaces | ID | Requirement | Priority | Notes | | ------ | --------------------------------------------------------------------- | -------- | ---------------- | --- | ----------------- | | FR-601 | The system SHALL provide CLI command: `sophiaclaw gateway` | P0 | Gateway start | | FR-602 | The system SHALL provide CLI command: `sophiaclaw agent --message` | P0 | Direct messaging | | FR-603 | The system SHALL provide CLI command: `sophiaclaw bulletin list` | P0 | Audit review | | FR-604 | The system SHALL provide CLI command: `sophiaclaw config set` | P0 | Configuration | | FR-605 | The system SHALL provide CLI command: `sophiaclaw policy add | enable | disable` | P1 | Policy management | | FR-606 | The system SHALL provide CLI command: `sophiaclaw credentials rotate` | P1 | Security | | FR-607 | The system SHALL provide CLI command: `sophiaclaw sessions kill-all` | P2 | Emergency | ### 2.8 Web Dashboard | ID | Requirement | Priority | Notes | | ------ | ------------------------------------------------------------------- | -------- | ----------------- | | FR-701 | The system SHALL provide web UI at http://localhost:3000 | P0 | Browser interface | | FR-702 | The system SHALL provide chat interface in web UI | P0 | Messaging | | FR-703 | The system SHALL provide governance dashboard with real-time status | P1 | Monitoring | | FR-704 | The system SHALL provide audit log viewer with filters | P1 | Compliance | | FR-705 | The system SHALL provide configuration UI | P1 | Management | | FR-706 | The system SHALL provide real-time metrics display | P2 | Observability | ### 2.9 Mobile Applications | ID | Requirement | Priority | Notes | | ------ | -------------------------------------------------------------- | -------- | --------------- | | FR-801 | The system SHALL provide iOS companion app | P1 | Mobile access | | FR-802 | The system SHALL provide Android companion app | P1 | Mobile access | | FR-803 | The system SHALL support push notifications for gate approvals | P1 | User engagement | | FR-804 | The system SHALL support voice interface for input | P2 | Accessibility | | FR-805 | The system SHALL support offline message queuing | P2 | Reliability | --- ## 3. Non-Functional Requirements ### 3.1 Performance | ID | Requirement | Priority | Target | | ------- | ---------------------------------- | -------- | ----------------- | | NFR-001 | Gateway startup time | P0 | <5 seconds | | NFR-002 | Simple message processing latency | P0 | <2 seconds (p50) | | NFR-003 | Complex message processing latency | P1 | <10 seconds (p95) | | NFR-004 | Tool execution latency | P1 | Depends on tool | | NFR-005 | WebSocket message throughput | P2 | 1000 msg/sec | | NFR-006 | Policy evaluation latency | P0 | <100ms | | NFR-007 | Gate check latency | P0 | <200ms | | NFR-008 | Audit log write latency | P1 | <50ms | ### 3.2 Reliability | ID | Requirement | Priority | Target | | ------- | ---------------------------------------- | -------- | ----------------------- | | NFR-011 | Gateway uptime (production) | P0 | 99.5% | | NFR-012 | Session persistence | P0 | No data loss on crash | | NFR-013 | Automatic recovery from LLM API failures | P0 | Retry with backoff | | NFR-014 | Channel reconnection on disconnect | P0 | <30 seconds | | NFR-015 | Graceful degradation under load | P1 | Shed non-critical tasks | | NFR-016 | Message delivery guarantee | P1 | At-least-once | ### 3.3 Scalability | ID | Requirement | Priority | Target | | ------- | -------------------------------- | -------- | -------------------------- | | NFR-021 | Concurrent WebSocket connections | P1 | 1000+ per instance | | NFR-022 | Active AI agent sessions | P1 | 50+ per instance | | NFR-023 | Connected channels | P2 | 10+ simultaneous | | NFR-024 | Sessions per user | P2 | Unlimited | | NFR-025 | Audit log entries | P2 | 1M+ without degradation | | NFR-026 | Workspace storage | P2 | 10GB default, configurable | | NFR-027 | Horizontal scaling (future) | P3 | Gateway federation | ### 3.4 Security | ID | Requirement | Priority | Notes | | ------- | ------------------------------------------ | -------- | ---------------------- | | NFR-031 | All credentials encrypted at rest | P0 | AES-256-GCM | | NFR-032 | All external communication over TLS | P0 | TLS 1.3 preferred | | NFR-033 | No secrets in source code or logs | P0 | Security imperative | | NFR-034 | Tool execution sandboxed | P0 | Workspace jail | | NFR-035 | Shell commands allowlisted | P0 | No arbitrary execution | | NFR-036 | Rate limiting on all APIs | P1 | Prevent abuse | | NFR-037 | Authentication required for gateway access | P0 | HMAC-signed tokens | | NFR-038 | Audit logging for security events | P0 | 1 year retention | ### 3.5 Usability | ID | Requirement | Priority | Notes | | ------- | ----------------------------------------- | -------- | ------------- | | NFR-041 | First-time setup under 10 minutes | P1 | Onboarding | | NFR-042 | CLI help available for all commands | P1 | Documentation | | NFR-043 | Error messages actionable and clear | P1 | UX | | NFR-044 | Governance events visible in real-time | P1 | Transparency | | NFR-045 | Audit logs exportable in standard formats | P2 | Compliance | ### 3.6 Maintainability | ID | Requirement | Priority | Notes | | ------- | ----------------------------------------- | -------- | -------------------- | | NFR-051 | All code in TypeScript with strict mode | P0 | Type safety | | NFR-052 | Minimum 80% test coverage | P0 | Quality gate | | NFR-053 | Public APIs documented with JSDoc | P1 | Developer experience | | NFR-054 | Semantic versioning with changelog | P0 | Release management | | NFR-055 | Backward compatibility for minor versions | P0 | Stability | --- ## 4. Platform Support Matrix ### 4.1 Server/Gateway Platforms | Platform | Version | Support Level | Notes | | ------------ | -------------- | ------------- | --------------------- | | macOS | 14.0+ (Sonoma) | Primary | Apple Silicon & Intel | | Ubuntu | 22.04 LTS+ | Primary | AMD64, ARM64 | | Debian | 12+ (Bookworm) | Primary | AMD64, ARM64 | | RHEL | 9+ | Primary | AMD64, ARM64 | | Windows 11 | 22H2+ | Experimental | WSL2 recommended | | FreeBSD | 14+ | Community | Best-effort | | Raspberry Pi | Pi 4+, Pi 5 | Community | ARM64 only | ### 4.2 Node.js Runtime | Runtime | Version | Support Level | Notes | | ------- | ---------- | ------------- | -------------------- | | Node.js | 22.x (LTS) | Primary | Recommended | | Node.js | 20.x | Supported | Deprecation warnings | | Node.js | <20 | Not Supported | EOL | | Bun | 1.x+ | Optional | Alternative runtime | ### 4.3 Client Platforms | Platform | Version | Support Level | Notes | | ----------- | ------- | ------------- | ----------------- | | Chrome/Edge | 120+ | Primary | Web UI | | Firefox | 121+ | Primary | Web UI | | Safari | 17+ | Primary | Web UI, macOS app | | iOS | 17+ | Primary | Mobile app | | Android | 13+ | Primary | Mobile app | --- ## 5. Dependencies and Version Requirements ### 5.1 Core Runtime Dependencies | Package | Version | Purpose | Critical | | ---------------- | ------- | ---------------------- | -------- | | `node` | 22.x+ | JavaScript runtime | Yes | | `typescript` | 5.x+ | Type system | Yes | | `pnpm` | 9.x+ | Package manager | Yes | | `better-sqlite3` | 11.x+ | Local database | Yes | | `jiti` | 2.x+ | TS runtime for plugins | Yes | ### 5.2 Channel Dependencies | Package | Version | Purpose | Critical | | -------------------- | ------- | ---------------------- | -------- | | `grammy` | 1.x+ | Telegram Bot framework | Yes | | `discord.js` | 14.x+ | Discord integration | Yes | | `@slack/web-api` | 7.x+ | Slack integration | Yes | | `@slack/socket-mode` | 2.x+ | Slack Socket Mode | Yes | | `whatsapp-web.js` | 1.x+ | WhatsApp web | Optional | | `signald-client` | - | Signal integration | Optional | ### 5.3 AI/LLM Dependencies | Package | Version | Purpose | Critical | | ---------------------- | ------- | ------------------------ | -------- | | `@langchain/core` | 0.x+ | LLM integration patterns | Yes | | `@langchain/anthropic` | 0.x+ | Claude API | Yes | | `@langchain/openai` | 0.x+ | OpenAI API | Yes | | `langchain` | 0.x+ | LLM orchestration | Yes | ### 5.4 Web/Framework Dependencies | Package | Version | Purpose | Critical | | ----------- | ------- | ----------------------- | -------- | | `express` | 4.x+ | HTTP server | Yes | | `ws` | 8.x+ | WebSocket server | Yes | | `fastify` | 4.x+ | Alternative HTTP server | Optional | | `socket.io` | 4.x+ | WebSocket abstraction | Optional | ### 5.5 Security Dependencies | Package | Version | Purpose | Critical | | -------------------- | ------- | ------------------ | -------- | | `zod` | 3.x+ | Schema validation | Yes | | `crypto` (built-in) | - | Encryption, HMAC | Yes | | `keytar` | 7.x+ | OS keychain access | Yes | | `express-rate-limit` | 7.x+ | Rate limiting | Yes | ### 5.6 Build/Development Dependencies | Package | Version | Purpose | Critical | | --------- | ------- | ----------------- | -------- | | `esbuild` | 0.x+ | Bundling | Yes | | `vitest` | 2.x+ | Testing framework | Yes | | `oxlint` | latest | Linting | Yes | | `oxfmt` | latest | Formatting | Yes | --- ## 6. Scalability Requirements ### 6.1 Vertical Scaling The system SHALL support single-instance deployments with: | Resource | Baseline | Maximum | | ---------------------- | -------- | ------- | | CPU cores | 2 | 32+ | | Memory | 4 GB | 64 GB | | Concurrent connections | 100 | 5000+ | | Active sessions | 10 | 500+ | | Tools/minute | 100 | 2000+ | ### 6.2 Horizontal Scaling (Future) | Feature | Status | Notes | | ---------------------- | ------- | ------------------------ | | Gateway federation | Planned | Message bus architecture | | Session store sharding | Planned | Redis-based | | Load balancer support | Planned | Sticky sessions required | | Multi-region | Future | Not in scope for v2 | ### 6.3 Resource Limits | Resource | Default | Configurable | Enforcement | | ------------------- | ----------- | ------------ | ---------------- | | Max sessions | 100 | Yes | Hard limit | | Session timeout | 30 min idle | Yes | Auto-close | | File upload size | 50 MB | Yes | Reject oversized | | Tool execution time | 60 seconds | Yes | Timeout + kill | | LLM tokens/request | 8K context | Yes | Truncate | | Workspace size | 10 GB | Yes | Quota warning | | Audit log retention | 1 year | Yes | Auto-purge | --- ## 7. Compliance Requirements ### 7.1 Data Privacy | Regulation | Requirement | Implementation | | ---------- | --------------------- | -------------------------------- | | GDPR | Right to data export | `sophiaclaw bulletin export` | | GDPR | Right to erasure | `sophiaclaw sessions delete-all` | | GDPR | Data minimization | Local-first storage | | CCPA | Data access request | Audit log export | | CCPA | Data deletion request | Complete session purge | ### 7.2 Security Standards | Standard | Level | Notes | | ------------ | ------------- | --------------------------------- | | OWASP Top 10 | Mitigated | Input validation, output encoding | | CIS Controls | Level 1 | Basic security hygiene | | NIST 800-53 | Mapped | Control documentation available | | SOC 2 | Not certified | Framework-aligned | ### 7.3 Industry Restrictions | Industry | Status | Notes | | ---------- | ---------- | --------------------------------------- | | Healthcare | Restricted | No PHI handling without BAA | | Financial | Restricted | Additional controls required | | Government | Restricted | Air-gapped deployment not supported | | Education | Supported | FERPA-compliant configuration available | --- ## 8. Deployment Options ### 8.1 Local Development | Aspect | Configuration | | ----------- | --------------------------------- | | Command | `sophiaclaw gateway --port 37521` | | Use case | Single user, testing, development | | Persistence | Local file system | | Security | Localhost only | ### 8.2 Production Daemon | Aspect | Configuration | | ----------- | ------------------------------------- | | Command | `sophiaclaw onboard --install-daemon` | | Use case | Always-on personal gateway | | Persistence | Local file system with rotation | | Security | TLS, firewall rules | ### 8.3 Docker Container | Aspect | Configuration | | ----------- | --------------------------- | | Image | `sophiaclaw/gateway:latest` | | Command | `docker run -p 37521:37521` | | Use case | Isolated deployment, CI/CD | | Persistence | Volume mounts required | ### 8.4 Cloud Self-Hosted | Platform | Configuration | | ------------- | -------------------------------- | | VPS (systemd) | Ubuntu 22.04+, systemctl service | | Kubernetes | Helm chart available | | Fly.io | `fly.toml` configuration | | Railway | One-click deploy | ### 8.5 macOS Application | Aspect | Configuration | | ------------ | --------------------------- | | Type | Native menubar app | | Auto-start | Login item | | Updates | Sparkle framework (appcast) | | Notarization | Apple notarized | --- ## 9. Acceptance Criteria ### 9.1 Functional Acceptance - [ ] All P0 functional requirements implemented and tested - [ ] All P1 functional requirements implemented or documented as future work - [ ] Governance flow (Intent → Policy → Gate → Audit) functions end-to-end - [ ] All primary channels (Telegram, Discord, Slack, Web) operational - [ ] Tool execution sandboxed and audited - [ ] Session persistence survives restart ### 9.2 Non-Functional Acceptance - [ ] Performance targets met (P0 NFRs) - [ ] Security controls verified (penetration test recommended) - [ ] 80%+ test coverage achieved - [ ] Documentation complete for users and developers - [ ] Installation succeeds on all primary platforms ### 9.3 Compliance Acceptance - [ ] No hardcoded secrets in codebase - [ ] Credentials encrypted at rest - [ ] Audit logs exportable - [ ] Privacy policy and terms of service available - [ ] Security contact information published --- ## 10. Document History | Version | Date | Author | Changes | | ------- | ---------- | ------------- | ----------------------------------------------- | | 1.0.0 | 2025-02-20 | Thalamus Labs | Initial release | | 2.0.0 | 2026-03-11 | Thalamus Labs | Open source release, comprehensive requirements | --- ## 11. Related Documents - [Governance Requirements](./GOVERNANCE_REQUIREMENTS.md) - [Security Requirements](./SECURITY_REQUIREMENTS.md) - [Performance Requirements](./PERFORMANCE_REQUIREMENTS.md) - [System Architecture](../architecture.md) - [Security Architecture](../security.md) ---

SophiaClaw — Governed AI. Trusted Results.
Built for transparency. Designed for trust.