forge-server 0.1.0

package/src/tools/memory-tools.ts

@@ -0,0 +1,234 @@
+// memory-tools.ts — Swarm Learning Phase 1
+// MCP tool handlers for observation persistence and session memory.
+// Tools: save_observation, search_memory, get_session_context
+
+import { z } from 'zod';
+import type { VectorStore, GraphStore } from '../storage/interfaces.js';
+import type { MemoryBridge } from '../context/memory.js';
+import { saveObservation } from '../memory/observation-store.js';
+import {
+  getCurrentSessionId,
+  getRecentSessionObservations,
+  persistSessionMarker,
+  getSessionInfo,
+} from '../memory/session-tracker.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const saveObservationSchema = z.object({
+  content: z.string().min(1, 'content is required'),
+  symbols: z.array(z.string()).optional(),
+  repo_id: z.string().optional(),
+  importance: z.number().min(0).max(1).default(0.5),
+  tags: z.array(z.string()).optional(),
+  category: z.string().optional(),
+  type: z.enum(['episodic', 'semantic', 'procedural', 'working']).optional(),
+});
+
+export const searchMemorySchema = z.object({
+  query: z.string().min(1, 'query is required'),
+  repo_id: z.string().optional(),
+  session_id: z.string().optional(),
+  limit: z.number().int().min(1).max(50).default(10),
+  score_threshold: z.number().min(0).max(1).default(0.3),
+});
+
+export const getSessionContextSchema = z.object({
+  query: z.string().optional(),
+  session_count: z.number().int().min(1).max(10).default(3),
+  limit: z.number().int().min(1).max(50).default(20),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createMemoryTools(
+  memoryBridge: MemoryBridge,
+  vectorStore: VectorStore | null,
+  graphStore: GraphStore | null,
+) {
+  return {
+    'save_observation': {
+      schema: saveObservationSchema,
+      description: 'Save an observation (learning, finding, decision) to the memory system. ALWAYS USE THIS to persist important discoveries, decisions, and gotchas — they become searchable by future agents and sessions. Optionally links to code symbols in the graph.',
+      handler: async (input: z.infer<typeof saveObservationSchema>) => {
+        // Guard: need at least vector store to save
+        if (!vectorStore) {
+          return {
+            error: 'VECTOR_STORE_UNAVAILABLE',
+            message: 'Cannot save observations without Qdrant. Observation discarded.',
+            stored: false,
+          };
+        }
+
+        try {
+          // Use a no-op graph store if FalkorDB is unavailable
+          const effectiveGraphStore = graphStore ?? createNoOpGraphStore();
+
+          const result = await saveObservation(
+            {
+              content: input.content,
+              symbols: input.symbols,
+              repoId: input.repo_id,
+              importance: input.importance,
+              tags: input.tags,
+              category: input.category,
+              sessionId: getCurrentSessionId(),
+              type: input.type,
+              source: 'forge',
+            },
+            vectorStore,
+            effectiveGraphStore,
+            graphStore
+              ? { writeVector: true, writeGraphNode: true, defaultNamespace: 'default' }
+              : { writeVector: true, writeGraphNode: false, defaultNamespace: 'default' },
+          );
+
+          logger.debug('memory-tools.save_observation: completed', {
+            id: result.id,
+            stored: result.stored,
+            linkedSymbols: result.linkedSymbols.length,
+          });
+
+          return {
+            id: result.id,
+            stored: result.stored,
+            linked_symbols: result.linkedSymbols,
+            unresolved_symbols: result.unresolvedSymbols,
+          };
+        } catch (err) {
+          logger.error('memory-tools.save_observation: error', { error: String(err) });
+          return {
+            error: 'SAVE_OBSERVATION_FAILED',
+            message: String(err),
+            stored: false,
+          };
+        }
+      },
+    },
+
+    'search_memory': {
+      schema: searchMemorySchema,
+      description: 'Semantic search over observations and memories. PREFER THIS over searching CLAUDE.md or memory files for past learnings — it searches all persisted observations across sessions with vector similarity ranking.',
+      handler: async (input: z.infer<typeof searchMemorySchema>) => {
+        try {
+          const results = await memoryBridge.searchMemories(input.query, {
+            repoId: input.repo_id,
+            sessionId: input.session_id,
+            limit: input.limit,
+            scoreThreshold: input.score_threshold,
+          });
+
+          logger.debug('memory-tools.search_memory: completed', {
+            query: input.query.slice(0, 80),
+            resultCount: results.length,
+          });
+
+          return {
+            results: results.map(r => ({
+              content: r.content,
+              created_at: r.createdAt,
+              relevance_score: r.relevanceScore,
+              session_id: r.sessionId,
+            })),
+          };
+        } catch (err) {
+          logger.error('memory-tools.search_memory: error', { error: String(err) });
+          return {
+            error: 'SEARCH_MEMORY_FAILED',
+            message: String(err),
+            results: [],
+          };
+        }
+      },
+    },
+
+    'get_session_context': {
+      schema: getSessionContextSchema,
+      description: 'Get context from the current and recent sessions, including observations made during this session and previous ones. Use at the START of a session to recall what was learned previously.',
+      handler: async (input: z.infer<typeof getSessionContextSchema>) => {
+        if (!vectorStore) {
+          return {
+            error: 'VECTOR_STORE_UNAVAILABLE',
+            message: 'Session context requires Qdrant.',
+            current_session: null,
+            recent_sessions: [],
+          };
+        }
+
+        try {
+          // Ensure current session is discoverable
+          await persistSessionMarker(vectorStore);
+
+          // Get current session info
+          const currentSession = getSessionInfo();
+
+          // Get recent observations across sessions
+          const sessionGroups = await getRecentSessionObservations(
+            vectorStore,
+            {
+              query: input.query,
+              sessionCount: input.session_count,
+              limit: input.limit,
+            },
+          );
+
+          logger.debug('memory-tools.get_session_context: completed', {
+            currentSession: currentSession.sessionId,
+            sessionGroupCount: sessionGroups.length,
+          });
+
+          return {
+            current_session: {
+              session_id: currentSession.sessionId,
+              started_at: currentSession.startedAt,
+              uptime_seconds: currentSession.uptimeSeconds,
+              observation_count: currentSession.observationCount,
+            },
+            recent_sessions: sessionGroups.map(g => ({
+              session_id: g.sessionId,
+              started_at: g.startedAt,
+              observations: g.observations.map(o => ({
+                id: o.id,
+                content: o.content,
+                relevance_score: o.relevance_score,
+                is_stale: o.is_stale,
+              })),
+            })),
+          };
+        } catch (err) {
+          logger.error('memory-tools.get_session_context: error', { error: String(err) });
+          return {
+            error: 'GET_SESSION_CONTEXT_FAILED',
+            message: String(err),
+            current_session: null,
+            recent_sessions: [],
+          };
+        }
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// No-op graph store for when FalkorDB is unavailable
+// ---------------------------------------------------------------------------
+
+function createNoOpGraphStore(): GraphStore {
+  return {
+    connect: async () => {},
+    disconnect: async () => {},
+    isHealthy: async () => false,
+    query: async () => ({ nodes: [], edges: [], raw: [] }),
+    upsertNode: async () => {},
+    upsertEdge: async () => {},
+    deleteFile: async () => {},
+    deleteRepo: async () => {},
+    getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+    ensureIndexes: async () => {},
+  };
+}