forge-server 0.1.0

package/src/memory/session-tracker.ts

@@ -0,0 +1,332 @@
+/**
+ * Session lifecycle and context tracking.
+ * Tracks current session ID, start time, and provides session-scoped observation queries.
+ * Sessions are identified by a timestamp-based ID generated at server startup.
+ *
+ * Phase 3: Sessions persist as Observation nodes in Qdrant with type: 'session_marker'.
+ * Cross-session retrieval queries those nodes to build a session registry.
+ */
+
+import { randomUUID } from 'crypto';
+import type { VectorStore } from '../storage/interfaces.js';
+import type { ObservationPayload } from '../util/types.js';
+import { embedText } from '../ingestion/embedder.js';
+import { logger } from '../util/logger.js';
+
+// The active session for this server process (created at startup)
+// Format: session-{timestamp} as specified in the architecture
+const SESSION_TIMESTAMP = Date.now();
+const SESSION_ID = `session-${SESSION_TIMESTAMP}`;
+const SESSION_START = SESSION_TIMESTAMP;
+
+// Track observation count for this session (in-memory)
+let observationCount = 0;
+
+// Whether we have already persisted this session's marker to Qdrant
+let sessionMarkerPersisted = false;
+
+/**
+ * Get the current session ID.
+ * Format: session-{timestamp}. Consistent for the lifetime of the MCP server process.
+ */
+export function getCurrentSessionId(): string {
+  return SESSION_ID;
+}
+
+/**
+ * Get the session start timestamp (Unix ms).
+ */
+export function getSessionStart(): number {
+  return SESSION_START;
+}
+
+/**
+ * Get session uptime in seconds.
+ */
+export function getUptimeSeconds(): number {
+  return Math.round((Date.now() - SESSION_START) / 1000);
+}
+
+/**
+ * Increment the in-memory observation count for this session.
+ * Called by observation-store after a successful save.
+ */
+export function incrementObservationCount(): void {
+  observationCount++;
+}
+
+/**
+ * Get the current session observation count.
+ */
+export function getObservationCount(): number {
+  return observationCount;
+}
+
+export interface SessionObservationGroup {
+  sessionId: string;
+  startedAt: number;
+  observations: Array<{
+    id: string;
+    content: string;
+    relevance_score: number;
+    is_stale: boolean;
+  }>;
+}
+
+/**
+ * Persist the current session as a session_marker observation in Qdrant.
+ * This enables cross-session discovery — other processes can find recent sessions
+ * by searching for type: 'session_marker' observations.
+ *
+ * Idempotent — only writes once per process lifecycle.
+ */
+export async function persistSessionMarker(vectorStore: VectorStore): Promise<void> {
+  if (sessionMarkerPersisted) return;
+
+  try {
+    const markerId = randomUUID();
+    const content = `Session ${SESSION_ID} started at ${new Date(SESSION_START).toISOString()}`;
+
+    // Embed the session marker content for potential semantic retrieval
+    let vector: number[];
+    try {
+      vector = await embedText(content);
+    } catch {
+      vector = new Array(384).fill(0);
+    }
+
+    const markerPayload: ObservationPayload = {
+      id: markerId,
+      repo_id: null,
+      session_id: SESSION_ID,
+      content,
+      type: 'working', // session markers are working memory
+      category: 'session_marker',
+      tags: ['session_marker'],
+      importance: 0.1,
+      created_at: SESSION_START,
+      accessed_at: SESSION_START,
+      access_count: 0,
+      is_stale: false,
+      linked_symbols: [],
+      source: 'forge',
+      metadata: {
+        session_id: SESSION_ID,
+        started_at: SESSION_START,
+        is_session_marker: true,
+      },
+      key: SESSION_ID,
+      namespace: 'session_registry',
+    };
+
+    await vectorStore.upsertObservation(markerId, vector, markerPayload);
+    sessionMarkerPersisted = true;
+    logger.debug('Session marker persisted', { sessionId: SESSION_ID });
+  } catch (err) {
+    logger.warn('Failed to persist session marker (non-fatal)', { error: String(err) });
+  }
+}
+
+/**
+ * Retrieve recent session IDs and their start times from Qdrant.
+ * Queries for session_marker observations ordered by created_at descending.
+ */
+export async function getRecentSessions(
+  vectorStore: VectorStore,
+  count: number = 5
+): Promise<Array<{ sessionId: string; startedAt: number }>> {
+  try {
+    const filter: Record<string, unknown> = {
+      must: [
+        { key: 'namespace', match: { value: 'session_registry' } },
+        { key: 'tags', match: { value: 'session_marker' } },
+      ],
+    };
+
+    const results = await vectorStore.filterObservations(filter, count * 2);
+
+    const sessions = results
+      .map(r => {
+        const payload = r.payload as ObservationPayload;
+        return {
+          sessionId: payload.session_id,
+          startedAt: payload.created_at,
+        };
+      })
+      // Sort by startedAt descending (most recent first)
+      .sort((a, b) => b.startedAt - a.startedAt)
+      // Deduplicate by sessionId (keep first/most-recent occurrence)
+      .filter((s, idx, arr) => arr.findIndex(x => x.sessionId === s.sessionId) === idx)
+      .slice(0, count);
+
+    return sessions;
+  } catch (err) {
+    logger.warn('Failed to get recent sessions', { error: String(err) });
+    return [];
+  }
+}
+
+/**
+ * Get observations from recent sessions.
+ * Phase 3: Queries the persistent session registry to find sessions,
+ * then retrieves observations for each one.
+ *
+ * If a query is provided, observations are ranked by semantic relevance.
+ * Otherwise they are returned in reverse chronological order.
+ */
+export async function getRecentSessionObservations(
+  vectorStore: VectorStore,
+  opts: {
+    query?: string;
+    queryVector?: number[];
+    sessionCount?: number;
+    limit?: number;
+  }
+): Promise<SessionObservationGroup[]> {
+  const { query, queryVector, sessionCount = 3, limit = 10 } = opts;
+
+  try {
+    // Always include the current session
+    const recentSessions = await getRecentSessions(vectorStore, sessionCount);
+
+    // Ensure the current session is included even if not yet persisted
+    const sessionIds = new Set<string>(recentSessions.map(s => s.sessionId));
+    sessionIds.add(SESSION_ID);
+
+    // Build the full session list with timestamps
+    const sessionsWithTime: Array<{ sessionId: string; startedAt: number }> = [
+      { sessionId: SESSION_ID, startedAt: SESSION_START },
+      ...recentSessions.filter(s => s.sessionId !== SESSION_ID),
+    ].slice(0, sessionCount);
+
+    // Determine the query vector for relevance ranking
+    let resolvedQueryVector: number[] | undefined = queryVector;
+    if (query && !resolvedQueryVector) {
+      try {
+        resolvedQueryVector = await embedText(query);
+      } catch {
+        resolvedQueryVector = undefined;
+      }
+    }
+
+    // Retrieve observations per session
+    const groups: SessionObservationGroup[] = [];
+
+    let remainingLimit = limit;
+
+    for (const session of sessionsWithTime) {
+      if (remainingLimit <= 0) break;
+
+      const sessionObs = await getSessionObservations(
+        vectorStore,
+        session.sessionId,
+        resolvedQueryVector,
+        remainingLimit
+      );
+
+      if (sessionObs.length > 0) {
+        groups.push({
+          sessionId: session.sessionId,
+          startedAt: session.startedAt,
+          observations: sessionObs,
+        });
+        remainingLimit -= sessionObs.length;
+      }
+    }
+
+    return groups;
+  } catch (err) {
+    logger.warn('Failed to get recent session observations', { error: String(err) });
+    return [];
+  }
+}
+
+/**
+ * Retrieve observations for a specific session from Qdrant.
+ * Excludes session_marker observations and stale observations.
+ * If a queryVector is provided, filters use it for ordering but Qdrant scroll
+ * doesn't support semantic ranking — we fetch extra and sort in memory.
+ */
+async function getSessionObservations(
+  vectorStore: VectorStore,
+  sessionId: string,
+  queryVector?: number[],
+  limit: number = 10
+): Promise<Array<{
+  id: string;
+  content: string;
+  relevance_score: number;
+  is_stale: boolean;
+}>> {
+  try {
+    // If we have a query vector, use semantic search for this session
+    if (queryVector) {
+      const results = await vectorStore.searchObservations(queryVector, {
+        limit: limit * 3,
+        scoreThreshold: 0.0,
+        filter: {
+          must: [
+            { key: 'session_id', match: { value: sessionId } },
+          ],
+          must_not: [
+            { key: 'tags', match: { value: 'session_marker' } },
+          ],
+        },
+      });
+
+      return results
+        .map(r => {
+          const payload = r.payload as ObservationPayload;
+          return {
+            id: payload.id,
+            content: payload.content,
+            relevance_score: Math.round(r.score * 1000) / 1000,
+            is_stale: payload.is_stale,
+          };
+        })
+        .filter(o => !o.is_stale)
+        .slice(0, limit);
+    }
+
+    // No query vector: use scroll (filterObservations) for chronological retrieval
+    const filter: Record<string, unknown> = {
+      session_id: sessionId,
+    };
+
+    const results = await vectorStore.filterObservations(filter, limit * 2);
+
+    return results
+      .map(r => {
+        const payload = r.payload as ObservationPayload;
+        return {
+          id: payload.id,
+          content: payload.content,
+          relevance_score: r.score,
+          is_stale: payload.is_stale,
+        };
+      })
+      // Exclude session_marker observations from result listing
+      .filter(o => !o.is_stale)
+      .slice(0, limit);
+  } catch (err) {
+    logger.warn('Failed to get session observations', { sessionId, error: String(err) });
+    return [];
+  }
+}
+
+/**
+ * Get the current session info summary.
+ */
+export function getSessionInfo(): {
+  sessionId: string;
+  startedAt: number;
+  uptimeSeconds: number;
+  observationCount: number;
+} {
+  return {
+    sessionId: SESSION_ID,
+    startedAt: SESSION_START,
+    uptimeSeconds: getUptimeSeconds(),
+    observationCount,
+  };
+}