System Architecture

How OmniClaude coordinates multi-agent work, persists memory, and learns from every session.

Architecture Foundation: Persistent Memory

OmniClaude's architecture is built on one core: persistent 3-tier memory. Everything else (coordination, learning, cross-project intelligence) is enabled by memory and its integration with git, GitHub webhooks, and SQLite.

Data Flow Architecture

Claude Code (Developer Machine)
    ↓ Developers write code
    ↓ Hooks capture events
    ↓
OmniClaude Server (Port 3333)
    ├─ SessionStart hook (oc-wake)
    │   └─ Load working memory from SQLite
    │
    ├─ UserPromptSubmit hook (oc-prime)
    │   └─ Smart inject relevant memory blocks
    │
    ├─ PreToolUse hook (oc-pulse)
    │   └─ Safety checks, file overlap detection
    │
    └─ Stop hook (oc-digest)
        └─ Process transcript, update memory
        └─ Detect drift, learn conventions
        └─ Notify about cross-project impacts
        ↓
GitHub Webhooks
    ├─ PR opened/merged
    ├─ CI checks failed
    └─ Branch changes
        ↓
SQLite Database (~/.omniclaude/omniclaude.db)
    ├─ 26 tables (17 memory + coordination + 9 Capability 8 guarantee)
    ├─ Atomic transactions
    ├─ WAL mode for concurrency
    └─ Single source of truth

The system watches Claude Code from outside, never modifying code directly.

Three-Tier Memory System

Working Memory

  • ✓ ~500 tokens (current session)
  • ✓ Active files being edited
  • ✓ Current task description
  • ✓ Recent decisions made
  • ✓ Immediate blockers

Auto-expires after session ends

Episodic Memory

  • ✓ Compressed session summaries
  • ✓ Files modified in each session
  • ✓ Tools used
  • ✓ Patterns discovered
  • ✓ Errors encountered

Searchable by project/date/topic

Semantic Memory

  • ✓ Architecture decisions
  • ✓ Coding conventions
  • ✓ Reusable patterns
  • ✓ Team preferences
  • ✓ Common error fixes

Persistent across all sessions

Smart Injection Algorithm

FOR each memory block in (working + episodic + semantic):
    score = 0
    score += keyword_overlap(block, user_prompt)  // 0-100
    score += recency_weight(block.last_used)      // 0-50
    score += frequency_weight(block.access_count) // 0-25
    score += task_match(block.type, task_type)    // 0-25

    IF score > RELEVANCE_THRESHOLD (default: 65):
        inject_into_context(block)
        track_tokens += len(block)

    IF track_tokens >= TOKEN_BUDGET (default: 2000):
        break  // Stop injecting, stay within budget

RESULT: Only relevant, high-scoring blocks injected
        No correctness degradation from noise

SQLite Database Schema (17 Tables)

Core Entities (2 tables)

  • projects — Team repositories metadata
  • developers — Developer profiles & authentication

Memory & Knowledge (3 tables)

  • memory_blocks — Global + project-tiered memory (working/episodic/semantic)
  • episodes — Compressed session summaries with file changes & tools used
  • decisions — Architecture decisions (tier 1-4: axioms → strategies → patterns → preferences)

Sessions & Activity (2 tables)

  • active_sessions — Current developer work in progress
  • session_state — Per-session memory snapshots (working memory, block values)

Git & Conflicts (3 tables)

  • project_edges — Dependencies between projects (consumes/shares relationships)
  • git_events — Branch changes, merges, force pushes, critical operations
  • merge_conflicts — Resolved conflicts for learning & pattern detection

Cross-Project Awareness (2 tables)

  • cross_project_impacts — When one project's file change affects others
  • notifications — Cascade alerts (pending → issued → acknowledged → resolved)

Patterns & Learning (3 tables)

  • code_patterns — Reusable solutions (problem → code_snippet)
  • conventions — Team standards extracted from corrections (rule, category, confidence)
  • error_patterns — Common bugs & their solutions (error_message → fixes)

Analytics & Monitoring (2 tables)

  • task_metrics — Per-session performance (duration, tools, errors, quality scores)
  • watchdog_analyses — Drift detection reports (circular edits, error loops, etc.)

Configuration (1 table)

  • flags — Feature flags (tiered_memory, project_graph, decision_graph, etc.)

Design Principles

  • ✓ Atomic transactions (no partial writes)
  • ✓ Foreign key constraints (referential integrity)
  • ✓ Proper indexing (queries on project_slug, timestamps, status)
  • ✓ WAL mode (concurrent reads, queued writes)
  • ✓ Timestamped rows (created_at, updated_at for auditing)

Multi-Developer Coordination Layer

Session Registry

active_sessions table:
{
  session_id: "session-abc",
  developer: "[email protected]",
  project: "auth-service",
  branch: "feature/auth-refactor",
  files_active: ["src/lib/auth.ts", "src/app/auth/page.tsx"],
  commits_ahead: 3,
  started: 2026-03-25T10:00:00Z,
  heartbeat: 2026-03-25T10:15:00Z
}

Every prompt submission → heartbeat updated
Developer switches branch → files_active updated
PR merged → cascade notifications sent

File Overlap Detection

WHEN user submits prompt in session-alice:
    prompt_files = extract_files(user_message)
    FOR each file in prompt_files:
        active_edits = active_sessions
                      .WHERE files_active LIKE file
                      .WHERE session_id != session-alice
        IF active_edits > 0:
            WARN: "alice and bob are both editing src/types.ts"
            SUGGEST: "consider coordinating"

GitHub Webhook Coordination

WHEN PR is merged on GitHub:
    → Webhook fires to OmniClaude
    → git_events table updated
    → For each active_session on that branch:
        → Send: "PR #123 merged, rebase to get latest"
        → Suggest: Step-by-step rebase commands
        → Detect: Potential conflicts
        → Inject: Rebase guidance into next prompt

Watchdog Safety System

Drift Detection Patterns

Circular Edits

File X region Y changed 3+ times in same session → indicates agent looping on same problem

Hallucinations

Import statement for package not in package.json → agent making up dependencies

Confidence Decay

Response length increasing + hedging language increasing → agent losing confidence

Loop Behavior

Repeating same action/tool call with same inputs → caught in error loop

Deployment Architecture

Single Machine

  • ✓ OmniClaude Server (Node.js, port 3333)
  • ✓ SQLite database (~/.omniclaude/omniclaude.db)
  • ✓ ~1-10MB database file
  • ✓ Easy to back up

Scaling

  • ✓ 1-5 devs: SQLite perfect
  • ✓ 5-20 devs: SQLite excellent (WAL mode)
  • ✓ 20-100 devs: SQLite good, monitor episode count
  • ✓ 100+ devs: PostgreSQL (same app code)