{"id":49551037,"url":"https://github.com/vibeforge1111/vibeship-spark-intelligence","last_synced_at":"2026-05-02T22:10:13.255Z","repository":{"id":339821975,"uuid":"1142883385","full_name":"vibeforge1111/vibeship-spark-intelligence","owner":"vibeforge1111","description":"a self-evolving intelligent companion","archived":false,"fork":false,"pushed_at":"2026-02-28T23:08:57.000Z","size":12643,"stargazers_count":106,"open_issues_count":120,"forks_count":29,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T02:07:16.963Z","etag":null,"topics":["ai","claude-code","cursor","developer-tools","intelligence","local-first","machine-learning","open-source","self-evolving"],"latest_commit_sha":null,"homepage":"https://spark.vibeship.co","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vibeforge1111.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"docs/support/DAILY_SUPPORT_TRACKING.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-27T00:48:04.000Z","updated_at":"2026-02-28T15:41:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vibeforge1111/vibeship-spark-intelligence","commit_stats":null,"previous_names":["vibeforge1111/vibeship-spark-intelligence"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vibeforge1111/vibeship-spark-intelligence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibeforge1111%2Fvibeship-spark-intelligence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibeforge1111%2Fvibeship-spark-intelligence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibeforge1111%2Fvibeship-spark-intelligence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibeforge1111%2Fvibeship-spark-intelligence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vibeforge1111","download_url":"https://codeload.github.com/vibeforge1111/vibeship-spark-intelligence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibeforge1111%2Fvibeship-spark-intelligence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32551017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T21:31:48.061Z","status":"ssl_error","status_checked_at":"2026-05-02T21:31:46.574Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","cursor","developer-tools","intelligence","local-first","machine-learning","open-source","self-evolving"],"created_at":"2026-05-02T22:10:12.648Z","updated_at":"2026-05-02T22:10:13.248Z","avatar_url":"https://github.com/vibeforge1111.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://spark.vibeship.co\"\u003e\u003cimg src=\"header.png\" alt=\"Spark Intelligence\" width=\"100%\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/vibeforge1111/vibeship-spark-intelligence/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue?style=flat-square\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/runs-100%25_local-green?style=flat-square\" alt=\"Local\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-Win%20%7C%20Mac%20%7C%20Linux-lightgrey?style=flat-square\" alt=\"Platform\"\u003e\n\u003c/p\u003e\n\n---\n\nLearns constantly. Adapts with your flow.\nRuns 100% on your machine as a local AI companion that turns past work into future-ready behavior.\nIt is designed to be beyond a learning loop.\n\n`You do work` -\u003e `Spark captures memory` -\u003e `Spark distills and transforms it` -\u003e `Spark delivers advisory context` -\u003e `You act with better context` -\u003e `Outcomes re-enter the loop`\n\n## What is Spark?\n\nSpark Intelligence is a self-evolving AI companion designed to grow smarter through use.\n\nIt is:\n- Not a chatbot.\n- Not a fixed rule set.\n- A living intelligence runtime that continuously converts experience into adaptive operational behavior, not just stored memory.\n\nThe goal is to keep context, patterns, and practical lessons in a form that your agent can actually use at the right moment.\n\n## Beyond a Learning Loop: Intelligence Operating Flow\n\n- Capture: hooks and events from your agent sessions are converted into structured memories.\n- Distill: noisy data is filtered into reliable, action-oriented insights.\n- Transform: high-value items are shaped for practical reuse (prioritized by reliability, context match, and usefulness).\n- Store: distilled wisdom is persisted and versioned in local memory stores.\n- Act: advisory and context updates are prepared for the right point in workflow.\n- Guard: gating layers check quality, authority, cooldown, and dedupe before any advisory is surfaced.\n- Learn: outcomes and follow-through are fed back to refine future recommendations.\n\n## Install\n\nPrerequisites:\n- Python 3.10+ (Windows one-liner auto-installs latest Python 3 via `winget` when missing)\n- `pip`\n- Git\n- Windows one-liner path: PowerShell\n- Mac/Linux one-liner path: `curl` + `bash`\n\nWindows one-command bootstrap (clone + venv + install + start + health):\n\n```powershell\nirm https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.ps1 | iex\n```\n\nOptional re-check (from repo root):\n\n```powershell\n.\\.venv\\Scripts\\python -m spark.cli up\n.\\.venv\\Scripts\\python -m spark.cli health\n```\n\nIf you already cloned the repo, run the local bootstrap:\n\n```powershell\n.\\install.ps1\n```\n\nIf you are running from `cmd.exe` or another shell:\n\n```powershell\npowershell -NoProfile -ExecutionPolicy Bypass -Command \"irm https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.ps1 | iex\"\n```\n\nMac/Linux one-command bootstrap (clone + venv + install + start):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vibeforge1111/vibeship-spark-intelligence/main/install.sh | bash\n```\n\nThen verify runtime readiness (second command, from repo root):\n\n```bash\n./.venv/bin/python -m spark.cli up\n./.venv/bin/python -m spark.cli health\n```\n\nMac/Linux manual install:\n\n```bash\ngit clone https://github.com/vibeforge1111/vibeship-spark-intelligence\ncd vibeship-spark-intelligence\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npython -m pip install -e .[services]\n```\n\nIf your system uses PEP 668 / external package management, this avoids the\n`externally-managed-environment` error:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e .[services]\n```\n\nOr run directly with editable install:\n\n```bash\npython -m pip install vibeship-spark-intelligence[services]\npython -m spark.cli up\n```\n\n## Quick Start\n\n```bash\n# Check health\npython -m spark.cli health\n\n# View what Spark has learned\npython -m spark.cli learnings\n```\n\nWindows: run `start_spark.bat` from the repo root.\n\nLightweight mode (core only, no Pulse/watchdog): `spark up --lite`\n\n## Connect Your Agent\n\nSpark works with any coding agent that supports hooks or event capture.\n\n| Agent | Integration | Guide |\n|-------|------------|-------|\n| **Claude Code** | Hooks (PreToolUse, PostToolUse, UserPromptSubmit) | `docs/claude_code.md` |\n| **Codex** | Session JSONL hook bridge (shadow/observe rollout) | `docs/CODEX_HOOK_BRIDGE_ROLLOUT.md` |\n| **Cursor / VS Code** | tasks.json + emit_event | `docs/cursor.md` |\n| **OpenClaw** | Session JSONL tailer | `docs/openclaw/` |\n\n## What You Get\n\n- **Self-evolving companion behavior** — adapts from your sessions instead of staying static.\n- **Signal capture** — hooks + event ingestion for tool actions, prompts, and outcomes.\n- **Distillation pipeline** — low-quality/raw observations are filtered out before storage.\n- **Transformation layer** — converts insight candidates into actionable advisory-ready forms.\n- **Advisory delivery** — pre-tool guidance ranked across retrieval sources with cool-down and dedupe.\n- **EIDOS loop** — prediction → outcome → evaluation for continuous quality updates.\n- **Domain chips** — pluggable expertise modules that can specialize behavior.\n- **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.\n- **CLI** — `spark status`, `spark learnings`, `spark promote`, `spark up/down`, and more.\n- **Hot-reloadable config** — tuneables with schema checks and live behavior shifts.\n\n## Architecture\n\n```\nYour Agent (Claude Code / Cursor / OpenClaw)\n  -\u003e hooks capture events\n  -\u003e queue -\u003e bridge worker -\u003e pipeline\n  -\u003e quality gate (Meta-Ralph) -\u003e cognitive learner\n  -\u003e distillation -\u003e transformation -\u003e advisory packaging\n  -\u003e pre-tool advisory surfaced + context files refreshed\n```\n\n## Obsidian Observatory\n\nSpark ships with an [Obsidian](https://obsidian.md) 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.\n\n### Install Obsidian\n\n1. Download [Obsidian](https://obsidian.md) (free, available on Windows / Mac / Linux)\n2. Install and open it\n\n### Generate the Observatory\n\n```bash\n# From the spark-intelligence repo:\npython scripts/generate_observatory.py --force --verbose\n```\n\nThis reads your `~/.spark/` state files and generates ~465+ markdown pages in under 1 second.\n\n**Default vault location:** `~/Documents/Obsidian Vault/Spark-Intelligence-Observatory`\n\nTo change it, edit `observatory.vault_dir` in `~/.spark/tuneables.json` or `config/tuneables.json`.\n\n### Open the Vault\n\n1. In Obsidian: **File \u003e Open vault \u003e Open folder as vault**\n2. Select `Spark-Intelligence-Observatory`\n3. It opens to `_observatory/flow.md` — the main pipeline dashboard\n\nThe vault comes pre-configured with:\n- **Dataview plugin** pre-installed (for live queries on all data)\n- **Workspace** set to open the Flow Dashboard + Dataview Dashboard\n- **Graph view** color-coded: green = pipeline stages, blue = explorer items, orange = advisory packets\n\n### Install Dataview (recommended)\n\nIf Dataview didn't auto-install from the pre-configured vault:\n\n1. Go to **Settings \u003e Community plugins \u003e Turn on community plugins**\n2. Click **Browse** \u003e search \"Dataview\" \u003e **Install** \u003e **Enable**\n3. The `Dashboard.md` queries will now render live tables\n\n### What You Can See\n\n#### Flow Dashboard (`_observatory/flow.md`)\n\nA 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.\n\n#### 12 Stage Detail Pages (`_observatory/stages/`)\n\nEach pipeline stage gets its own page with health metrics, recent activity, and upstream/downstream links:\n\n| Stage | What it shows |\n|-------|--------------|\n| Event Capture | Hook heartbeat, session tracking |\n| Queue | Pending events, file size, overflow |\n| Pipeline | Processing rate, batch size, empty cycles |\n| Memory Capture | Importance scores, category distribution |\n| Meta-Ralph | Quality verdicts, pass rate, score distribution |\n| Cognitive Learner | Insight count, reliability leaders, categories |\n| EIDOS | Episodes, steps, distillations, predict-evaluate loop |\n| Advisory | Follow rate, source effectiveness, recent advice |\n| Promotion | Targets, recent activity, result distribution |\n| Chips | Domain modules, per-chip activity and size |\n| Predictions | Outcomes, surprise tracking, link rate |\n| Tuneables | Current config, all sections listed |\n\n#### Explorer — Browse Your Data (`_observatory/explore/`)\n\nClick into any data store and browse individual items:\n\n| Dataset | Pages | What you see |\n|---------|-------|-------------|\n| **Cognitive Insights** | ~150 detail pages | Reliability, validations, evidence, counter-examples |\n| **EIDOS Distillations** | ~90 detail pages | Statement, confidence, domains, triggers |\n| **EIDOS Episodes** | ~100 detail pages | Goal, outcome, every step with prediction vs evaluation |\n| **Meta-Ralph Verdicts** | ~100 detail pages | Score breakdown (6 dimensions), input text, issues |\n| **Advisory Decisions** | Index table | Every emit/suppress/block decision with reasons |\n| **Implicit Feedback** | Index table | Followed/ignored signals, per-tool follow rates |\n| **Retrieval Routing** | Index table | Route distribution, why advice was/wasn't surfaced |\n| **Tuneable Evolution** | Index table | Parameter changes over time with impact analysis |\n| **Promotions** | Index table | What got promoted to CLAUDE.md and why |\n| **Advisory Effectiveness** | Index table | Source effectiveness, overall follow rate |\n\n#### Canvas View (`_observatory/flow.canvas`)\n\nA spatial layout of the pipeline — drag, zoom, click through to any stage. Great for presentations or getting the big picture.\n\n#### Dataview Dashboard (`Dashboard.md`)\n\nPre-built live queries you can customize:\n- High-reliability insights (90%+)\n- Promoted insights and where they went\n- Recent successful and failed episodes\n- Meta-Ralph verdicts with high scores\n- Most-retrieved distillations\n- Advisory health and feedback signals\n- System evolution tracking\n\n### Auto-Sync\n\nWhen Spark's pipeline is running, the observatory auto-refreshes every 120 seconds. No manual regeneration needed. To regenerate manually:\n\n```bash\npython scripts/generate_observatory.py --force --verbose\n```\n\n### Configuration\n\nAll settings live in the `observatory` section of your tuneables:\n\n```json\n{\n  \"observatory\": {\n    \"enabled\": true,\n    \"auto_sync\": true,\n    \"sync_cooldown_s\": 120,\n    \"vault_dir\": \"path/to/your/vault\",\n    \"generate_canvas\": true,\n    \"max_recent_items\": 20,\n    \"explore_cognitive_max\": 200,\n    \"explore_distillations_max\": 200,\n    \"explore_episodes_max\": 100,\n    \"explore_verdicts_max\": 100,\n    \"explore_decisions_max\": 200,\n    \"explore_feedback_max\": 200,\n    \"explore_routing_max\": 100,\n    \"explore_tuning_max\": 200\n  }\n}\n```\n\nEdit `~/.spark/tuneables.json` (runtime) or `config/tuneables.json` (version-controlled).\n\n### Tips\n\n- **Start from `flow.md`** — it's the entry point. Drill down into stages, then into the explorer.\n- **Don't edit `_observatory/` files** — they get regenerated. Use `Dashboard.md` or create your own notes alongside.\n- **Use Graph View** — filter to `_observatory` to see how everything connects.\n- **Bookmark items** — bookmarks persist across regenerations since file paths stay stable.\n- **Keep limits under 500** per explorer section for smooth Obsidian performance.\n- **Pin `flow.md` as a tab** — always-visible health check.\n- **Use the Canvas for demos** — `flow.canvas` is a great way to explain the system to others.\n\nFull guide: [`docs/OBSIDIAN_OBSERVATORY_GUIDE.md`](docs/OBSIDIAN_OBSERVATORY_GUIDE.md)\n\n## Documentation\n\n- **Start here (canonical onboarding)**: `docs/SPARK_ONBOARDING_COMPLETE.md`\n- **Fast path (5 minutes)**: `docs/GETTING_STARTED_5_MIN.md`\n- **CLI + operations quickstart**: `docs/QUICKSTART.md`\n- **Obsidian Observatory**: `docs/OBSIDIAN_OBSERVATORY_GUIDE.md`\n- **Docs index**: `docs/DOCS_INDEX.md`\n- **Repo hygiene policy**: `REPO_HYGIENE.md`\n- **Website**: [spark.vibeship.co](https://spark.vibeship.co)\n- **Contributing**: `CONTRIBUTING.md` (local setup, PR flow, and safety expectations)\n\n## Responsible Use\n\nThis is a self-evolving system. If you are planning a public release or high-autonomy deployment:\n- Read first: `docs/AI_MANIFESTO.md`\n- Read first: https://aimanifesto.vibeship.co/\n- `docs/RESPONSIBLE_PUBLIC_RELEASE.md`\n- `docs/security/THREAT_MODEL.md`\n- `SECURITY.md` for vulnerability reporting\n\n## License\n\n[MIT](LICENSE) — free to use, modify, and distribute.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt by \u003ca href=\"https://vibeship.com\"\u003eVibeship\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibeforge1111%2Fvibeship-spark-intelligence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvibeforge1111%2Fvibeship-spark-intelligence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibeforge1111%2Fvibeship-spark-intelligence/lists"}