Implementation

Build-промпт для AI-кодинг-агента: реалізувати зберігання чатів, debug/trace-площину та chat-memory-індекс — три сховища за їхніми слайсами. Спершу прочитай Огляд, Storage, Debug & tracing і Memory.

Ця сторінка — agent-промпт

Кожен розділ має сторінку Implementation — точну, copy-paste task-специфікацію, яку виконує агент.

Промпт

ROLE: You are implementing the Chats subsystem of Agentfy.ai 2.0 (NestJS + Prisma + CleanSlice).

GOAL: Persist user↔agent conversations as the source of truth, emit a full debug trace per turn to a
SEPARATE telemetry system, and build a memory index the agent can search — each behind a slice so the
physical backend is swappable.

DELIVERABLES
1) `agent/chat` slice: Chat + Message models (Postgres), gateway-backed. Append messages, paginate by
   chat, list by agent. Message.content is Json (text + tool refs + attachments). Store the per-turn
   trace id on the message. Make the chat DB connection a CONFIG value (so it can later point to a
   dedicated Postgres instance without code changes). Add time/agent partitioning + an archive path
   to object storage for cold chats. Do NOT store raw prompts/traces here.
2) Tracing: instrument the orchestrator (api) to emit one trace per turn to self-hosted LANGFUSE
   (prompts, LLM calls, MCP tool_calls/results as spans, tokens, latency). Backend: Langfuse +
   ClickHouse. Retention policy: hot in ClickHouse, cold dropped/archived. No trace data in the chat DB.
3) `agent/memory` slice: an async deriver (queue job) that chunks + embeds NEW messages into a memory
   index (pgvector, reusing the LightRAG Postgres). Expose `memory_search` as a brain tool. Keep the
   backend behind the gateway so pgvector → Honcho/`tally` is a swap later.

CONTRACTS / CONVENTIONS
- CleanSlice: gateway pattern, `I`-prefixed DI tokens, ids `{slice}-{uuid}` in mapper.toCreate, no `any`.
- The deriver is async (BullMQ) — never block the chat write path.
- memory_search is a BRAIN tool (no secrets/KEK in any worker).

SECURITY: trace plane is internal (debug/eval), never surfaced to the user chat; PII retention policy
on traces; chat archive in tenant-scoped object storage.

ACCEPTANCE: see below. Start at the v0.2 scope (chat + trace); memory can follow.

Довідка

• Моделі: Chat / Message точно як у Storage і DB schema.
• Trace: один trace на турн, trace id зберігається на Message; спани для LLM + кожного MCP tools/call.
• Memory: Message → chunk → embed → pgvector; memory_search(query) → top-k, згодоване в цикл.

Впорядковані задачі

1. v0.2 — agent/chat (Postgres, gateway, пагінація) + Langfuse-інструментація турну.
2. + Memory — async-deriver + memory_search на pgvector.
3. + Scale — партиціонуй/архівуй таблицю Message; виокрем чат на виділений Postgres, коли IO виправдає.
4. + tally — поміняй memory-бекенд на Honcho/tally, коли знадобиться peer-memory.

Критерії приймання

• [ ] Повідомлення персистяться й пагінуються за чатом; з'єднання чат-БД — конфіг-значення (взаємозамінне).
• [ ] Кожен турн дає Langfuse-trace (промпти + виклики тулів + токени); жодних trace-блобів у Postgres.
• [ ] Повідомлення лінкується на свій trace id (стрибок із чату → повний debug).
• [ ] memory_search повертає релевантні хіти з минулих чатів через pgvector; deriver працює async, поза шляхом запису.
• [ ] Memory-бекенд за gateway (pgvector сьогодні, tally потім) — без змін у викликачах для заміни.

Дивіться також

• Огляд · Storage · Debug & tracing · Memory
• Conventions — правила CleanSlice, яких слід дотримуватися.