Aeon Docs: Skills, Memory & Self-Healing Guide

UH00X/Y 3CXR9P How aeon works - a complete map of the framework. Every moving part, every loop, every schedule.

A complete map of the framework - every moving part, every loop, every schedule.

Last updated 26 AUG

This page may not always be current. aeon ships fast - check the live README, open PRs, and recent commits.

Three surfaces

The local dashboard (./aeon, port 5555) configures skills. The repo holds skills, identity, memory, and YAML. Actions runners execute on cron and write results back.

Four files an operator touches

aeon.yml - enabled flags, cron schedules, var inputs, model overrides, chain definitions.
CLAUDE.md - agent identity, auto-loaded every run, references memory/MEMORY.md and soul/.
catalog/skills.json - catalog of all 81 skills, regenerated from each SKILL.md by bin/generate-skills-json.
.github/workflows/scheduler.yml - ticks every 5 min, dispatches due skills.

The control plane

apps/dashboard/ shells out to gh for every /api/* call - secrets, workflows, config. Loopback-gated by default; AEON_DASHBOARD_ALLOWED_HOSTS opens it for Tailscale, with same-origin checks against no-cors POST.

The repo, walkable

CLAUDE.md agent identity
STRATEGY.md north-star
brief aeon.yml schedules, chains, triggers
./aeon dashboard + CLI launcher
./notify multi-channel notify

Catalog

Core

Basics

Anatomy of a skill

---
name: digest
description: Generate and send a digest on a configurable topic, optionally pulling RSS/Atom feeds as an input source alongside web + X signal
metadata:
  title: Digest
  mode: write
  category: basics
  var: ""
  tags: [content, news]
  requires: [XAI_API_KEY?]
---

# Digest

You are running as the digest skill. Your job is to produce a crisp ≤300-word digest from recent signals: top items on the topic, why they matter, and what changed since the last run.

## Inputs
- memory/MEMORY.md      → current goals
- memory/topics/*.md    → tracked topics
- output/.chains/*.md   → upstream chain outputs (if any)

## Output
- A single ./notify call with the brief
- An entry appended to memory/logs/$(date +%F).md

The universal `var` field

Every skill accepts one input through var, interpreted per skill: topic for research (var: "rust"), repo for dev (var: "owner/repo"), token for crypto (var: "solana"), focus area for productivity. Empty falls back to defaults.

Config shape

model: claude-sonnet-5

skills:
  article:
    enabled: true               # flip to activate
    schedule: "0 8 * * *"       # daily at 8am UTC
  digest:
    enabled: true
    schedule: "0 14 * * *"
    var: "solana"               # topic for this skill
  token-movers:
    enabled: true
    schedule: "30 12 * * *"
    model: "claude-opus-4-8"    # per-skill model override

Four skills

heartbeat - the sentinel

Runs daily, the only skill enabled by default.

Issue lifecycle

Issues live in memory/issues/ISS-NNN.md with frontmatter (status, severity, root_cause, fix_pr). Health skills file, open → resolved;

PR governance

pr-review --survey buckets open PRs by risk tier (core-review / infra-review / skill-pass / fast-track), re-notifying only on a riskier new PR.

Five layers

Layer	Purpose	Lifetime
`memory/MEMORY.md`	Index - goals, topics, pointers	Long-lived, hand-curated
`memory/topics/`	Detailed notes by topic	Long-lived
`memory/logs/YYYY-MM-DD.md`	Append-only daily log	Forever
`memory/issues/`	Structured failure tracker	Until `resolved`
`memory/skill-health/`	Rolling quality scores per skill	Rolling window

Operating rules

Read MEMORY.md on entry for goals and active topics.
Append a log on exit to memory/logs/$(date +%F).md.

Scheduler rules

Every match fires, in parallel, every 5 minutes by default.
Dependencies run first via a skill's depends_on: frontmatter.

Defining a chain

chains:
  digest-pipeline:
    schedule: "0 7 * * *"
    on_error: fail-fast                       # or: continue
    steps:
      - parallel: [token-movers, github-trending]   # run concurrently
      - skill: digest, consume: [token-movers, github-trending]   # runs after; outputs injected

Capabilities taxonomy

Capability	Meaning
`read_only`	No writes, onchain calls, or notifications.
`external_api`	Any authenticated call to a non-aeon HTTP API.
`writes_external_host`	POST/PUT/DELETE/PATCH to an external host.
`onchain_writes`	Signs and broadcasts transactions.
`agent_messaging`	Speaks publicly for the operator on social/chat platforms.
`sends_notifications`	Calls `./notify` - the operator's own channel only.

Channels

Channel	Outbound	Inbound (talk back)
Telegram	`TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID`	Same (offset-based polling)
Discord	`DISCORD_WEBHOOK_URL`	`DISCORD_BOT_TOKEN` + `DISCORD_CHANNEL_ID`
Slack	`SLACK_WEBHOOK_URL`	`SLACK_BOT_TOKEN` + `SLACK_CHANNEL_ID`
Email	`RESEND_API_KEY` + `NOTIFY_EMAIL_TO`	-

More harnesses

Seven more run through harness-adapter's run-harness, wrapped in the same {result, usage, session_id} contract:

Codex - OpenAI Codex CLI (openai/*)

FORKIT. RUNIT. FORGETIT.

RUN AEON733