Integration

With Claude Code

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command", 
        "command": "python /path/to/Spark/hooks/observe.py"
      }]
    }],
    "PostToolUseFailure": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python /path/to/Spark/hooks/observe.py"
      }]
    }]
  }
}

With Clawdbot

Spark automatically syncs learnings to workspace files:

• AGENTS.md — Workflow patterns
• TOOLS.md — Tool insights
• SOUL.md — User preferences

With Mind

When Mind is running (python -m mind.lite_tier), Spark syncs learnings for:

• Semantic search across all learnings
• Cross-project pattern transfer
• Decision tracking and outcome attribution

Output Files

| File | Contents | |------|----------| | .learnings/LEARNINGS.md | All cognitive insights | | .learnings/ERRORS.md | Error patterns and recoveries | | ~/.spark/cognitive_insights.json | Raw insight data | | ~/.spark/queue/events.jsonl | Event queue |

Promotion Criteria

Insights are auto-promoted when:

• Reliability ≥ 70%
• Validated ≥ 3 times
• Not already promoted

Promotion targets:

• CLAUDE.md — Wisdom, reasoning, context rules
• AGENTS.md — Meta-learning, self-awareness
• TOOLS.md — Tool-specific context rules
• SOUL.md — User understanding, communication

API

from lib import (
    get_cognitive_learner,
    sync_all_to_mind,
    write_all_learnings,
    check_and_promote,
)

# Get learner instance
cognitive = get_cognitive_learner()

# Learn something
cognitive.learn_why(
    what_worked="Read before Edit",
    why_it_worked="Prevents content mismatch errors",
    context="File editing workflow"
)

# Sync to Mind
sync_all_to_mind()

# Write to markdown
write_all_learnings()

# Promote proven insights
check_and_promote()

Part of Vibeship

• Mind — Persistent memory with semantic search
• Spark — Self-evolving intelligence (this)
• Spawner — Skill loading and orchestration
• H70 — 500+ expert skills

Windows one-command bootstrap (clone + venv + install + start + health):

irm https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.ps1 | iex

Optional re-check (from repo root):

.\.venv\Scripts\python -m spark.cli up
.\.venv\Scripts\python -m spark.cli health

If you already cloned the repo, run the local bootstrap:

.\install.ps1

If you are running from cmd.exe or another shell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.ps1 | iex"

Mac/Linux one-command bootstrap (clone + venv + install + start):

curl -fsSL https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.sh | bash

Then verify runtime readiness (second command, from repo root):

./.venv/bin/python -m spark.cli up
./.venv/bin/python -m spark.cli health

Mac/Linux manual install:

git clone https://github.com/vibeforge1111/vibeship-spark-intelligence
cd vibeship-spark-intelligence
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .[services]

If your system uses PEP 668 / external package management, this avoids the externally-managed-environment error:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .[services]

Or run directly with editable install:

python -m pip install vibeship-spark-intelligence[services]
python -m spark.cli up

Quick Start

# Check health
python -m spark.cli health

# View what Spark has learned
python -m spark.cli learnings

Windows: run start_spark.bat from the repo root.

Lightweight mode (core only, no Pulse/watchdog): spark up --lite

Connect Your Agent

Spark works with any coding agent that supports hooks or event capture.

| Agent | Integration | Guide | |-------|------------|-------| | Claude Code | Hooks (PreToolUse, PostToolUse, UserPromptSubmit) | docs/claude_code.md | | Codex | Session JSONL hook bridge (shadow/observe rollout) | docs/CODEX_HOOK_BRIDGE_ROLLOUT.md | | Cursor / VS Code | tasks.json + emit_event | docs/cursor.md | | OpenClaw | Session JSONL tailer | docs/openclaw/ |

What You Get

• Self-evolving companion behavior — adapts from your sessions instead of staying static.
• Signal capture — hooks + event ingestion for tool actions, prompts, and outcomes.
• Distillation pipeline — low-quality/raw observations are filtered out before storage.
• Transformation layer — converts insight candidates into actionable advisory-ready forms.
• Advisory delivery — pre-tool guidance ranked across retrieval sources with cool-down and dedupe.
• EIDOS loop — prediction → outcome → evaluation for continuous quality updates.
• Domain chips — pluggable expertise modules that can specialize behavior.
• Observability surfaces — Obsidian Observatory in-repo, plus optional external Spark Pulse (separate vibeship-spark-pulse app; spark_pulse.py is a redirector) and local Meta-Ralph views.
• CLI — spark status, spark learnings, spark promote, spark up/down, and more.
• Hot-reloadable config — tuneables with schema checks and live behavior shifts.

