💬 feat(chat): ChatService — cognitive chat orchestration with memory-primed context

[sbharatjoshi]

Summary

Build ChatService — the core orchestrator for cognitive chat interactions. It manages the full lifecycle: receive message → recall relevant memories → prime LLM context → execute agentic reasoning graph → stream response → persist conversation turn.

Strategic rationale: Cognitive chat is the #1 adoption driver. It's the feature users interact with daily and the most visible demonstration of Spector's memory advantage over stateless chatbots.

---

User Stories

Primary:
As an Agent Builder, I want to chat with an AI that has persistent memory so that our conversations build on each other over time instead of starting from zero every session.

Secondary:
As a Data Scientist, I want to see which memories were recalled to prime a response so that I can understand how memory quality affects answer quality and debug retrieval issues.

Tertiary:
As a Platform Operator, I want chat sessions to be persistent and recoverable so that I can resume conversations after a restart without losing context.

---

Acceptance Criteria

Core Chat Execution

• Given a user sends a message to POST /api/v1/chat, when the request contains a message and optional sessionId, then the system recalls relevant memories, primes the LLM context, executes the agentic reasoning graph, and returns a typed AgentChatResponse
• Given no sessionId is provided, when the chat service processes the request, then a new UUID session ID is generated with isNewSession: true
• Given an existing sessionId is provided, when the chat service processes the request, then conversation history for that session is loaded and included in the LLM context

Context Priming

• Given a user message arrives, when the ContextPrimingService processes it, then it retrieves session history and cross-session relevant memories via cognitive recall
• Given relevant memories are found, when they are injected into the system prompt, then each memory is formatted with metadata: [memory_type | age_description] text

Tool Approval

• Given the agent identifies a tool requiring user approval, when the tool is flagged, then the response returns with status: APPROVAL_REQUIRED and pendingToolCalls list
• Given the user approves pending tool calls, when the follow-up request contains approvedToolCalls, then the approved tools execute

Response

• Given a completed chat turn, when the response is serialized, then it includes: response, sessionId, isNewSession, model, status, latency, durationMs, primedMemories, trace, pendingToolCalls, sources
• Given enableTrace: true, when the chat executes, then the trace array contains TraceEvent records for every step

Persistence

• Given a completed chat turn with status: DONE, when both user message and response are non-empty, then the turn is persisted to session history

---

Scope

IN scope (MVP):

• ChatService.java — full chat lifecycle orchestration
• ChatController.java — REST endpoint
• ChatDto.java — 10 nested records (request, response, trace, session, models, config, tools)
• Agentic graph execution with tool calling
• Tool approval workflow
• Execution tracing
• Model listing from Ollama

OUT of scope:

• ContextPrimingService — separate issue
• ChatMemoryPort — separate issue
• Streaming — separate issue
• Session management — separate issue
• Multi-agent chat — future

---

Architecture

flowchart TD
    Client["Client (Cortex UI / API)"]
    
    subgraph ChatController["ChatController (REST API)"]
        EP1["POST /api/v1/chat"]
        EP5["GET /api/v1/chat/models"]
        EP6["GET /api/v1/chat/config"]
    end
    
    subgraph ChatService["ChatService (Orchestrator)"]
        S1["1. Prime context"]
        S2["2. Build message list"]
        S3["3. Run agentic graph"]
        S4["4. Persist turn"]
        S5["5. Return response"]
    end
    
    CPS["ContextPrimingService"]
    ACG["AgenticChatGraph (LangGraph4j)"]
    TR["ToolRegistry"]
    LLM["LLM Provider (Ollama)"]
    CMP["ChatMemoryPort (H2/JDBC)"]
    
    Client --> ChatController
    ChatController --> ChatService
    S1 --> CPS
    S3 --> ACG
    ACG --> TR
    ACG --> LLM
    S4 --> CMP

Loading

---

Getting Started

1. Key files:

   spector-synapse/src/main/java/.../synapse/agent/chat/
   ├── api/ChatController.java
   ├── service/ChatService.java
   └── dto/ChatDto.java
   

2. Test:

   curl -X POST http://localhost:7070/api/v1/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello, remember that my name is Bharat"}'

---

Success Metrics

Metric	Baseline	Target
End-to-end chat latency	N/A	< 10 seconds
Context priming recall relevance	N/A	80%+ accuracy
Session persistence reliability	N/A	100%
Concurrent sessions	N/A	100+ without degradation

---

RICE-C Score

Factor	Score	Rationale
Reach	5/5	Every user interacts via chat
Impact	3x	Primary interaction surface
Confidence	90%	Proven pattern from enterprise
Effort	L	~2 weeks
Cognitive Fit	5/5	Chat with memory recall IS cognitive memory

RICE-C Priority Score: 97.5

[github-actions]

This issue has been automatically marked as stale because it has not had activity in 30 days.

If you're still working on this or it's still relevant, please leave a comment and we'll keep it open. Otherwise, it will be closed in 14 days.

No pressure — life happens! You can always reopen or create a new issue later. 🙂

[jarvispectrayan]

Verified complete in codebase via commit 019e3bb0 (feat(synapse): add Agent Framework core + Cognitive Chat service). ChatService cognitive chat orchestration is implemented. Closing as DONE.