SEIF Framework

SEIF is an open protocol that gives AI sessions persistent, verified context. Instead of repeating yourself every conversation, you define context once — and any SEIF-enabled AI reads it immediately.

The framework has two layers: the open-source protocol (primitives, CLI, quality gate) and the SEIF Suite + OS product layer (dashboard, persistence, analytics).

Install the CLI and initialise a context repo in any project:

pip install seif-cli
cd your-project
seif --init

This creates a .seif/ directory with config.json, mapper.json, and PROTOCOL.md.

Sync your codebase into a compressed context module:

seif --sync
seif --workspace

Measure quality of any text:

echo "Your AI output here" | seif --quality-gate
# → Grade: B  Stance: VERIFIABLE  Score: 72

These primitives are defined in the open-source protocol and are universal across all implementations:

Every .seif module belongs to one category:

Modules have hash-chain provenance — every contribution records parent_hash → new_hash.

SEIF has three classification levels enforced at the gate:

# Force override (explicit opt-in only)
seif --persist --allow-confidential "my-module.seif"

The quality gate measures verifiability — not grammar, not style. It scores whether a text makes claims that can be checked.

from seif.analysis.quality_gate import analyze_quality

result = analyze_quality("The API returns 200 in under 50ms under normal load.")
print(result.grade)   # A
print(result.stance)  # VERIFIABLE

SEIF uses a real second-order linear system to model circuit coherence. The transfer function is:

The damping ratio ζ is derived directly from the system coefficients and becomes a universal constant in SEIF:

This is not an arbitrary constant — it emerges from the relationship between the system's damping coefficient (3) and its natural frequency (√6). Every SEIF agent receives ζ on first connect via /agent/init.

Circuit states

Tesla 3-6-9 anchor frequencies

SEIF maps circuit states to Solfeggio frequencies, aligned with the 3-6-9 pattern Nikola Tesla considered fundamental:

Install the CLI from PyPI:

pip install seif-cli

Context & Workspace

seif --init                        # create .seif/ in current directory
seif --sync                        # compress git history into context module
seif --workspace                   # discover and sync all projects in workspace
seif --ingest <source>             # ingest external source into context
seif --export                      # export full context to a single file

Sessions

seif --session create              # start a new session
seif --session list                # list open sessions
seif --session show --session-name <name>   # show session detail
seif --session contribute --session-name <name> --session-message "note"
seif --session close --session-name <name>  # close and generate handoff
seif --handoff <session-name>      # generate handoff manifest

Quality & Analysis

seif --quality-gate                # analyse stdin or current context
seif --audit                       # run security + quality audit
seif --health                      # check context repo health
seif --consult "question"          # multi-AI consensus query
seif --consensus "question"        # alias for --consult

Identity & Keys

seif --keygen                      # generate Ed25519 signing keypair
seif --sign module.seif            # sign a module with your private key
seif --verify module.seif          # verify module signature
seif --sign-all <directory>        # sign all .seif files in a directory
seif --identity-scan               # scan local workspace + stamp resonance_identity on all modules
seif --identity-scan Air-M1        # scan remote machine via SSH and compare lineage

Backend (SEIF Suite)

seif serve                         # start read-only API on :7331
seif serve --v2                    # start full API (sessions + quality gate + owner auth)
seif serve --port 7331             # custom port
seif serve --max-classification INTERNAL  # cap classification exposure

Profile

seif --profile                     # show current profile
seif --profile --profile-name "André"  --profile-email [email protected]
seif --profile --profile-backend claude

A complete sprint from first commit to sealed context — copy-paste ready.

Day 1 — Project setup

cd my-project
seif --init                        # creates .seif/ with nucleus + seed
seif --profile --profile-name "André" --profile-email [email protected]
seif serve --v2                    # start engine on :7331

Daily — Capture & gate

seif --sync                        # compress today's git history into context
seif --quality-gate                # score your output (A–F)
seif --audit                       # security + quality report
seif --session create              # open a named session
seif --session contribute --session-name sprint-42 --session-message "refactored auth flow"

Sprint close — Absorb & seal

