feat(memory): LLM-maintained fact files — cap errors, stats, eviction policy (M1-M4)

[jkyberneees]

What

Makes fact-file memory self-maintaining by the agent: when a file fills, the agent evicts older entries itself — judgment stays in the ReAct loop, and every eviction is an explicit, auditable memory remove/replace call.

• M1 — decision-ready cap errors (facts.go): cap failures in Add/Replace/ReplaceAt carry the full entry index ([n] size "rune-safe preview") + explicit memory remove/replace guidance, so the agent evicts without an extra read round-trip.
• M2 — stats action (tool.go): memory(action:"stats", target:"env") → {used, cap, entries:[{index, chars, preview}]} as a pre-flight fill check. view stays episodes-only (provenance gate).
• M3 — eviction policy (tool.go): the tool description codifies the contract — git/GitHub-recoverable records evict first, pointers to untracked local work evict last.
• M4 — near-cap hint (memory.go): the system-prompt memory block appends a one-line ⚠ env fact file NN% full — evict stale entries via memory remove only at ≥90% fill.
• Docs: new "Automatic Cap Maintenance" section in docs/MEMORY.md.

Deliberately not built

• No auto-consolidation on write — mid-flow LLM rewrites risk dropping load-bearing details and amplify provider throttling.
• No date-based auto-eviction — age ≠ value; a days-old pointer to untracked work can be the only durable record of it.

Tests

RED-first: 9 tests in internal/memory/auto_eviction_test.go (cap-error index incl. the 4-byte § separator byte accounting, stats guards, rune-safe previews, hint threshold pinning). Verified: go test -race -count=1 ./internal/memory/... green, go build ./... clean, filtered cmd/odek Memory tests green, gofmt/vet clean.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	2963323	Commit Preview URL Branch Preview URL	Aug 30 2026, 07:32 PM