roadmap phase 1 complete

packages/orchestration-service/CLAUDE.md

@@ -24,10 +24,25 @@ Default port: **4000**. Depends on memory-service, embedding-service, inference-
    - No project: `must: [sessionId == this session]`
    - Project: `should: [sessionId == s1, sessionId == s2, ...]` across all project sessions
    - Dedup against recent episode IDs before including.
-5. Embed and search Qdrant ENTITIES; filter by `projectId` if applicable.
-6. Build prompt in this fixed order: **system prompt → entities → semantic episodes → recent episodes → user message → "Assistant:"**
+5. Embed and search Qdrant ENTITIES (filtered by `projectId` if in a project). Returns entity IDs alongside payload — the Qdrant point ID equals the SQLite entity ID.
+6. Expand matched entities into a 1-hop graph neighborhood via `POST /graph/neighbors` on the memory-service. Returns `{ nodes, edges }` — the full entity objects plus connecting relationships. Falls back to flat entity list (no edges) if the graph call fails.
+7. Build prompt in this fixed order: **system prompt → graph context → semantic episodes → recent episodes → user message → "Assistant:"**
 
-The ordering prioritizes established facts (entities) and relevant past context (semantic) over pure recency.
+The ordering prioritizes established facts (graph context) and relevant past context (semantic) over pure recency.
+
+## Graph Context Format
+
+`formatGraphContext(nodes, edges)` in `src/chat/index.js` formats the neighborhood as:
+
+```
+- Alice (person): software engineer working on NexusAI
+  → works_on NexusAI (project)
+  → knows Bob (person)
+- NexusAI (project): AI assistant framework
+- Bob (person): Alice's colleague
+```
+
+Each node shows its notes on the first line. Outbound edges are indented below with `→ label target (type)`. Nodes with only inbound edges (neighbors pulled in by traversal) appear without connection lines.
 
 ## System Prompt Resolution
 
@@ -85,6 +100,12 @@ When the existing summary's token count exceeds `SUMMARIES.MAX_SUMMARY_TOKENS`,
 
 `searchEntities` checks `projectId !== null && projectId !== undefined` before applying the filter — a session with no project skips the filter entirely and searches globally.
 
+## Graph Service Client (`src/services/graph.js`)
+
+Thin HTTP client for memory-service graph endpoints. One function:
+
+- **`getNeighbors(entityIds[])`** — POSTs to `memory-service/graph/neighbors` with the entity IDs from Qdrant entity search. Returns `{ nodes, edges }`. Throws on non-2xx — caller wraps in try/catch with graceful fallback.
+
 ## Models Endpoint
 
 `GET /models` scans `modelsFolderPath` for `.gguf` files and optionally reads a `models.json` manifest (keyed by filename) for labels and descriptions. File size is reported in GB. Returns 500 if the folder is inaccessible.
@@ -96,9 +117,7 @@ When the existing summary's token count exceeds `SUMMARIES.MAX_SUMMARY_TOKENS`,
 `GET /health/services` runs parallel fetch calls to all four dependent services with a 3-second `AbortSignal.timeout` each. Results are returned as an array — the endpoint never returns a non-2xx itself regardless of downstream status.
 
 ## Background Model (qwen2.5:3b)
-Used for entity extraction and summarization via Ollama on Mini PC 1. Uses **ChatML 
-format** (`<|im_start|>` / `<|im_end|>`) — not Phi3 format. Use `format: 'json'` 
-only for structured extraction, never for free-text summarization.
+Used for entity/relationship extraction and summarization via Ollama on Mini PC 1. Uses **ChatML format** (`<|im_start|>` / `<|im_end|>`) — not Phi3 format. Use `format: 'json'` only for structured extraction, never for free-text summarization.
 
 ## API Endpoints Quick Reference
 

packages/orchestration-service/src/chat/index.js

@@ -5,22 +5,20 @@ const qdrant = require("../services/qdrant");
 const { ORCHESTRATION, logger } = require("@nexusai/shared");
 const appSettings = require("../config/settings");
 const {triggerSummary} = require('../services/summarization')
+const graph = require('../services/graph');
 
