Implementation

A build prompt for an AI coding agent: implement chat storage, the debug/trace plane, and the chat-memory index — three stores behind their slices. Read Overview, Storage, Debug & tracing and Memory first.

This page is an agent prompt

Every section gets an Implementation page — a precise, copy-paste task spec the agent executes.

The prompt

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.

Reference

• Models: Chat / Message exactly as in Storage and DB schema.
• Trace: one trace per turn, trace id stored on the Message; spans for LLM + each MCP tools/call.
• Memory: Message → chunk → embed → pgvector; memory_search(query) → top-k fed into the loop.

Ordered tasks

1. v0.2 — agent/chat (Postgres, gateway, pagination) + Langfuse instrumentation of the turn.
2. + Memory — the async deriver + memory_search on pgvector.
3. + Scale — partition/archive the Message table; split chat to a dedicated Postgres when IO warrants.
4. + tally — swap memory backend to Honcho/tally when peer-memory is needed.

Acceptance criteria

• [ ] Messages persist and paginate by chat; the chat DB connection is a config value (swappable).
• [ ] Every turn produces a Langfuse trace (prompts + tool calls + tokens); no trace blobs in Postgres.
• [ ] A message links to its trace id (jump from chat → full debug).
• [ ] memory_search returns relevant past-chat hits via pgvector; the deriver runs async, off the write path.
• [ ] The memory backend is behind a gateway (pgvector today, tally later) — no caller changes to swap.

See also

• Overview · Storage · Debug & tracing · Memory
• Conventions — the CleanSlice rules to follow.