aictx 3.0.0

Repo-local execution memory for coding agents

aictx

Coding agents forget how they worked.

aictx makes their past executions reusable.

It records real execution, stores useful patterns, and reuses successful strategies in later executions inside the same repository.

---

Why this exists

Most agent workflows start from scratch every time.

aictx allows them to reuse what already worked.

---

What aictx is

A repo-local execution memory layer for coding agents that records real execution and reuses successful strategies.

• repo-local execution memory
• real execution logging
• reusable strategy memory
• structured execution signal capture with provenance
• failure and repo-area memory
• lightweight runtime guidance and post-task summaries for coding agents

---

Safety model

AICTX modifies repository files and can optionally install runner integrations. By default it creates repo-local runtime artifacts only during repo setup, and aictx install does not modify global Codex files. Global Codex integration requires aictx install --install-codex-global.

---

Quick start

pip install aictx
aictx install
cd your-repo
aictx init

After aictx init, you can use your coding agent normally in that repo.

Manual aictx commands after initialization are optional:

• the intended flow is install + init, then agent-driven usage
• suggest, reflect, reuse, and report real-usage remain available for inspection, debugging, or manual control
• Claude/Codex integration files and hooks added by init are there to help the agent use aictx automatically when the runner respects repo instructions

---

Public CLI

aictx install
aictx init
aictx suggest
aictx reflect
aictx reuse
aictx report real-usage
aictx clean
aictx uninstall

Only install and init are part of the normal setup path.

The rest of the public commands are optional operational commands:

• suggest, reflect, reuse -> for manual inspection or explicit agent calls
• report real-usage -> for reviewing stored execution data
• clean, uninstall -> for removing AICTX-managed content

---

What aictx does

• records real execution in .aictx/metrics/execution_logs.jsonl
• writes operational feedback in .aictx/metrics/execution_feedback.jsonl
• stores successful and failed strategies in .aictx/strategy_memory/strategies.jsonl
• captures available files, commands, tests, and errors with provenance instead of inventing data
• stores repo-local failure patterns and area memory for later debugging/context
• reuses only successful strategies during later executions
• returns agent_summary and agent_summary_text after finalize; agents must append agent_summary_text to final user responses for non-trivial tasks
• exposes small JSON commands for runtime guidance
• does not scaffold knowledge mods or cross-repo/global metrics in v3

---

What AICTX modifies

Repo-local:

• .aictx/
• AICTX-managed blocks in AGENTS.md and CLAUDE.md
• .claude/settings.json merged AICTX hook entries
• .claude/hooks/aictx_*.py
• .gitignore entries for AICTX runtime paths

Optional global:

• ~/.codex/AGENTS.override.md
• ~/.codex/config.toml

Global Codex files are only updated when --install-codex-global is passed.

---

Idempotency guarantees

• aictx init is non-destructive for existing AICTX execution logs and strategy memory
• existing .aictx/metrics/*.jsonl and .aictx/strategy_memory/*.jsonl files are preserved
• .claude/settings.json is merged, not overwritten
• AICTX-managed Markdown blocks and hooks are idempotent
• aictx init does not delete legacy non-AICTX paths

---

What aictx does NOT do

aictx does not optimize your agent. aictx does not guarantee better performance.

It makes past executions observable and reusable.

---

Who this is for

• engineers using coding agents repeatedly in the same repository
• teams that want repo-local execution history and reusable strategies
• users who prefer traceable artifacts over heuristic-heavy automation

Who this is not for

• users expecting guaranteed productivity gains
• teams looking for a full orchestration platform
• workflows that do not preserve repo-level instructions or execution discipline

---

Runtime loop

1. prepare_execution() loads prior successful strategies and may attach execution_hint
2. the agent executes
3. finalize_execution() records logs, feedback, strategy memory, and agent_summary_text
4. the agent appends agent_summary_text to the final user response; if unavailable, it says AICTX summary unavailable
5. the next execution can reuse successful strategies and ignore failed ones

---

Main runtime artifacts

.aictx/
  metrics/
    execution_logs.jsonl
    execution_feedback.jsonl
  strategy_memory/
    strategies.jsonl

---

Additional properties

• repo-local artifacts are the source of truth; execution history and strategy memory stay inspectable inside the repository
• failed strategies are stored, but they are excluded from reuse by default
• public operational command outputs are deterministic and machine-readable JSON; internal run-execution without --json also prints the user-facing AICTX summary
• AICTX-managed changes can be removed cleanly with aictx clean and aictx uninstall

---

Notes

• file tracking depends on explicit input from the agent/runtime; wrapped execution can capture commands, tests, errors, and edited files best-effort
• strategy reuse is heuristic: matching task type, prompt similarity, overlapping files, primary entry point, commands/tests/errors, and area are preferred, with recency as a secondary signal
• task typing uses explicit metadata first, then deterministic keyword/path inference, then unknown
• capture provenance distinguishes explicit, runtime-observed, heuristic, and unknown signals
• middleware packet generation is not active in the default runtime path
• failed strategies are stored but never reused as hints
• no synthetic benchmarks or estimated improvements are reported

---

Cleanup

• aictx clean removes only AICTX-managed content from the current repository: the .aictx/ scaffold, AICTX blocks in AGENTS.md / CLAUDE.md, legacy AICTX content in AGENTS.override.md when present, AICTX Claude hooks/settings, and the .gitignore entry added by AICTX
• aictx uninstall removes AICTX-managed content from all registered repositories and removes global AICTX state under ~/.aictx, plus AICTX-managed Codex global instructions/config lines
• both commands are conservative: they only remove content that AICTX created or marked as AICTX-managed

---

Possible evolution

The current v1 keeps strategy memory intentionally simple.

Possible future work, based on real usage:

• better file access capture from agent/runtime integrations
• broader runner-native signal capture where supported
• clearer comparison across repeated task categories
• stronger runner-native automation where supported
• richer repo-level reporting built only from real execution history

Not part of the current product contract:

• synthetic benchmarks
• heuristic scores
• guaranteed optimization claims

---

Read next

• Usage
• Demo
• Limitations
• Safety
• Upgrade
• Execution summary
• Failure memory
• Area memory