-function buildPrompt(recentEpisodes, semanticEpisodes, entities, userMessage, systemPrompt) {
+function buildPrompt(recentEpisodes, semanticEpisodes, neighborhood, userMessage, systemPrompt) {
     const parts = [systemPrompt ?? ORCHESTRATION.SYSTEM_PROMPT];
 
-  if (entities.length > 0) {
-    parts.push(
-      "Here is what you know about entities relevant to this conversation:",
-    );
-    for (const e of entities) {
-      parts.push(`- ${e.name} (${e.type}): ${e.notes}`);
+    const graphText = formatGraphContext(neighborhood.nodes ?? [], neighborhood.edges ?? []);
+    if (graphText) {
+        parts.push("Here is what you know about entities relevant to this conversation and their connections:");
+        parts.push(graphText);
+        parts.push("---");
     }
-    parts.push("---");
-  }
 
   if (semanticEpisodes.length > 0) {
-    parts.push("Here are some relevant memories from earlier conversations:");
+    parts.push("Long-term memory (semantically relevant to this message):");
     for (const ep of semanticEpisodes) {
       parts.push(`User: ${ep.user_message}\nAssistant: ${ep.ai_response}`);
     }
@@ -28,7 +26,7 @@ function buildPrompt(recentEpisodes, semanticEpisodes, entities, userMessage, sy
   }
 
   if (recentEpisodes.length > 0) {
-    parts.push(`Here are some relevant memories from your past conversations:`);
+    parts.push("Recent conversation history (most recent exchanges):");
     for (const ep of recentEpisodes) {
       parts.push(`User: ${ep.user_message}\nAssistant: ${ep.ai_response}`);
     }
@@ -54,6 +52,28 @@ function buildNamingPrompt(userMessage, aiResponse) {
   ].join("\n");
 }
 
+function formatGraphContext(nodes, edges) {
+    if (!nodes.length) return null;
+
+    const nodeMap = new Map(nodes.map(n => [n.id, n]));
+
+    // Build outbound adjacency
+    const outbound = new Map(nodes.map(n => [n.id, []]));
+    for (const edge of edges) {
+        if (outbound.has(edge.from_id) && nodeMap.has(edge.to_id)) {
+            const target = nodeMap.get(edge.to_id);
+            outbound.get(edge.from_id).push(`${edge.label} ${target.name} (${target.type})`);
+        }
+    }
+
+    return nodes.map(n => {
+        const lines = [`- ${n.name} (${n.type}): ${n.notes ?? '(no notes)'}`];
+        for (const conn of outbound.get(n.id) ?? []) lines.push(`  → ${conn}`);
+        return lines.join('\n');
+    }).join('\n');
+}
+
+
 async function autoNameSession(externalId, userMessage, aiResponse) {
   try {
     const prompt = buildNamingPrompt(userMessage, aiResponse);
@@ -107,22 +127,20 @@ async function getSemanticEpisodes(
   }
 }
 
-async function getRelevantEntities(userMessage, projectId=null) {
-  try {
-    const vector = await embedding.embed(userMessage);
-    const results = await qdrant.searchEntities(vector, { projectId });
-    logger.info(
-      "[orchestration] Entity search results:",
-      results.map((r) => ({ name: r.payload?.name, score: r.score })),
-    );
-    return results.map((r) => r.payload).filter(Boolean);
-  } catch (err) {
-    logger.debug(
-      "[orchestration] Entity search failed, continuing without:",
-      err.message,
-    );
-    return [];
-  }
+async function getRelevantEntities(userMessage, projectId = null) {
+    try {
+        const vector = await embedding.embed(userMessage);
+        const results = await qdrant.searchEntities(vector, { projectId });
+        logger.info(
+            '[orchestration] Entity search results:',
+            results.map((r) => ({ name: r.payload?.name, score: r.score })),
+        );
+        // Include the Qdrant point ID (== SQLite entity ID) for graph traversal
+        return results.map((r) => r.payload ? { id: r.id, ...r.payload } : null).filter(Boolean);
+    } catch (err) {
+        logger.debug('[orchestration] Entity search failed, continuing without:', err.message);
+        return [];
+    }
 }
 
 async function assembleContext(externalId, userMessage) {
@@ -159,10 +177,22 @@ async function assembleContext(externalId, userMessage) {
     const semanticEpisodes = await getSemanticEpisodes(
         userMessage, session.id, recentIds, projectSessionIds, { semanticLimit, scoreThreshold }
     );
-    const entities = await getRelevantEntities(userMessage, session.project_id ?? null);
+    const entityResults = await getRelevantEntities(userMessage, session.project_id ?? null);
 
-    // 5. Assemble prompt
-    const prompt = buildPrompt(recentEpisodes, semanticEpisodes, entities, userMessage, activeSystemPrompt);
+    // 5. Expand matched entities into 1-hop graph neighborhood
+    let neighborhood = { nodes: [], edges: [] };
+    if (entityResults.length > 0) {
+        try {
+            neighborhood = await graph.getNeighbors(entityResults.map(e => e.id));
+        } catch (err) {
+            logger.warn('[orchestration] Graph neighborhood fetch failed, falling back to flat entities:', err.message);
+            // Graceful fallback: use Qdrant payload data as flat nodes, no edges
+            neighborhood = { nodes: entityResults, edges: [] };
+        }
+    }
+
+    // 6. Assemble prompt
+    const prompt = buildPrompt(recentEpisodes, semanticEpisodes, neighborhood, userMessage, activeSystemPrompt);
 
     return {
         session,

packages/orchestration-service/src/services/graph.js

@@ -0,0 +1,15 @@
+const { getEnv, SERVICES } = require('@nexusai/shared');
+
+const MEMORY_URL = getEnv('MEMORY_SERVICE_URL', SERVICES.MEMORY_URL);
+
+async function getNeighbors(entityIds) {
+    const res = await fetch(`${MEMORY_URL}/graph/neighbors`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ entityIds }),
+    });
+    if (!res.ok) throw new Error(`Graph neighbors error: ${res.status}`);
+    return res.json();
+}
+
+module.exports = { getNeighbors };