Skip to content

AgentCache 0.2.0

Choose a tag to compare

View all tags
@cdibona cdibona released this 26 Jun 18:54
· 36 commits to main since this release
v0.2.0
94c689b

🎯 Major Features

✅ Delta Symbol Indexing

Per-commit optimization for symbol cache generation. On pushes with changed files:

  • Re-ctag only changed files instead of re-scanning the whole tree
  • Carry forward unchanged symbols from the parent commit's cache
  • Safe fallback to full rebuild (no parent cache / version/schema mismatch / ctags missing / root commit / merge unless enabled / changed-file ratio over AGENTCACHE_DELTA_MAX_RATIO limit)
  • Canonicalization guarantee: delta output is byte-identical to full rebuild (preserves exp2 PRISTINE guarantee)

Load demo (exp3):

first_push    mode=full   reindexed=1  carried=0  bytes=32   parent=None
second_push   mode=delta  reindexed=1  carried=1  bytes=37   parent=3d97fc4c

See experiments/results/exp3_hook_update.json for live delta proof.

📊 Load Observability

meta.json and generate_for_commit() now emit a generation block with:

  • mode — full or delta
  • parent — parent commit SHA (if delta)
  • files_in_tree, files_changed, files_reindexed, files_carried_forward
  • content_bytes_materialized, symbol_count
  • ctags_available, fallback_reason

Enables per-human-action telemetry and debugging.

🔧 Configuration

New knobs (all optional, backward-compatible defaults):

  • AGENTCACHE_DELTA_SYMBOLS — enable/disable delta path (default: true if ctags present)
  • AGENTCACHE_DELTA_ON_MERGE — delta across merges (default: false, safest)
  • AGENTCACHE_DELTA_MAX_RATIO — fallback to full if changed_files / total_files exceeds ratio (default: 0.3)
  • AGENTCACHE_WEB_HOST — test harness bind host (default: 127.0.0.1, now supports tailnet IPs)

Schema versions:

  • GENERATOR_VERSION → 0.2.0
  • SYMBOLS_SCHEMA → 2

🛠️ Tooling & Operations

System Prerequisites

  • universal-ctags now required for symbol indexing (previously optional). Install via sudo apt-get install universal-ctags.
    • CI workflow now installs it automatically.
    • Detection: symbols.ctags_available() flips to true; delta path activates.

Test Harness

  • Tailnet serving: bind test harness to tailnet IP for remote access over Tailscale.
    • AGENTCACHE_WEB_HOST=100.107.70.97 (or any tailnet IP)
    • Combine with tailscale serve for HTTPS access.
  • Systemd --user integration: harness can run as a managed systemd --user service (auto-restart, reboot-survivable).
  • Startup log fix: log line now reflects the real bind host instead of hardcoded 127.0.0.1:8080.

CI Workflow

  • Renamed to "AgentCache generate" (was: "Generate AgentCache").
  • Installs universal-ctags before running tests.

🐛 Compatibility Fix

Python < 3.11.4 / 3.12 compatibility: tarfile.extractall(filter=) kwarg is unavailable on Python 3.11.0–3.11.3 (added in 3.12, backported to 3.11.4+). Guarded with version check; falls back to plain extractall() on older interpreters (safe: git-archive members are trusted relative tree paths).

  • Impact: previously masked because ctags was absent locally (symbol tests skipped) and CI Python had the backport.
  • Fixed: symbol indexing now works on Python 3.11.2 with ctags present.
  • Tests: all 49 tests pass (13 previously skipped delta tests now run + pass).

📖 Documentation Updates

  • README.md: Delta symbol indexing overview, config knobs, ctags prerequisite.
  • AGENTS.md: Load block structure, generation telemetry.
  • .env.example: New env vars with descriptions.
  • docs/ADOPTER_AGENTS_TEMPLATE.md: Notes on delta mode and load interpretation.
  • experiments/README.md: exp3 now demonstrates delta (second push shows carried-forward symbols).

Contributors

Generated with Amplifier

Assets 2
Loading