Architecture

Your Agent (Claude Code / Cursor / OpenClaw)
  -> hooks capture events
  -> queue -> bridge worker -> pipeline
  -> quality gate (Meta-Ralph) -> cognitive learner
  -> distillation -> transformation -> advisory packaging
  -> pre-tool advisory surfaced + context files refreshed

Obsidian Observatory

Spark ships with an Obsidian integration that turns the entire intelligence pipeline into a human-readable vault you can browse, search, and query — every insight, every decision, every quality verdict, visible in one place.

Install Obsidian

1. Download Obsidian (free, available on Windows / Mac / Linux)
2. Install and open it

Generate the Observatory

# From the spark-intelligence repo:
python scripts/generate_observatory.py --force --verbose

This reads your ~/.spark/ state files and generates ~465+ markdown pages in under 1 second.

Default vault location: ~/Documents/Obsidian Vault/Spark-Intelligence-Observatory

To change it, edit observatory.vault_dir in ~/.spark/tuneables.json or config/tuneables.json.

Open the Vault

1. In Obsidian: File > Open vault > Open folder as vault
2. Select Spark-Intelligence-Observatory
3. It opens to _observatory/flow.md — the main pipeline dashboard

The vault comes pre-configured with:

• Dataview plugin pre-installed (for live queries on all data)
• Workspace set to open the Flow Dashboard + Dataview Dashboard
• Graph view color-coded: green = pipeline stages, blue = explorer items, orange = advisory packets

Install Dataview (recommended)

If Dataview didn't auto-install from the pre-configured vault:

1. Go to Settings > Community plugins > Turn on community plugins
2. Click Browse > search "Dataview" > Install > Enable
3. The Dashboard.md queries will now render live tables

What You Can See

Flow Dashboard (_observatory/flow.md)

A live Mermaid diagram of the full 12-stage pipeline with embedded metrics — queue depth, processing rate, insight counts, advisory follow rate, and more. Plus a system health table with status badges.

12 Stage Detail Pages (_observatory/stages/)

Each pipeline stage gets its own page with health metrics, recent activity, and upstream/downstream links:

| Stage | What it shows | |-------|--------------| | Event Capture | Hook heartbeat, session tracking | | Queue | Pending events, file size, overflow | | Pipeline | Processing rate, batch size, empty cycles | | Memory Capture | Importance scores, category distribution | | Meta-Ralph | Quality verdicts, pass rate, score distribution | | Cognitive Learner | Insight count, reliability leaders, categories | | EIDOS | Episodes, steps, distillations, predict-evaluate loop | | Advisory | Follow rate, source effectiveness, recent advice | | Promotion | Targets, recent activity, result distribution | | Chips | Domain modules, per-chip activity and size | | Predictions | Outcomes, surprise tracking, link rate | | Tuneables | Current config, all sections listed |

Explorer — Browse Your Data (_observatory/explore/)

Click into any data store and browse individual items:

| Dataset | Pages | What you see | |---------|-------|-------------| | Cognitive Insights | ~150 detail pages | Reliability, validations, evidence, counter-examples | | EIDOS Distillations | ~90 detail pages | Statement, confidence, domains, triggers | | EIDOS Episodes | ~100 detail pages | Goal, outcome, every step with prediction vs evaluation | | Meta-Ralph Verdicts | ~100 detail pages | Score breakdown (6 dimensions), input text, issues | | Advisory Decisions | Index table | Every emit/suppress/block decision with reasons | | Implicit Feedback | Index table | Followed/ignored signals, per-tool follow rates | | Retrieval Routing | Index table | Route distribution, why advice was/wasn't surfaced | | Tuneable Evolution | Index table | Parameter changes over time with impact analysis | | Promotions | Index table | What got promoted to CLAUDE.md and why | | Advisory Effectiveness | Index table | Source effectiveness, overall follow rate |

Canvas View (_observatory/flow.canvas)

A spatial layout of the pipeline — drag, zoom, click thr