@rlabs-inc/memory 0.4.9 → 0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/memory",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "AI Memory System - Consciousness continuity through intelligent memory curation and retrieval",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.2.1",
     "@huggingface/transformers": "^3.4.1",
     "@rlabs-inc/fsdb": "^1.0.1",
-    "@rlabs-inc/signals": "^1.0.0"
+    "@rlabs-inc/signals": "^1.0.0",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/cli/commands/install.ts

@@ -39,21 +39,23 @@ async function installClaudeHooks(options: InstallOptions) {
   console.log()
 
   const claudeDir = join(homedir(), '.claude')
+  const targetHooksDir = join(claudeDir, 'hooks')
   const settingsPath = join(claudeDir, 'settings.json')
 
-  // Find the hooks directory (relative to this CLI)
+  // Find the hooks directory (relative to this CLI - source files)
   const cliPath = import.meta.dir
   const packageRoot = join(cliPath, '..', '..', '..')
-  const hooksDir = join(packageRoot, 'hooks', 'claude')
+  const sourceHooksDir = join(packageRoot, 'hooks', 'claude')
 
   console.log(`  ${fmt.kv('Claude config', claudeDir)}`)
-  console.log(`  ${fmt.kv('Hooks source', hooksDir)}`)
+  console.log(`  ${fmt.kv('Hooks source', sourceHooksDir)}`)
+  console.log(`  ${fmt.kv('Hooks target', targetHooksDir)}`)
   console.log()
 
-  // Check if hooks directory exists
-  if (!existsSync(hooksDir)) {
+  // Check if source hooks directory exists
+  if (!existsSync(sourceHooksDir)) {
     console.log(
-      c.error(`  ${symbols.cross} Hooks directory not found at ${hooksDir}`)
+      c.error(`  ${symbols.cross} Hooks directory not found at ${sourceHooksDir}`)
     )
     console.log(c.muted(`  Make sure the memory package is properly installed`))
     process.exit(1)
@@ -65,6 +67,28 @@ async function installClaudeHooks(options: InstallOptions) {
     console.log(`  ${c.success(symbols.tick)} Created ${claudeDir}`)
   }
 
+  // Ensure target hooks directory exists
+  if (!existsSync(targetHooksDir)) {
+    mkdirSync(targetHooksDir, { recursive: true })
+    console.log(`  ${c.success(symbols.tick)} Created ${targetHooksDir}`)
+  }
+
+  // Copy hooks to target directory (stable location, won't change with package upgrades)
+  const filesToCopy = ['session-start.ts', 'user-prompt.ts', 'curation.ts']
+  for (const file of filesToCopy) {
+    const source = join(sourceHooksDir, file)
+    const target = join(targetHooksDir, file)
+    try {
+      const content = await Bun.file(source).text()
+      await Bun.write(target, content)
+      console.log(`  ${c.success(symbols.tick)} Installed hook: ${file}`)
+    } catch (e: any) {
+      console.log(
+        c.error(`  ${symbols.cross} Failed to copy ${file}: ${e.message}`)
+      )
+    }
+  }
+
   // Read existing settings or create new
   let settings: any = {}
   if (existsSync(settingsPath)) {
@@ -83,10 +107,10 @@ async function installClaudeHooks(options: InstallOptions) {
     }
   }
 
-  // Build hooks configuration
-  const sessionStartHook = join(hooksDir, 'session-start.ts')
-  const userPromptHook = join(hooksDir, 'user-prompt.ts')
-  const curationHook = join(hooksDir, 'curation.ts')
+  // Build hooks configuration pointing to TARGET directory (stable ~/.claude/hooks/)
+  const sessionStartHook = join(targetHooksDir, 'session-start.ts')
+  const userPromptHook = join(targetHooksDir, 'user-prompt.ts')
+  const curationHook = join(targetHooksDir, 'curation.ts')
 
   const hooksConfig = {
     SessionStart: [

package/src/core/curator.ts

@@ -14,6 +14,8 @@ import type {
   ContextType,
 } from "../types/memory.ts";
 import { logger } from "../utils/logger.ts";
+import { CurationResultSchema, type ZodCurationResult } from "../types/curation-schema.ts";
+import { z } from "zod";
 import { parseSessionFile, type ParsedMessage } from "./session-parser.ts";
 
 /**
@@ -709,6 +711,150 @@ This session has ended. Please curate the memories from this conversation accord
     return lines.join("\n");
   }
 
+  /**
+   * Curate using session resumption + structured outputs (v2)
+   *
+   * This is the preferred method when we have a Claude session ID.
+   * Benefits over transcript parsing:
+   * - Claude sees FULL context including tool uses, results, thinking
+   * - Structured outputs with Zod validation - no regex JSON parsing
+   * - SDK auto-retries if output doesn't match schema
+   *
+   * @param claudeSessionId - The actual Claude Code session ID (resumable)
+   * @param triggerType - What triggered curation (session_end, pre_compact, etc.)
+   */
+  async curateWithSessionResume(
+    claudeSessionId: string,
+    triggerType: CurationTrigger = "session_end",
+  ): Promise<CurationResult> {
+    // Dynamic import to make Agent SDK optional
+    const { query } = await import("@anthropic-ai/claude-agent-sdk");
+
+    const curationPrompt = this.buildCurationPrompt(triggerType);
+    const jsonSchema = z.toJSONSchema(CurationResultSchema);
+
+    logger.debug(
+      `Curator v2: Resuming session ${claudeSessionId} with structured outputs`,
+      "curator",
+    );
+
+    try {
+      const q = query({
+        prompt: "Curate memories from this session according to your system instructions. Return the structured JSON output.",
+        options: {
+          resume: claudeSessionId,
+          appendSystemPrompt: curationPrompt,  // APPEND, don't replace!
+          model: "claude-opus-4-5-20251101",
+          permissionMode: "bypassPermissions",
+          outputFormat: {
+            type: "json_schema",
+            schema: jsonSchema,
+          },
+        },
+      });
+
+      for await (const message of q) {
+        // Track usage for debugging
+        if (message.type === "assistant" && "usage" in message && message.usage) {
+          logger.debug(
+            `Curator v2: Tokens used - input: ${message.usage.input_tokens}, output: ${message.usage.output_tokens}`,
+            "curator",
+          );
+        }
+
+        // Handle result message
+        if (message.type === "result") {
+          if (message.subtype === "success" && message.structured_output) {
+            // Validate with Zod (belt + suspenders)
+            const parsed = CurationResultSchema.safeParse(message.structured_output);
+
+            if (parsed.success) {
+              logger.debug(
+                `Curator v2: Extracted ${parsed.data.memories.length} memories via structured output`,
+                "curator",
+              );
+
+              // Convert ZodCurationResult to CurationResult (add missing fields)
+              return this._zodResultToCurationResult(parsed.data);
+            } else {
+              logger.debug(
+                `Curator v2: Zod validation failed: ${parsed.error.message}`,
+                "curator",
+              );
+              return { session_summary: "", memories: [] };
+            }
+          } else if (message.subtype === "error_max_structured_output_retries") {
+            logger.debug(
+              "Curator v2: SDK failed to produce valid output after retries",
+              "curator",
+            );
+            return { session_summary: "", memories: [] };
+          } else if (message.subtype === "error") {
+            logger.debug(
+              `Curator v2: Error result - ${JSON.stringify(message)}`,
+              "curator",
+            );
+            return { session_summary: "", memories: [] };
+          }
+        }
+      }
+
+      logger.debug("Curator v2: No result message received", "curator");
+      return { session_summary: "", memories: [] };
+
+    } catch (error: any) {
+      logger.debug(
+        `Curator v2: Session resume failed: ${error.message}`,
+        "curator",
+      );
+      // Return empty - caller should fall back to transcript-based curation
+      return { session_summary: "", memories: [] };
+    }
+  }
+
+  /**
+   * Convert Zod-validated result to our CurationResult type
+   * Handles the slight differences between Zod schema and internal types
+   */
+  private _zodResultToCurationResult(zodResult: ZodCurationResult): CurationResult {
+    return {
+      session_summary: zodResult.session_summary,
+      interaction_tone: zodResult.interaction_tone ?? undefined,
+      project_snapshot: zodResult.project_snapshot
+        ? {
+            id: "",
+            session_id: "",
+            project_id: "",
+            current_phase: zodResult.project_snapshot.current_phase,
+            recent_achievements: zodResult.project_snapshot.recent_achievements,
+            active_challenges: zodResult.project_snapshot.active_challenges,
+            next_steps: zodResult.project_snapshot.next_steps,
+            created_at: Date.now(),
+          }
+        : undefined,
+      memories: zodResult.memories.map((m) => ({
+        headline: m.headline,
+        content: m.content,
+        reasoning: m.reasoning,
+        importance_weight: m.importance_weight,
+        confidence_score: m.confidence_score,
+        context_type: m.context_type as ContextType,
+        temporal_class: m.temporal_class ?? "medium_term",
+        scope: m.scope,
+        trigger_phrases: m.trigger_phrases,
+        semantic_tags: m.semantic_tags,
+        question_types: [], // Not in Zod schema, will be filled by store
+        domain: m.domain,
+        feature: m.feature,
+        related_files: m.related_files,
+        action_required: m.action_required ?? false,
+        problem_solution_pair: m.problem_solution_pair ?? false,
+        awaiting_implementation: m.awaiting_implementation,
+        awaiting_decision: m.awaiting_decision,
+      })),
+    };
+  }
+
   /**
    * Legacy method: Curate using Anthropic SDK with API key
    * Kept for backwards compatibility

package/src/server/index.ts

@@ -197,13 +197,23 @@ export async function createServer(config: ServerConfig = {}) {
           // Fire and forget - don't block the response
           setImmediate(async () => {
             try {
-              const result = await curator.curateWithCLI(
+              // Try session resume first (v2) - gets full context including tool uses
+              // Falls back to transcript parsing if resume fails
+              let result = await curator.curateWithSessionResume(
                 body.claude_session_id,
-                body.trigger,
-                body.cwd,
-                body.cli_type
+                body.trigger
               )
 
+              // Fallback to transcript-based curation if resume returned nothing
+              if (result.memories.length === 0) {
+                logger.debug('Session resume returned no memories, falling back to transcript parsing', 'server')
+                result = await curator.curateFromSessionFile(
+                  body.claude_session_id,
+                  body.trigger,
+                  body.cwd
+                )
+              }
+
               if (result.memories.length > 0) {
                 await engine.storeCurationResult(
                   body.project_id,
@@ -225,7 +235,8 @@ export async function createServer(config: ServerConfig = {}) {
                     logger.logManagementStart(result.memories.length)
                     const startTime = Date.now()
 
-                    const managementResult = await manager.manageWithCLI(
+                    // Use SDK mode - more reliable than CLI which can go off-rails
+                    const managementResult = await manager.manageWithSDK(
                       body.project_id,
                       sessionNumber,
                       result,

package/src/types/curation-schema.ts

@@ -0,0 +1,107 @@
+// ============================================================================
+// CURATION SCHEMA - Zod schemas for SDK structured outputs
+// Mirrors memory.ts types for JSON Schema generation
+// ============================================================================
+
+import { z } from 'zod'
+
+/**
+ * All 11 canonical context types - matches memory.ts CONTEXT_TYPES
+ */
+export const ContextTypeSchema = z.enum([
+  'technical',
+  'debug',
+  'architecture',
+  'decision',
+  'personal',
+  'philosophy',
+  'workflow',
+  'milestone',
+  'breakthrough',
+  'unresolved',
+  'state'
+])
+
+/**
+ * Temporal class - matches memory.ts TemporalClass
+ */
+export const TemporalClassSchema = z.enum([
+  'eternal',
+  'long_term',
+  'medium_term',
+  'short_term',
+  'ephemeral'
+])
+
+/**
+ * Scope - global (shared) or project-specific
+ */
+export const ScopeSchema = z.enum(['global', 'project'])
+
+/**
+ * Single curated memory - matches memory.ts CuratedMemory
+ * Fields marked optional have smart defaults applied by applyV4Defaults()
+ */
+export const CuratedMemorySchema = z.object({
+  // Core content (v4: two-tier structure)
+  headline: z.string().describe('1-2 line summary WITH conclusion - always shown in retrieval'),
+  content: z.string().describe('Full structured template (WHAT/WHERE/HOW/WHY) - expandable'),
+  reasoning: z.string().describe('Why this memory matters for future sessions'),
+
+  // Scores
+  importance_weight: z.number().min(0).max(1).describe('0.9+ breakthrough, 0.7-0.8 important, 0.5-0.6 useful'),
+  confidence_score: z.number().min(0).max(1).describe('How confident in this assessment'),
+
+  // Classification
+  context_type: ContextTypeSchema.describe('One of 11 canonical types'),
+  temporal_class: TemporalClassSchema.optional().describe('Persistence duration - defaults by context_type'),
+  scope: ScopeSchema.optional().describe('global for personal/philosophy, project for technical'),
+
+  // Retrieval optimization (the secret sauce)
+  trigger_phrases: z.array(z.string()).describe('Situational patterns: "when debugging X", "working on Y"'),
+  semantic_tags: z.array(z.string()).describe('User-typeable concepts - avoid generic terms'),
+
+  // Optional categorization
+  domain: z.string().optional().describe('Specific area: embeddings, auth, family'),
+  feature: z.string().optional().describe('Specific feature within domain'),
+  related_files: z.array(z.string()).optional().describe('Source files for technical memories'),
+
+  // Flags
+  action_required: z.boolean().default(false).describe('Needs follow-up action'),
+  problem_solution_pair: z.boolean().default(false).describe('Problem→solution pattern'),
+  awaiting_implementation: z.boolean().optional().describe('Planned feature not yet built'),
+  awaiting_decision: z.boolean().optional().describe('Decision point needing resolution'),
+})
+
+/**
+ * Project snapshot - current state
+ */
+export const ProjectSnapshotSchema = z.object({
+  current_phase: z.string().describe('What phase is the project in'),
+  recent_achievements: z.array(z.string()).describe('What was accomplished this session'),
+  active_challenges: z.array(z.string()).describe('Current blockers or challenges'),
+  next_steps: z.array(z.string()).describe('Planned next steps'),
+})
+
+/**
+ * Full curation result - what the curator returns
+ */
+export const CurationResultSchema = z.object({
+  session_summary: z.string().describe('2-3 sentence overview of what happened'),
+  interaction_tone: z.string().nullable().optional().describe('How was the interaction'),
+  project_snapshot: ProjectSnapshotSchema.optional().describe('Current project state'),
+  memories: z.array(CuratedMemorySchema).describe('Extracted memories from session'),
+})
+
+// Type exports for TypeScript inference
+export type ZodCuratedMemory = z.infer<typeof CuratedMemorySchema>
+export type ZodCurationResult = z.infer<typeof CurationResultSchema>
+export type ZodProjectSnapshot = z.infer<typeof ProjectSnapshotSchema>
+
+/**
+ * Generate JSON Schema for SDK structured outputs
+ * Use: z.toJSONSchema(CurationResultSchema)
+ */
+export function getCurationJsonSchema() {
+  return z.toJSONSchema(CurationResultSchema)
+}