How It Works

A complete walkthrough of how persistent memory enables coordination, learning, and cross-project intelligence.

The Foundation: Why This Works

OmniClaude works because it guarantees, coordinates, and remembers — in that order. It watches Claude Code sessions from outside, guarantees that work actually lands on disk, coordinates agents safely, learns from transcripts, stores insights in 3-tier memory, and injects relevant context into the next session. Everything else emerges from this foundation.

🔐 Before Memory: Capability 8 Work Guarantees

Before coordination and memory, OmniClaude guarantees that work actually lands on disk. Every file write is verified. Every plan, todo, spec, and artifact is registered and findable. This foundation — Capability 8 — is what makes everything else trustworthy.

1️⃣ Watch

Observes every Claude Code session from outside. Never modifies code. Just records what happens.

2️⃣ Learn

Extracts patterns: corrections by users, conventions, errors, and solutions from transcripts.

3️⃣ Persist

Stores learned knowledge in three-tier memory (working/episodic/semantic) in SQLite.

4️⃣ Whisper (Inject Context)

On UserPromptSubmit, smart injection algorithm scores all memory blocks against the current prompt. Injects the top-scoring blocks within the token budget (~2K tokens). Claude Code gets smarter context automatically.

Scenario: Two Developers Working in Parallel

T=0:00 — Alice Starts on Auth Refactor

User: "Claude-A, refactor our authentication system. Make it use OAuth."

What Happens (Powered by Memory):

  • ✓ SessionStart hook: Session registered, working memory loaded (watch + persist)
  • ✓ UserPromptSubmit hook: Relevant memory injected (learn → whisper)
  • ✓ Memory includes: Auth patterns, prior OAuth decisions, team preferences
  • ✓ Session registry: Alice's session registered with files tracked

T=0:15 — Alice Makes 3 Commits

Alice's Claude commits changes to auth system across 3 commits.

  • ✓ Watch: All 3 commits recorded in git_events
  • ✓ Persist: Session registry updated with file edits (7 files touched)
  • ✓ Memory state: Working memory tracks current task context

T=0:20 — Bob Starts on Dashboard Update

User: "Claude-B, update the dashboard to show the new user role."

What Happens (Memory Enables Coordination):

  • ✓ Bob's session starts (watch)
  • ✓ UserPromptSubmit: Memory injected PLUS coordination awareness from session registry
  • ⚠️ FILE OVERLAP DETECTED: Session memory shows Alice editing src/types.ts
  • ✓ Bob's Claude receives injected warning with coordination advice (whisper)

T=0:30 — Alice Pushes, Creates PR #48

Alice's Claude pushes branch and creates PR #48.

  • ✓ Watch: GitHub webhook fires, recorded in git_events
  • ✓ Persist: PR metadata stored in SQLite
  • ✓ Bob's next prompt: Includes "NEW PR #48 from Alice (auth refactor)"

T=0:35 — Dashboard PR Merges to Main

User merges Bob's PR #47 (dashboard update) to main. Alice's branch is now 1 commit behind.

  • ✓ Watch: GitHub webhook fires "PR #47 merged" (persist in git_events)
  • ✓ Learn: Conflict detection runs using memory of both branches
  • ✓ Whisper: Alice's next prompt includes step-by-step rebase instructions

T=0:40 — Alice Resolves Conflicts

User: "Claude-A, resolve the conflicts with main and force push."

  • ✓ Alice's Claude executes guided rebase
  • ✓ Watch: Conflict resolution patterns recorded
  • ✓ Learn: Watchdog analyzes conflict patterns, stores learned solutions
  • ✓ Persist: Merge conflict metadata stored (used for future predictions)

T=0:45 — Alice's PR is Merged

User merges Alice's PR #48. Entire workflow complete.

  • ✓ Watch: Final merge recorded
  • ✓ Learn: Session analyzed, patterns extracted
  • ✓ Persist: Episode stored in episodic memory, semantic patterns updated
  • ✓ Future: Next OAuth task benefits from this session's learning

Why This Coordination Was Possible

Every step was powered by persistent memory:

  • 🧠 Session registry in memory — Real-time tracking of what each developer is editing
  • 📡 GitHub webhooks stored in memory — Instant sync of events, historical tracking
  • 🚨 Conflict detection via memory — Warned Bob about shared files before conflict happened
  • 📋 Smart injection from memory — Conflict resolution suggestions appeared in Alice's prompt automatically
  • 🧠 Learning from memory — Patterns from conflict resolution stored for next time

