Make your agent learn. Reflects. Experiments. Improves. Across every session.
Every sub-agent you spawn finishes its work and disappears. Whatever it figured out - which command failed three times before the right one, which file actually mattered, which approach to skip - dies with it. The next sub-agent rediscovers it from scratch. Your own next session does too.
ax is the loop that closes before the session ends. A Stop hook fires
at session-end (main or sub-agent), asks the agent for a structured retro
(tried · worked · failed · next), and indexes the result as a typed
experiment in a local graph. Friction patterns become proposals you
triage. Accepted proposals become experiments with t+7 / t+30 / t+90
verdicts. The next session reads what worked.
What did this sub-agent learn? Which experiments are still open? Which skills earned their keep? Which hooks blocked anything useful?
axanswers these by reading what already happened.
AX (agent experience) is what the agent perceives across sessions,
reflects on at the end of each, and turns into the next experiment. It
is to AI coding agents what retros and post-mortems are to engineering
teams - a structured reflection step that compounds.
ax (lowercase) is the reference implementation. Local typed graph,
Stop-hook-driven retros, agent-readable queries, React dashboard, MIT.
A longer take: docs/manifesto.md. Vocabulary:
docs/language.md.
flowchart LR
cc["~/.claude/projects/<br/>Claude transcripts"]
cx["~/.codex/sessions/<br/>Codex transcripts"]
sk["~/.claude/skills/<br/>installed skills"]
g[("local git history")]
cc --> ingest
cx --> ingest
sk --> ingest
g --> ingest
ingest["axctl ingest<br/>(Effect pipelines)"] --> db
db[("the ax graph<br/>session · turn · tool_call · skill<br/>repository · checkout · commit · file<br/>friction · diagnostic · insight")]
db --> cli["axctl CLI<br/>recall · skills · insights · evidence"]
db --> dash["axctl serve<br/>live dashboard"]
db --> agent["agent skill<br/>project context · verify · harness"]
Everything runs on 127.0.0.1. The agent and the CLI both read the same
graph; the dashboard is a thin React view over the same queries.
Which skills earned their keep, by composite score over the last 30 days:
$ axctl skills taste --limit=8
skill scope score 7d 30d total
codex:exec_command codex-tool 40902.5 1,124 30,500 40,389
codex:write_stdin codex-tool 6,957 166 4,932 6,451
codex:rescue command 781 0 389 605
codex:update_plan codex-tool 766.5 14 338 391
simplify user 718.5 5 89 101
codex:wait_agent codex-tool 713 3 497 507
codex:spawn_agent codex-tool 647 2 439 442
superpowers:systematic-debugging plugin 26.5 0 6 6
(8 / 288 skills shown)
Recall past work across every session, in milliseconds:
$ axctl recall "auth middleware"
4 matches
2026-05-23T15:19 codex user acme-app alright lets commit auth related work for now
2026-05-23T14:51 codex assistant acme-app Added the HealthOS just setup. You can now run from repo root: just health dev …
2026-05-23T14:41 codex assistant acme-app Findings: apple-auth.service.ts accepts extra Apple audiences from ambient env …
2026-05-19T11:08 claude user ax the auth middleware retry loop - we still see exit-code 1 from bun check after …
Which tools fail most often, so you know what to skill-up around:
$ axctl insights tools --limit=5
name failure_count exit_code last_seen
write_stdin 647 1 2026-05-23T14:34
Edit 483 - 2026-05-23T05:14
Skill 475 - 2026-05-05T13:34
exec_command 421 1 2026-05-22T18:50
Bash 318 1 2026-05-21T22:12
LLM agents are good at tasks. They're bad at remembering what happened. Memory tooling today is either a giant rolling context window (expensive, slow, lossy) or vague vector retrieval (no structure, no grounding in real events).
ax takes a different shape: a typed graph of evidence built from the
agent's own logs. Sessions, turns, tool calls, plans, skills, commits, files,
friction, and derived signals - all queryable, all local, no
network round-trip, no third party.
Three things fall out of that, and they're the three things "agent experience" actually means in practice:
- Skill triage - which of your installed skills get used, which never fire, which correlate with stuck sessions.
- Pre-flight grounding -
axctl project contexthands the next agent stack info, recent friction, and verification commands. - Retro signal - query the graph after a hard session: tool retries, plan churn, file edit pairings. Feed it back into the next run.
curl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh | bash
PATH="$HOME/.local/bin:$PATH" axctl ingest --since=7Skills are distributed via the skills.sh marketplace. After the CLI is installed, drop the agent skills into your Claude Code session with:
npx skills add Necmttn/ax # installs ax:setup + ax:retro skillsRequires Bun ≥ 1.3 and SurrealDB ≥ 3.0. macOS-first; Linux works for ingest and CLI (no launchd reactivity).
For dev install, schema, queries, and benchmarks, see
docs/development.md.
axctl ingest --since=7 # backfill last 7 days of transcripts + skills + git
axctl serve # live dashboard at http://127.0.0.1:8520
axctl skills taste # CLI view: which skills earned their keep
axctl recall "auth bug" # full-text recall across past sessionsax ships two installable skills so a Claude Code / Codex agent can query
its own evidence graph mid-session:
npx skills add git@github.com:Necmttn/ax.git --skill axctl -g -a claude-code -a codex -y
npx skills add git@github.com:Necmttn/ax.git --skill retro -g -a claude-code -a codex -yRecommended agent loop:
axctl project context --jsonbefore work - stack, recent friction, verification commands.- Do the work.
axctl project verify --jsonbefore reporting done - runs the checks the project actually expects.
axctl ingest [--since=N] [--reset]
axctl serve | report # live dashboard / static HTML
axctl recall <query> # full-text search across turns
axctl skills <search|taste|unused|pairs|recovery>
axctl insights <view> # 16 read-only graph views
axctl project <context|verify|harness>
axctl evidence <guidance-next|session-summary|weekly>
axctl daemon <status|start|stop|restart>
axctl doctor | install | uninstall | update | version
Full reference: docs/insights-cli-reference.md.
docs/manifesto.md- the missing layer in the agent stackdocs/language.md- coined vocabulary, the AX glossarydocs/brand.md- design system + voice rulesdocs/development.md- local setup, schema, queries, benchmarksCONTRIBUTING.md- PR conventions, ground rulesCONTEXT.md- domain glossary (Repository vs. Checkout vs. …)docs/adr/- architecture decisions
MIT © 2025 Necmettin Karakaya