feat(memory): PR-E5a · agent_episodic_events table + endpoint (Sprint v1.8)

[hizrianraz]

Summary

First Sprint v1.8 execution PR. Per ainfera-os/docs/PHASE-5-VARDA-MEMORY-PLAN.md §3.1 (Supabase episodic store) + Aule rec A2 locked 2026-05-17: api endpoint (Path B), not direct Supabase write — keeps Varda's auth model clean + opens the surface for all 5 fleet agents.

Phase 5 plan canon on ainfera-os main: 567236a (Plan PR #14 merged earlier today).

Table

agent_episodic_events — append-only per-agent event log:

id                       UUID (gen_random_uuid)
agent_id                 UUID FK CASCADE
created_at               TIMESTAMPTZ DEFAULT now()
event_type               VARCHAR(64)
sender                   VARCHAR(128) nullable
recipient                VARCHAR(128) nullable
body                     JSONB DEFAULT '{}'
inference_receipt_id     VARCHAR(64) nullable  (soft-link to receipts)
audit_event_hash         VARCHAR(64) nullable  (soft-link to audit chain)

Two compound indexes for the dominant query shapes:

• (agent_id, created_at DESC) → last-N-events-for-agent
• (agent_id, event_type, created_at DESC) → filter-by-type

Endpoints

POST /v1/agents/{agent_id}/memory/episodic
GET  /v1/agents/{agent_id}/memory/episodic
       ?event_type=<str>
       &since=<ISO8601>
       &limit=<1..500>  (default 100)

Auth: tenant must own agent_id (uses existing require_owned_agent dep). Same pattern as /v1/heartbeat for shape.

Files (8 · ≤10 per [LOCK 6.3])

• alembic/versions/20260517_0009_agent_episodic_events.py (new) — migration
• ainfera_api/orm.py — appended AgentEpisodicEventORM after LedgerEntryORM
• ainfera_api/models/agent_memory.py (new) — Pydantic schemas
• ainfera_api/routers/agent_memory.py (new) — POST + GET endpoints; uses modern Annotated[..., Query()] pattern (ruff B008 clean)
• ainfera_api/main.py — register agent_memory.router
• tests/integration/test_agent_memory.py (new) — 7 integration tests (no-auth → 4xx, cross-tenant, persistence roundtrip, ordering, event_type filter, limit clamping, cross-agent isolation)
• tests/integration/conftest.py — add agent_episodic_events to _RESET_TABLES (CASCADE handles via FK too; explicit is safer)
• tests/smoke/test_openapi_contract.py — add 2 new endpoints to EXPECTED_OPERATIONS (pre-commit contract test caught the drift on first attempt — working as intended)

Pre-commit gates green

• ✅ ruff — clean (after B008 fix: Query() in arg defaults → Annotated[..., Query()] pattern)
• ✅ ruff format
• ✅ mypy --strict
• ✅ pytest -x (unit + smoke · 394 passed + the new openapi contract test)

Cross-store invariants held (per plan §2)

• ✅ A2A envelope schema unchanged (cross-repo · no ainfera-os edits in this PR)
• ✅ Caps stay at api layer per [LOCK 2.4]
• ✅ Letta NOT used ([LOCK 2.2] + §9 Letta-scoped-to-Namo-only)
• ✅ No A2A primitives leak into episodic schema per [LOCK 2.3]

What this PR does NOT do (next in §4 sequence)

• PR-E5b in ainfera-os/ wires Varda's runner.py to call this endpoint after each think() + send(). Cross-repo coupling — opens once PR-E5a merges + alembic migration applied.
• PR-N5 (Notion semantic store) follows PR-E5b
• PR-O5 (Obsidian procedural · Path Z) follows PR-N5
• PR-S5 (substrate.openclaw memory deprecation per A4 lock) is the final Sprint v1.8 PR (AIN-122 fold-in)

Test plan

• AST parses cleanly for all 8 files
• Pre-commit gates green (ruff + ruff format + mypy --strict + pytest -x)
• OpenAPI contract test updated for new endpoints
• Founder-side migration apply (per [LOCK 6.4]) — alembic upgrade head against Supabase prod via Railway-injected DATABASE_URL. Required before PR-E5b can land.
• CI: full pytest with RUN_INTEGRATION=1 against migrated DB

Related

• AIN-122 — Varda sandbox-id non-determinism (Phase 5 fold-in to PR-S5)
• ainfera-os PHASE-5-VARDA-MEMORY-PLAN.md §3.1 + §12 A2 — this PR implements both
• v0.4.0-phase-4-frameworks tag in ainfera-os (the milestone Sprint v1.8 builds atop)

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces a new persisted data store (migration + ORM) and new authenticated API surface for writing/reading arbitrary JSON payloads, which could impact production data growth and access control if misconfigured.

Overview
Adds an append-only per-agent episodic memory log: new agent_episodic_events table (with indexes), SQLAlchemy model, and Pydantic schemas.

Exposes new authenticated endpoints POST/GET /v1/agents/{agent_id}/memory/episodic (filters: event_type, since, limit) and registers the router in main.py; updates integration fixtures/tests and the OpenAPI contract snapshot to cover the new API surface.

^{Reviewed by Cursor Bugbot for commit fbc048e. Bugbot is set up for automated code reviews on this repo. Configure here.}