feat(ai-echo): AI echo system — pgvector retrieval, personas, memories, generic engine

[Innei]

Summary

Adds a generic AI echo engine and three supporting modules, anchored on the recently (wishing-well / 树洞) module: every new recently entry receives AI-written replies voiced by configurable personas. The engine is scenario-pluggable so future scenarios (comment auto-reply, reader companion) plug in without touching the engine.

Four new modules under apps/core/src/modules/ai/:

• ai-embeddings — pgvector corpus over post / note / page; chunker (paragraph-aware, deterministic, hash-diffed); EMBED_SYNC task + event listeners; admin backfill + stats; retrieval API returns similarity = 1 - cosine_distance.
• ai-persona — PERSONA_REGISTRY const with inner-self (dynamic, distilled) + passerby (static); persona_profiles table; single-pass LLM distillation with Redis lock; length-window + recency-weighted exemplar selection.
• ai-memory — human-authored canonical-facts CRUD; recall supports salience-only (no query) and vector-ranked (with query, re-ranked by similarity × salience × confidence); KPI.
• ai-echo — generic EchoScenario abstraction + ai_echoes table; ECHO_GENERATE task with status-guarded idempotent replay; daily quota; admin regenerate/edit/delete/list + public list. Ships one scenario: recently (triggers on RECENTLY_CREATE, cascades on RECENTLY_DELETE).

Shared foundation:

• pgvector extension + vector custom Drizzle column type
• 4 new tables, all migrated in 0015_ai_echo_system.sql (additive only; expand-contract safe)
• AIFeatureKey.Echo / Embedding / PersonaDistill + matching AISchema config slots + AiService resolvers
• 5 AITaskType entries with dedup keys
• 18 new AppErrorCode entries with payload + definition mappings
• 2 new BusinessEvents (RECENTLY_ECHO_LANDED, PERSONA_PROFILE_REFRESHED)

Specs

• Root: docs/superpowers/specs/2026-05-23-ai-echo-system-root.md
• Engine: docs/superpowers/specs/2026-05-23-ai-echo-engine-design.md
• Embeddings: docs/superpowers/specs/2026-05-23-ai-embeddings-design.md
• Persona: docs/superpowers/specs/2026-05-23-ai-persona-design.md
• Memory: docs/superpowers/specs/2026-05-23-ai-memory-design.md

Implementation deviations (all reality adaptations)

• EchoScenarioRegistry service replaces the spec's ECHO_SCENARIO multi-provider injection token — NestJS doesn't natively support multi: true (Angular concept); consumer modules self-register via OnModuleInit. Functionally equivalent.
• AiService is locally provided in AiPersonaModule / AiMemoryModule to avoid circular import; stateless (only resolves config). Worth consolidating later.
• The initial corpus backfill app-migration is a log-only marker — the slim migration runner has no Nest DI, so the admin runs POST /ai-embeddings/backfill after configuring an embedding model. Spec §12 already allows this fallback.
• Test pg image switched to pgvector/pgvector:pg17 (one-line tag swap in pg-testcontainer.ts).

Test plan

• pnpm exec eslint --fix — clean across all modified files
• pnpm -C apps/core run lint:migrations — ok (16 files scanned)
• npx vitest run --no-file-parallelism test/src/modules/ai/{ai-embeddings,ai-persona,ai-memory,ai-echo} — 110/110 passing (15 spec files)
• Acceptance criteria from root spec §7 verified by integration tests:
  • Recently create → 2 echoes reach status='ready'; RECENTLY_ECHO_LANDED fires twice
  • Public GET /ai-echo/by-subject/recently/:id filters to ready + edited
  • Admin edit/delete/regenerate (force=true archives old)
  • Persona refresh: single-pass distill writes row; concurrent → 409
  • Embedding sync produces correct rows; unchanged source → no-op (hash diff)
  • Memory recall integrates into echo prompts; reflected in ai_echoes.metadata.memoryIds
  • Embedding model unconfigured → sync/retrieval graceful no-op; echoes still generate (without retrieval section)

Known infra debt (pre-existing, not introduced here)

Full-suite test runs have occasional flakes due to dbHelper.clear() (in test/helper/db-mock.helper.ts) issuing blanket TRUNCATE across parallel vitest worker processes that share the same pg-testcontainer. The new specs pass deterministically when run in isolation. A future cleanup should either scope dbHelper.clear() to per-spec tables or set poolOptions.forks.singleFork: true.

Follow-ups (deferred to v2 per spec)

• Echo: rating endpoint, comment-reply + reader-companion scenarios, streaming via ai-inflight
• Embeddings: recently embedding, reindex endpoint, HNSW/IVFFLAT migration when row count crosses threshold
• Persona: map-reduce distill, auto-refresh (cron + threshold), vector-by-query exemplar selection
• Memory: /from-passage LLM draft, MEMORY_EXTRACT + forced review, MEMORY_DECAY, supersede detection, KPI nudge widget

[safedep]

SafeDep Report Summary

No dependency changes detected. Nothing to scan.

View complete scan results →

_{This report is generated by SafeDep Github App}