name: spark description: "Self-evolving intelligence layer. Auto-captures learnings from tool usage, stores in Mind, writes to markdown, and promotes high-value insights to CLAUDE.md/AGENTS.md. Use when: (1) Starting a new session to load cognitive context, (2) After errors to learn from failures, (3) When patterns emerge to extract skills, (4) Periodically to sync and promote learnings."

Spark

Self-evolving intelligence layer for AI agents.

What It Does

Spark automatically:

1. Observes every tool call and its outcome
2. Learns cognitive patterns (not just what worked, but WHY)
3. Stores learnings in Mind for semantic retrieval
4. Writes human-readable logs to .learnings/
5. Promotes proven insights to CLAUDE.md/AGENTS.md
6. Extracts recurring patterns into reusable skills

Quick Reference

Cognitive Categories

Spark learns in these categories:

CLI Commands

# Check system status
python cli.py status

# Sync to Mind
python cli.py sync

# Write learnings to markdown
python cli.py write

# Promote ready insights
python cli.py promote

# Sync bootstrap context to platform files
python cli.py sync-context

# Preview/apply decay-based pruning
python cli.py decay

# View recent learnings
python cli.py learnings --limit 20

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

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

Learns constantly. Adapts with your flow. Runs 100% on your machine as a local AI companion that turns past work into future-ready behavior. It is designed to be beyond a learning loop.

You do work -> Spark captures memory -> Spark distills and transforms it -> Spark delivers advisory context -> You act with better context -> Outcomes re-enter the loop

What is Spark?

Spark Intelligence is a self-evolving AI companion designed to grow smarter through use.

It is:

• Not a chatbot.
• Not a fixed rule set.
• A living intelligence runtime that continuously converts experience into adaptive operational behavior, not just stored memory.

The goal is to keep context, patterns, and practical lessons in a form that your agent can actually use at the right moment.

Beyond a Learning Loop: Intelligence Operating Flow

• Capture: hooks and events from your agent sessions are converted into structured memories.
• Distill: noisy data is filtered into reliable, action-oriented insights.
• Transform: high-value items are shaped for practical reuse (prioritized by reliability, context match, and usefulness).
• Store: distilled wisdom is persisted and versioned in local memory stores.
• Act: advisory and context updates are prepared for the right point in workflow.
• Guard: gating layers check quality, authority, cooldown, and dedupe before any advisory is surfaced.
• Learn: outcomes and follow-through are fed back to refine future recommendations.

Install

Prerequisites:

• Python 3.10+ (Windows one-liner auto-installs latest Python 3 via winget when missing)
• pip
• Git
• Windows one-liner path: PowerShell
• Mac/Linux one-liner path: curl + bash

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.

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:

Explorer — Browse Your Data (_observatory/explore/)

Click into any data store and browse individual items:

Canvas View (_observatory/flow.canvas)

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