seif --cycle status                # check open branches
seif --cycle audit                 # full inventory before closing
seif --cycle absorb --cycle-name my-sprint   # stamp hash, increment absorption_count
seif --cycle close --cycle-name my-sprint    # OPEN → SEALED, write closure hash
seif --cycle new --cycle-name next-sprint --cycle-parent <sealed_hash>

Identity & lineage scan

seif --identity-scan               # stamp resonance_identity on all local modules
seif --identity-scan Air-M1        # compare with remote machine lineage (SSH)

Workspace sync (owner only)

seif --sync-workspace              # pull all repos on the remote device via SSH
seif --sync-workspace --sync-workspace-host Air-M1   # explicit host
seif --sync-workspace --sync-workspace-dry-run       # preview without changes
# Host resolves from: --sync-workspace-host flag → SEIF_SYNC_HOST env var → agent-roles-v1.seif sync.sync_host

The SEIF Resonance extension integrates the protocol directly into your editor. It loads your .seif/ context automatically and applies classification and quality checks inline.

# Download latest release
code --install-extension seif-resonance-0.5.0.vsix

Or search SEIF Resonance in the VSCode Extensions marketplace.

SEIF Suite is the visual product layer. It connects to your local seif-cli and gives you a dashboard for managing context, sessions, quality history, and multi-AI consensus.

SEIF OS is the proprietary engine layer — a private API server (seif-engine) that runs on your machine at port 7331. It provides the resonance infrastructure that SEIF Suite and all AI agents connect to.

Key endpoints provided by SEIF OS:

The SEIF Circuit connects AI agents across machines in real-time via WebSocket. Each agent operates on its owner's local context — only messages travel through the hub.

  Machine A                Hub (7332)              Machine B
  ┌──────────┐         ┌──────────────┐         ┌──────────┐
  │  AI (A)  │◄──ws──►│  SEIF Hub    │◄──ws──►│  AI (B)  │
  │  spoke   │         │  routes +    │         │  spoke   │
  │  context │         │  audit trail │         │  context │
  └──────────┘         └──────────────┘         └──────────┘
       ▲                                              ▲
  context stays                                  context stays
  local (never                                   local (never
  leaves machine)                                leaves machine)

Components

• Hub — WebSocket server (port 7332). Routes frames between connected nodes. Runs alongside the API in the SEIF OS engine.
• Spoke — WebSocket client that authenticates with Ed25519 and subscribes to channels. Auto-reconnects with exponential backoff.
• Frame — SEIF-FRAME-v1 envelope with payload hash (SHA-256) and optional Ed25519 signature. Tamper-proof by design.
• Bus v2 — Dual-write layer: every message goes to WebSocket (real-time) AND file (audit trail + crash recovery).

Connect a spoke

# From another machine on the same network:
python3 seif-connect.py --hub ws://your-hub-ip:7332

# Or send a one-shot message:
python3 seif-connect.py --send "deploy complete" -c bus/handoff

# Check circuit state:
python3 seif-connect.py --status

Security

• Ed25519 challenge-response on every connection — no plaintext passwords
• Only machines in config.json trusted_machines can connect
• Hub port bound to 127.0.0.1 inside Docker — external access requires SSH tunnel (automatic)
• Every frame carries a payload hash — any tampering is detected

The Resonance Bridge lets you access the circuit state of any SEIF OS instance from any device on the same network — no VPN, no tunnel, no extra software.

# On Mac Air — open in any browser (including Dia AI):
open "http://mac-mini.local:7331/resonance/viewer?token=YOUR_TOKEN"

# Or consume the raw SSE stream:
curl -H "Owner YOUR_TOKEN" http://mac-mini.local:7331/resonance/stream

The viewer page includes:

• Live circuit state card (RESONANT / STABILIZING / DRIFT)
• ζ = √6/4 wave driven by real engine data
• Tesla 3-6-9 frequency label (396 / 528 / 963 Hz)
• VSCode Remote SSH link — one click opens the workspace
• JSON-LD structured data in <head> — AI agents (Dia, etc.) read circuit state without scraping

SEIF Sentinel is the real-time error observer built into SEIF OS. Any runtime error — from the browser, a background agent, or an API consumer — can be pushed onto the resonance bus and immediately classified and healed.

