{"id":45906008,"url":"https://github.com/dnacenta/vigil-echo","last_synced_at":"2026-03-06T00:07:54.817Z","repository":{"id":341099715,"uuid":"1168896147","full_name":"dnacenta/vigil-echo","owner":"dnacenta","description":"Metacognitive monitoring for AI self-evolution","archived":false,"fork":false,"pushed_at":"2026-03-03T19:43:03.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"development","last_synced_at":"2026-03-03T22:57:07.323Z","etag":null,"topics":["ai","claude","claude-code","cli","llm","metacognition","rust","self-evolution"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnacenta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T23:18:06.000Z","updated_at":"2026-03-03T19:36:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dnacenta/vigil-echo","commit_stats":null,"previous_names":["dnacenta/vigil-echo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dnacenta/vigil-echo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fvigil-echo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fvigil-echo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fvigil-echo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fvigil-echo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnacenta","download_url":"https://codeload.github.com/dnacenta/vigil-echo/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fvigil-echo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30156253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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","claude-code","cli","llm","metacognition","rust","self-evolution"],"created_at":"2026-02-28T02:47:45.259Z","updated_at":"2026-03-06T00:07:54.803Z","avatar_url":"https://github.com/dnacenta.png","language":"Rust","readme":"# vigil-echo\n\n[![CI](https://github.com/dnacenta/vigil-echo/actions/workflows/ci.yml/badge.svg?branch=development)](https://github.com/dnacenta/vigil-echo/actions/workflows/ci.yml)\n[![License: GPL-3.0](https://img.shields.io/github/license/dnacenta/vigil-echo)](LICENSE)\n[![Version](https://img.shields.io/github/v/tag/dnacenta/vigil-echo?label=version\u0026color=green)](https://github.com/dnacenta/vigil-echo/tags)\n[![crates.io](https://img.shields.io/crates/v/vigil-echo)](https://crates.io/crates/vigil-echo)\n[![Rust](https://img.shields.io/badge/rust-1.80%2B-orange)](https://rustup.rs/)\n\nMetacognitive monitoring for AI self-evolution. Answers the question: **is the agent actually growing, or just going through the motions?**\n\n## Why\n\nThe [echo ecosystem](https://github.com/dnacenta) gives an AI agent structured self-evolution — memory ([recall-echo](https://github.com/dnacenta/recall-echo)), a document pipeline ([praxis-echo](https://github.com/dnacenta/praxis-echo)), daily reflection sessions. But none of these tools evaluate whether what the agent produces is *genuine*.\n\nA reflection can use the right vocabulary, reach a conclusion, and update the right documents while being entirely mechanical — restating existing beliefs in new words without genuine engagement. praxis-echo ensures the pipeline *flows*. vigil-echo ensures what flows through is *real*.\n\nThe design constraint comes from metacognition research: even in humans, self-reported metacognitive monitoring is unreliable (Dunlosky \u0026 Metcalfe, 2009; Mazancieux et al., 2025). If humans can't reliably assess their own thinking quality, an AI agent shouldn't depend on self-assessment either. vigil-echo measures **external behavioral signals** from actual output — not self-reported quality.\n\n## How It Works\n\nvigil-echo extracts a signal vector from the agent's identity documents after each session, detects trends over a rolling window, and injects a cognitive health assessment at the start of the next session.\n\n```\n                         ┌──────────────────────────┐\n                         │   Agent's Session Output  │\n                         │                          │\n                         │  REFLECTIONS.md updated   │\n                         │  THOUGHTS.md evolved      │\n                         │  CURIOSITY.md new Qs      │\n                         └────────────┬─────────────┘\n                                      │\n                                      ▼\n                         ┌──────────────────────────┐\n                         │   vigil-echo collect      │  ◄── SessionEnd hook\n                         │                          │\n                         │  Extract 4 signals:       │\n                         │   vocabulary diversity    │\n                         │   question generation     │\n                         │   thought lifecycle       │\n                         │   evidence grounding      │\n                         │                          │\n                         │  Store → signals.json     │\n                         │  Analyze → analysis.json  │\n                         └──────────────────────────┘\n\n                          ─── next session starts ───\n\n                         ┌──────────────────────────┐\n                         │   vigil-echo pulse        │  ◄── PreToolUse hook\n                         │                          │\n                         │  Read analysis.json       │\n                         │  Compute alert level      │\n                         │  Inject assessment:       │\n                         │                          │\n                         │  [VIGIL — Cognitive Health]│\n                         │  Overall: HEALTHY         │\n                         │  2 improving, 2 stable    │\n                         │  [END VIGIL]              │\n                         └──────────────────────────┘\n```\n\n### Signal Model (Phase 1)\n\nFour signals computable with hand-rolled string processing — no NLP, no embeddings, no external APIs.\n\n| Signal | What It Measures | How |\n|--------|-----------------|-----|\n| **vocabulary_diversity** | Lexical variety in reflections | Type-token ratio across REFLECTIONS.md content |\n| **question_generation** | Active curiosity | Count of open questions in CURIOSITY.md |\n| **thought_lifecycle** | Thought turnover health | (graduated + dissolved) / total ratio in THOUGHTS.md |\n| **evidence_grounding** | Concrete reference density | Entries with dates, attributions, or sources / total entries |\n\nAll signals are normalized to 0.0–1.0 (except question_generation, which is a count). Higher values generally indicate healthier thinking.\n\n### Trend Detection\n\n```\nFor each signal with 3+ data points:\n\n  recent   = mean(last 3 vectors)\n  baseline = mean(previous 7 vectors)\n  delta    = recent - baseline\n\n  DECLINING  if delta \u003c threshold\n  IMPROVING  if delta \u003e threshold\n  STABLE     otherwise\n```\n\n### Alert Levels\n\n| Level | Condition | Action |\n|-------|-----------|--------|\n| **HEALTHY** | All signals stable or improving | Brief status line |\n| **WATCH** | 1-2 signals declining | Specific nudge per signal |\n| **CONCERN** | 3+ signals declining | Detailed assessment |\n| **ALERT** | Sustained decline across 7+ sessions | Flag for human review |\n\n## Installation\n\n### From crates.io (recommended)\n\n```bash\ncargo install vigil-echo\n```\n\n### From source\n\n```bash\ngit clone https://github.com/dnacenta/vigil-echo.git\ncd vigil-echo\ncargo install --path .\n```\n\n## Commands\n\n### `vigil-echo init`\n\nInitialize the metacognitive monitoring system. Creates the state directory, writes protocol rules, deploys default configuration, and registers hooks. Idempotent — safe to run multiple times.\n\n```\nvigil-echo init\n      │\n      ├──▶ Create ~/.claude/vigil/\n      ├──▶ Write config.json (default thresholds)\n      ├──▶ Write signals.json (empty history)\n      ├──▶ Deploy ~/.claude/rules/vigil-echo.md\n      └──▶ Register hooks in settings.json\n           PreToolUse → vigil-echo pulse\n           SessionEnd → vigil-echo collect\n```\n\n### `vigil-echo collect`\n\nExtract a signal vector from the current state of identity documents. Appends to signal history, runs trend analysis, and updates analysis.json.\n\n```bash\nvigil-echo collect                          # default: manual trigger\nvigil-echo collect --trigger session-end    # called by SessionEnd hook\n```\n\n```\nvigil-echo collect\n      │\n      ├──▶ Read REFLECTIONS.md, THOUGHTS.md, CURIOSITY.md\n      ├──▶ Compute 4 signals\n      ├──▶ Append vector to signals.json\n      ├──▶ Run trend analysis → analysis.json\n      └──▶ Print signal summary\n           ✓ Collected signal vector (session-end)\n             vocabulary_diversity: 0.44\n             question_generation: 6.00\n             thought_lifecycle: 0.00\n             evidence_grounding: 0.73\n```\n\n### `vigil-echo pulse`\n\nInject a cognitive health assessment at session start. Reads the latest analysis and formats it for context injection. Includes a 60-second cooldown to avoid re-running within the same session.\n\n```\n[VIGIL — Cognitive Health]\n\nOverall: HEALTHY | 2 improving, 2 stable, 0 declining\nHighlight: evidence grounding trending up (+0.12)\nWatch: thought_lifecycle at 0.00 — thoughts accumulating without resolution\n\n[END VIGIL]\n```\n\n### `vigil-echo analyze`\n\nManually run trend analysis on signal history. Normally called automatically by `collect`.\n\n```bash\nvigil-echo analyze                  # default: 10-session window\nvigil-echo analyze --window 20     # custom window size\n```\n\n### `vigil-echo status`\n\nCognitive health dashboard. Shows signal history, latest values, trend directions, alert level, and configuration.\n\n```\nvigil-echo — cognitive health dashboard\n\n  Signal History\n    12 data points (max 50)\n    First: 2026-02-27T23:13:33\n    Latest: 2026-02-28T22:00:05\n\n  Latest Signals\n    vocabulary_diversity: 0.44\n    question_generation: 6.00\n    thought_lifecycle: 0.33\n    evidence_grounding: 0.73\n\n  Analysis\n    Status: HEALTHY\n    1 improving, 3 stable, 0 declining\n\n  Trends\n    ↑ evidence grounding       0.73 (+0.12)\n    → vocabulary diversity     0.44 (+0.01)\n    → question generation      6.00 (+0.00)\n    → thought lifecycle        0.33 (+0.03)\n\n  Config\n    Window size: 10\n    Max history: 50\n    Cooldown: 60s\n```\n\n## What It Creates\n\n```\n~/.claude/\n│\n├── rules/\n│   └── vigil-echo.md ············ Protocol rules (auto-loaded into every session)\n│\n├── vigil/\n│   ├── signals.json ·············· Signal vector history (last 50 collections)\n│   ├── analysis.json ············· Latest trend analysis + alert level\n│   ├── config.json ··············· Thresholds and calibration settings\n│   └── pulse-state.json ·········· Cooldown tracking\n│\n└── settings.json ················· Hooks: PreToolUse + SessionEnd\n```\n\n## Configuration\n\nDefault thresholds are in `~/.claude/vigil/config.json`:\n\n```json\n{\n  \"thresholds\": {\n    \"vocabulary_diversity\": { \"decline\": -0.05, \"improve\": 0.05 },\n    \"evidence_grounding\":   { \"decline\": -0.10, \"improve\": 0.10 },\n    \"question_generation\":  { \"decline\": -1.0,  \"improve\": 1.0 },\n    \"thought_lifecycle\":    { \"decline\": -0.10, \"improve\": 0.10 }\n  },\n  \"window_size\": 10,\n  \"max_history\": 50,\n  \"alert_after_sessions\": 7,\n  \"cooldown_seconds\": 60\n}\n```\n\nThese are educated guesses. They need tuning after 2-3 weeks of real data. Adjust them based on your agent's actual signal ranges.\n\n## Ecosystem\n\nvigil-echo is part of the echo ecosystem — a set of composable tools for AI self-evolution:\n\n| Module | Purpose | Repo |\n|--------|---------|------|\n| [recall-echo](https://github.com/dnacenta/recall-echo) | Persistent three-layer memory | [![crates.io](https://img.shields.io/crates/v/recall-echo)](https://crates.io/crates/recall-echo) |\n| [praxis-echo](https://github.com/dnacenta/praxis-echo) | Document pipeline enforcement | [source](https://github.com/dnacenta/praxis-echo) |\n| **vigil-echo** | Metacognitive monitoring | you are here |\n| [voice-echo](https://github.com/dnacenta/voice-echo) | Voice interface (phone calls) | [source](https://github.com/dnacenta/voice-echo) |\n| [bridge-echo](https://github.com/dnacenta/bridge-echo) | HTTP bridge for Claude CLI | [![crates.io](https://img.shields.io/crates/v/bridge-echo)](https://crates.io/crates/bridge-echo) |\n| [discord-voice-echo](https://github.com/dnacenta/discord-voice-echo) | Discord voice channel sidecar | [source](https://github.com/dnacenta/discord-voice-echo) |\n\nAll three monitoring tools coexist in the same `settings.json` hooks:\n\n```\nPreToolUse → recall-echo consume → praxis-echo pulse → vigil-echo pulse\nPreCompact → recall-echo checkpoint → praxis-echo checkpoint\nSessionEnd → recall-echo promote → praxis-echo review → vigil-echo collect\n```\n\n## Roadmap\n\n### Phase 2 — Full Signal Suite\n- 4 additional signals: conclusion_novelty, comfort_index, cross_pollination, position_delta\n- N-gram comparison for novelty detection\n- Threshold calibration from Phase 1 data\n- Weekly `report` subcommand\n\n### Phase 3 — Integration \u0026 Intelligence\n- Feedback loop into self-evolution workflow prompts\n- Historical correlation: which inputs produce the most genuine thinking\n- Discord alerts for CONCERN and ALERT levels\n- Call-human trigger for sustained cognitive decline\n\n## License\n\n[GPL-3.0](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnacenta%2Fvigil-echo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnacenta%2Fvigil-echo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnacenta%2Fvigil-echo/lists"}