Capability 8 — The Artifact That Didn't Disappear

The Problem: Plans Vanish

Developer asks Claude Code to plan a white-label implementation and save it as a markdown file. Claude says "saved." VS Code restarts. The file is nowhere.

↓

OmniClaude Capability 8 In Action

✓ PreToolUse Hook: Intercepts the write

✓ File Verification: File existence verified on disk with SHA-256 hash

✓ Artifact Registry: File registered with path, timestamp, session ID, and hash

✓ Next SessionStart: "Active artifact: white-label-plan.md — last modified 6 hours ago"

↓

✓ Result:

File is exactly where it was left. Work continues. No lost plans. No forgotten decisions. No "did Claude save this?" moments.

Memory Injection in Action

Session 1: Alice Sets OAuth Pattern

Alice's Claude tries OAuth implementation using Passport.js. User reviews and suggests: "Actually, we prefer Auth0 because it handles SAML."

✓ WATCHED & LEARNED: "For OAuth, use Auth0 not Passport.js"

Stored in persistent semantic memory → conventions table

Session 2: Bob Starts Auth Work (2 weeks later)

Different developer. New prompt: "I need to add two-factor authentication to the auth system."

Smart Injection Algorithm (from persistent memory):

  • • "OAuth" ∈ "two-factor auth" → +40 (keyword overlap)
  • • Convention: "auth0 not passport" → +30 (recency)
  • • "auth" edited 47 times last month → +25 (frequency)
  • • Task-type: "feature" matches "add 2FA" → +20 (task match)
  • = 115 points (above threshold 65) → INJECT

Bob's Claude receives injected context (from memory):

"For OAuth, this team uses Auth0 (supports SAML). When adding 2FA, leverage Auth0's native 2FA support rather than building custom solution."

✓ Result:

Bob's Claude immediately knows to use Auth0 (not re-inventing the wheel). Task completed 50% faster because Alice's learned knowledge was persisted and whispered back.

Watchdog Learning in Action

Detecting the 80% Problem

Prompt 1 (WATCH):

"Implement the payment flow using Stripe"

Claude produces 80% solution. Circular edits detected: `src/api/payments/route.ts` edited 3 times in same prompt.

Watchdog Alerts (LEARN):

"Drift detected on payment flow (circular edits). Agent may be stuck. Consider breaking into smaller tasks or providing explicit constraints."

Prompt 2 (WHISPER - Next Session):

User gets warning from persistent memory: "Payment flow had issues last session. Let's break this into: (1) Checkout session creation, (2) Webhook handler, (3) Testing."

Convention Learning (PERSIST)

User corrects Claude 3 times on the same pattern: "Always use validateRequest() middleware, not inline validation."

✓ PATTERN LEARNED & PERSISTED: "Use validateRequest() middleware, never inline validation"

Stored in persistent memory. Next time Claude sees validation code, it will be injected with this rule.

Cross-Project Intelligence (Powered by Memory)

Scenario: Schema Change Ripple

Project A: User asks Claude to add a `role` field to the User table.

Watch: File modified: `src/db/schema.ts` → `User` table definition

↓

Project Graph in Memory Detects: This file is shared with Project B

Learn: "User table schema changed. Dependent projects may need updates."

↓

Whisper to Project B: Next time someone works in that project...

📌 Schema change detected in shared file (src/db/schema.ts):

User table gained a `role` field. Your queries that reference this table may need updates. Check dependent projects.

Why This Architecture Works

✓ Non-Invasive

OmniClaude never interrupts Claude Code. All coordination happens via persistent memory and background webhooks.

✓ Git-Based

Uses GitHub as the system of record. Memory tracks git events. No custom coordination logic.

✓ Persistent

Everything stored in SQLite with ACID guarantees. Sessions, memory, conflicts, patterns survive beyond a single use.

✓ Learning

Automatically learns conventions, patterns, and error-fix relationships from every session without manual intervention.

The Core Pattern: Watch → Learn → Persist → Whisper → Repeat

This external-observer pattern, powered by persistent memory, is what enables OmniClaude to solve problems no other tool has solved.