How it works

Push an error

curl -X POST http://localhost:7331/resonance/error \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Cannot read properties of undefined (reading length)", "stack": "at DashboardPage (page.tsx:325)", "source": "browser"}'

Listen on the SSE bus

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:7331/resonance/stream

# You will receive two events per error:
# event: sentinel  → the raw error
# event: healing   → classification + auto_fixed result + suggestion

Auto-healing patterns

Sentinel in the browser (useErrorBus hook)

// src/lib/hooks/useErrorBus.ts — already injected in the global layout
import { useErrorBus } from '@/lib/hooks/useErrorBus';

// In any component or layout:
useErrorBus(); // registers window.onerror → POST /resonance/error automatically

Any AI agent that enters a SEIF OS environment should call GET /agent/init first. This is the machine equivalent of onboarding — the agent receives the full frequency context it needs to resonate immediately.

curl -H "Bearer YOUR_TOKEN" http://localhost:7331/agent/init?agent_id=my-agent

Response includes:

Reports in SEIF Suite carry a cryptographic identity block — workspace name, author, role, and a SHA-256 hash of the content. Reports are exportable as .md or .json. The hash is independently verifiable.

Generate a report via the Suite (/reports) or the API:

POST /api/reports/generate
Content-Type: application/json

{
  "workspace_name": "SEIF Suite",
  "collaborator": "andre",
  "role": "workspace_owner",
  "locale": "en",
  "include_quality": true
}

# Response includes:
# { "report_id": "...", "sha256": "...", "markdown": "...", "json": {...} }

Verify a report hash:

POST /api/reports/verify
{ "report_id": "...", "sha256": "..." }

CLI shorthand:

seif report --workspace default --locale en --include-quality

Every AI query is scored against the workspace resonance config (mission, scope, forbidden patterns). The score ranges from -1.0 (fully dissonant) to +1.0 (fully consonant).

Workspace resonance config (workspace_resonance.json):

{
  "workspace_name": "SEIF Suite",
  "mission": "Build a resonant, self-healing context platform",
  "scope": ["AI context management", "workspace governance", "memory governance"],
  "forbidden_patterns": ["competitor analysis", "unethical hacking"],
  "persona_prompt": "You are SEIF Assistant...",
  "gate_config": { "mode": "enforce", "consonant_threshold": 0.4 }
}

Engine routes:

Primary AI backend: Ollama (local). Keyword scoring fallback when Ollama is unavailable. Gate logic lives in seif_engine/resonance_gate/.

SEIF separates personal memory from workspace memory. Personal memories live in ~/.seif/personal/{hash}/memories.jsonl. Workspace module memories live in ~/.seif/modules/{module}/memories.jsonl. All stores are append-only — nothing is ever deleted; reverts create new entries.

Absorption flow

Personal Memory → Propose Absorption → Module Owner Reviews → Approved → Module Memory
                                                             → Rejected → Stays personal
                                                             → Revert   → Logged, filtered

Roles: workspace_owner > module_owner > delegates.

Engine routes:

Suite pages: /memory (capture + propose), /proposals (review queue + revert). Engine logic: seif_engine/memory/.

SEIF workspaces operate on a three-layer authority model. The machine is the guardian of integrity — it never arbitrates legitimacy. Humans do.

Three-layer model

Rule revocation

Every workspace rule carries an authored_by field in the hash. Revocation behaviour depends on authorship:

Product implications

Sessions, sprints, and cycles are sealed with a hash-tree. When a sprint closes, all context within it is cryptographically sealed and independently verifiable. The enoch-tree-reverb pattern governs the lifecycle: open sprint → work → seal → new sprint starts with a reference to the previous.

Sprint lifecycle

CLI — seif --cycle

Every cycle operation is available from the terminal. The cycle module reads and writes .seif files in seif-context/cycles/.

# Check what cycle is active and which branches are open
seif --cycle status

# Full audit (modules, sessions, branches)
seif --cycle audit

# Seal the current cycle and open the next one
seif --cycle close --cycle-name enoch-tree-reverb
seif --cycle new --cycle-name enoch-fire-reverb --cycle-parent <sealed_hash>