{"id":50507679,"url":"https://github.com/indigokarasu/finch","last_synced_at":"2026-06-02T17:31:23.236Z","repository":{"id":358814581,"uuid":"1240276079","full_name":"indigokarasu/finch","owner":"indigokarasu","description":"Finch: self-improvement orchestrator — mines session history to detect corrections, breakthroughs, and behavioral patterns.","archived":false,"fork":false,"pushed_at":"2026-05-23T04:23:39.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T06:33:23.799Z","etag":null,"topics":["adaptive-learning","ai-agent","claude","evolution","hermes-agent","ocas","openclaw","self-improvement","session-mining"],"latest_commit_sha":null,"homepage":"https://github.com/indigokarasu/ocas-finch","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indigokarasu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-05-16T00:32:24.000Z","updated_at":"2026-05-23T04:23:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/indigokarasu/finch","commit_stats":null,"previous_names":["indigokarasu/ocas-finch","indigokarasu/finch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/indigokarasu/finch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigokarasu%2Ffinch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigokarasu%2Ffinch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigokarasu%2Ffinch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigokarasu%2Ffinch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indigokarasu","download_url":"https://codeload.github.com/indigokarasu/finch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigokarasu%2Ffinch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["adaptive-learning","ai-agent","claude","evolution","hermes-agent","ocas","openclaw","self-improvement","session-mining"],"created_at":"2026-06-02T17:31:22.413Z","updated_at":"2026-06-02T17:31:23.230Z","avatar_url":"https://github.com/indigokarasu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ocas-finch\n\n**OCAS Self-Improvement Orchestrator** — Darwin's finch: adaptive evolution for AI agents.\n\nFinch mines session JSONL files to detect learning signals from real user interactions — corrections, breakthroughs, methodologies, course-changes, and behavioral directives (Always/Never). Each finding is routed to the modification target that will have the most behavioral impact: MEMORY.md or skill patches.\n\nPart of the [OCAS](https://github.com/indigokarasu/ocas-architecture) (OpenClaw Agent System) ecosystem.\n\n## What it does\n\n1. **Mines** session JSONL files for learning signals using regex pattern matching\n2. **Compacts** MEMORY.md to stay within the 2,200 char limit (dedup, re-rank, evict, compress)\n3. **Routes** each finding to the optimal target (MEMORY.md for behavioral rules, skill patches for methodologies)\n4. **Emits** OCAS Action Journals and DecisionRecords per the OCAS spec\n5. **Applies** changes with user review (weekly) or auto-applies low-risk findings (daily)\n\n## Signal types\n\n| Signal | What it means | Where it goes |\n|--------|--------------|---------------|\n| **Correction** | User said \"no/wrong/don't/stop\" | MEMORY.md |\n| **Directive (Always)** | User said \"always do X\" | MEMORY.md — Always Rules |\n| **Directive (Never)** | User said \"never do X\" | MEMORY.md — Never Rules |\n| **Course change** | User reinterpreted and redirected | MEMORY.md |\n| **Breakthrough** | User confirmed something works | MEMORY.md — What Works |\n| **Methodology** | User described a reproducible process | Skill patch or MEMORY.md |\n| **Stop** | User stopped/cancelled a task | MEMORY.md — Stop Signals |\n\n## Architecture\n\n```\n~/.hermes/\n  skills/ocas-finch/\n    SKILL.md                    # Skill definition (this package)\n    scripts/\n      miner.py                  # Session mining engine\n      router.py                 # Recommendation router\n      compact.py                # MEMORY.md compaction engine\n    references/\n      signal_patterns.md        # Complete regex pattern reference\n      mining_methodology.md     # Mining methodology and lessons learned\n  commons/\n    data/ocas-finch/\n      decisions.jsonl           # DecisionRecord log (append-only)\n      memory_archive.md         # Evicted MEMORY.md entries\n    journals/ocas-finch/\n      YYYY-MM-DD/\n        {run_id}.json           # Action Journal entries\n```\n\n## OCAS compliance\n\n- **Storage**: Per `spec-ocas-storage-conventions.md` — all data under `commons/`\n- **Journals**: Action Journal entries per `spec-ocas-journal.md`\n- **DecisionRecords**: Per `spec-ocas-shared-schemas.md`\n- **Naming**: `ocas-` prefix per OCAS naming convention\n- **Workflow plans**: `finch-daily.plan.md` and `finch-weekly.plan.md` per `spec-ocas-workflow-plans.md`\n\n## Usage\n\n### Mine sessions\n```bash\npython3 ~/.hermes/skills/ocas-finch/scripts/miner.py --days 7 --json --min-confidence 0.7\n```\n\n### Compact MEMORY.md\n```bash\npython3 ~/.hermes/skills/ocas-finch/scripts/compact.py --apply\n```\n\n### Route findings\n```bash\npython3 ~/.hermes/skills/ocas-finch/scripts/router.py --input /tmp/finch_mined.json --dry-run\n```\n\n### Full pipeline (daily)\n```bash\npython3 ~/.hermes/skills/ocas-finch/scripts/miner.py --days 1 --json --min-confidence 0.7 \u003e /tmp/finch_mined.json\npython3 ~/.hermes/skills/ocas-finch/scripts/compact.py --apply\npython3 ~/.hermes/skills/ocas-finch/scripts/router.py --input /tmp/finch_mined.json\n```\n\n## Scheduled tasks\n\n| Job | Frequency | Behavior |\n|-----|-----------|----------|\n| **ocas-finch:daily** | Daily 6am PT | Mine 24h → Compact → Route → Auto-apply low-risk. Flag directives. |\n| **ocas-finch:weekly** | Sunday 8am PT | Mine 7d → Compact → Route → Show full plan for approval. |\n\n## Integration with Hermes Agent\n\nThis skill is designed for [Hermes Agent](https://github.com/indigokarasu/hermes-agent) and uses:\n- `memory` tool for MEMORY.md modifications\n- `skill_manage` tool for skill patches\n- `cronjob` tool for scheduled runs\n- Session JSONL files from `~/.hermes/sessions/`\n\n## Related\n\n- [OCAS Architecture Spec](https://github.com/indigokarasu/ocas-architecture) — System architecture, schemas, and design documents\n- [Mentor](https://github.com/indigokarasu/mentor) — Self-improving orchestration and evaluation engine\n- [Forge](https://github.com/indigokarasu/forge) — Skill architect and builder\n- [Fellow](https://github.com/indigokarasu/fellow) — Empirical experimentation engine\n- [Corvus](https://github.com/indigokarasu/corvus) — Exploratory pattern analysis engine\n\n## License\n\nPart of the OCAS ecosystem. See [indigo](https://github.com/indigokarasu/indigo) for licensing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigokarasu%2Ffinch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findigokarasu%2Ffinch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigokarasu%2Ffinch/lists"}