@rlabs-inc/memory 0.3.9 → 0.3.11

package/README.md

@@ -336,6 +336,17 @@ This isn't just about remembering facts. It's about preserving:
 
 ## Changelog
 
+### v0.3.11
+- **Feature**: Agent SDK integration for curator and manager - no API key needed, uses Claude Code OAuth
+- **Feature**: `memory ingest --session <id>` to ingest a single session (useful when automatic curation fails)
+- **Feature**: Manager now runs after each session during ingestion to organize/link memories
+- **Improvement**: Spinner activity indicator during long curator and manager operations
+- **Improvement**: Better manager output with colored stats (superseded, resolved, linked)
+- **Improvement**: DEBUG logs now only show with `--verbose` flag
+
+### v0.3.10
+- **Improvement**: Use `which claude` for universal CLI path discovery - works with any installation method (native, homebrew, npm)
+
 ### v0.3.9
 - **Fix**: Claude Code v2.0.76+ changed `--output-format json` from single object to array of events. Updated curator and manager to handle both formats with backwards compatibility.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/memory",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "AI Memory System - Consciousness continuity through intelligent memory curation and retrieval",
   "type": "module",
   "main": "dist/index.js",
@@ -39,6 +39,7 @@
     "cli": "bun src/cli/index.ts"
   },
   "dependencies": {
+    "@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"

package/src/cli/commands/ingest.ts

@@ -8,21 +8,63 @@ import { styleText } from 'util'
 import {
   findAllSessions,
   findProjectSessions,
+  parseSessionFile,
   parseSessionFileWithSegments,
   getSessionSummary,
   calculateStats,
   type ParsedProject,
+  type ParsedSession,
 } from '../../core/session-parser.ts'
 import { Curator } from '../../core/curator.ts'
+import { Manager, type StoragePaths } from '../../core/manager.ts'
 import { MemoryStore } from '../../core/store.ts'
+import type { CurationResult, CuratedMemory } from '../../types/memory.ts'
 import { homedir } from 'os'
 import { join } from 'path'
+import { readdir, stat } from 'fs/promises'
 
 type Style = Parameters<typeof styleText>[0]
 const style = (format: Style, text: string): string => styleText(format, text)
 
+// Simple spinner for long operations
+const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+class Spinner {
+  private interval: ReturnType<typeof setInterval> | null = null
+  private frameIndex = 0
+  private message = ''
+
+  start(message: string) {
+    this.message = message
+    this.frameIndex = 0
+    process.stdout.write(`        ${style('cyan', spinnerFrames[0])} ${style('dim', message)}`)
+    this.interval = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % spinnerFrames.length
+      process.stdout.write(`\r        ${style('cyan', spinnerFrames[this.frameIndex])} ${style('dim', this.message)}`)
+    }, 80)
+  }
+
+  update(message: string) {
+    this.message = message
+    process.stdout.write(`\r        ${style('cyan', spinnerFrames[this.frameIndex])} ${style('dim', this.message)}`)
+  }
+
+  stop(finalMessage?: string) {
+    if (this.interval) {
+      clearInterval(this.interval)
+      this.interval = null
+    }
+    // Clear the line and optionally write final message
+    process.stdout.write('\r' + ' '.repeat(80) + '\r')
+    if (finalMessage) {
+      console.log(finalMessage)
+    }
+  }
+}
+
 interface IngestOptions {
   project?: string
+  session?: string
   all?: boolean
   dryRun?: boolean
   verbose?: boolean
@@ -30,6 +72,71 @@ interface IngestOptions {
   maxTokens?: number
 }
 
+/**
+ * Find a specific session by ID
+ * Searches in specified project or across all projects
+ */
+async function findSessionById(
+  sessionId: string,
+  projectsFolder: string,
+  projectPath?: string
+): Promise<{ session: ParsedSession; folderId: string } | null> {
+  const filename = sessionId.endsWith('.jsonl') ? sessionId : `${sessionId}.jsonl`
+
+  // If project path is specified, search only there
+  if (projectPath) {
+    const filepath = join(projectPath, filename)
+    try {
+      await stat(filepath)
+      const session = await parseSessionFile(filepath)
+      const folderId = projectPath.split('/').pop() ?? projectPath
+      return { session, folderId }
+    } catch {
+      return null
+    }
+  }
+
+  // Search all projects
+  try {
+    const projectFolders = await readdir(projectsFolder)
+
+    for (const folder of projectFolders) {
+      const folderPath = join(projectsFolder, folder)
+      const filepath = join(folderPath, filename)
+
+      try {
+        await stat(filepath)
+        const session = await parseSessionFile(filepath)
+        return { session, folderId: folder }
+      } catch {
+        continue
+      }
+    }
+  } catch {
+    // projectsFolder doesn't exist
+  }
+
+  return null
+}
+
+/**
+ * Build storage paths for the manager (mirrors engine.getStoragePaths)
+ */
+function buildStoragePaths(projectId: string): StoragePaths {
+  const globalPath = join(homedir(), '.local', 'share', 'memory', 'global')
+  const centralPath = join(homedir(), '.local', 'share', 'memory')
+  const projectPath = join(centralPath, projectId)
+
+  return {
+    projectPath,
+    globalPath,
+    projectMemoriesPath: join(projectPath, 'memories'),
+    globalMemoriesPath: join(globalPath, 'memories'),
+    personalPrimerPath: join(globalPath, 'primer', 'personal-primer.md'),
+    storageMode: 'central',
+  }
+}
+
 export async function ingest(options: IngestOptions) {
   logger.setVerbose(options.verbose ?? false)
 
@@ -40,18 +147,8 @@ export async function ingest(options: IngestOptions) {
   console.log(style(['bold', 'magenta'], '└──────────────────────────────────────────────────────────┘'))
   console.log()
 
-  // Check for API key
-  const apiKey = process.env.ANTHROPIC_API_KEY
-  if (!apiKey && !options.dryRun) {
-    logger.error('ANTHROPIC_API_KEY not set')
-    console.log()
-    console.log(style('dim', '   Set your API key to use SDK curation:'))
-    console.log(style('dim', '   export ANTHROPIC_API_KEY=sk-...'))
-    console.log()
-    console.log(style('dim', '   Or use --dry-run to see what would be ingested'))
-    console.log()
-    process.exit(1)
-  }
+  // Agent SDK uses Claude Code OAuth - no API key needed!
+  // Just need Claude Code installed and authenticated
 
   const projectsFolder = join(homedir(), '.claude', 'projects')
   const maxTokens = options.maxTokens ?? 150000
@@ -59,7 +156,35 @@ export async function ingest(options: IngestOptions) {
   // Find sessions to ingest
   let projects: ParsedProject[] = []
 
-  if (options.project) {
+  if (options.session) {
+    // Find specific session by ID
+    const projectPath = options.project ? join(projectsFolder, options.project) : undefined
+    const result = await findSessionById(options.session, projectsFolder, projectPath)
+
+    if (!result) {
+      logger.error(`Session not found: ${options.session}`)
+      console.log()
+      if (options.project) {
+        console.log(style('dim', `   Searched in: ${projectPath}`))
+      } else {
+        console.log(style('dim', `   Searched in: ${projectsFolder}`))
+        console.log(style('dim', '   Tip: Use --project <name> to specify the project folder'))
+      }
+      console.log()
+      process.exit(1)
+    }
+
+    projects = [{
+      folderId: result.folderId,
+      name: result.session.projectName,
+      path: join(projectsFolder, result.folderId),
+      sessions: [result.session]
+    }]
+
+    logger.info(`Found session in project: ${result.session.projectName}`)
+    console.log(`      ${style('dim', 'path:')} ${result.session.filepath}`)
+    console.log()
+  } else if (options.project) {
     // Find specific project
     const projectPath = join(projectsFolder, options.project)
     const sessions = await findProjectSessions(projectPath, { limit: options.limit })
@@ -86,9 +211,11 @@ export async function ingest(options: IngestOptions) {
       process.exit(1)
     }
   } else {
-    logger.error('Specify --project <name> or --all')
+    logger.error('Specify --session <id>, --project <name>, or --all')
     console.log()
     console.log(style('dim', '   Examples:'))
+    console.log(style('dim', '     memory ingest --session abc123-def456'))
+    console.log(style('dim', '     memory ingest --session abc123-def456 --project my-project'))
     console.log(style('dim', '     memory ingest --project my-project'))
     console.log(style('dim', '     memory ingest --all'))
     console.log(style('dim', '     memory ingest --all --dry-run'))
@@ -137,21 +264,33 @@ export async function ingest(options: IngestOptions) {
     return
   }
 
-  // Initialize curator and store
-  const curator = new Curator({ apiKey })
+  // Initialize curator, manager, and store
+  // Curator uses Agent SDK (no API key needed - uses Claude Code OAuth)
+  const curator = new Curator()
+  const manager = new Manager()
   const store = new MemoryStore()
 
+  // Check if manager is enabled
+  const managerEnabled = process.env.MEMORY_MANAGER_DISABLED !== '1'
+
   logger.divider()
   logger.info('Starting ingestion...')
+  if (managerEnabled) {
+    console.log(`      ${style('dim', 'manager:')} enabled (will organize memories after each session)`)
+  }
   console.log()
 
   let totalSegments = 0
   let totalMemories = 0
   let failedSegments = 0
+  let managedSessions = 0
 
   for (const project of projects) {
     console.log(`   ${style('cyan', '📁')} ${style('bold', project.name)}`)
 
+    // Build storage paths for manager (same for all sessions in project)
+    const storagePaths = buildStoragePaths(project.folderId)
+
     for (const session of project.sessions) {
       const summary = getSessionSummary(session)
       const truncated = summary.length > 45 ? summary.slice(0, 42) + '...' : summary
@@ -164,29 +303,88 @@ export async function ingest(options: IngestOptions) {
       const segments = await parseSessionFileWithSegments(session.filepath, maxTokens)
       totalSegments += segments.length
 
+      // Accumulate all memories from this session for manager
+      const sessionMemories: CuratedMemory[] = []
+      let sessionSummary = ''
+
+      const spinner = new Spinner()
+
       for (const segment of segments) {
         try {
-          if (options.verbose) {
-            console.log(`        ${style('dim', `→ Segment ${segment.segmentIndex + 1}/${segment.totalSegments} (${segment.estimatedTokens} tokens)`)}`)
-          }
+          const segmentLabel = `Segment ${segment.segmentIndex + 1}/${segment.totalSegments}`
+          const tokensLabel = `${Math.round(segment.estimatedTokens / 1000)}k tokens`
+
+          // Start spinner for curation
+          spinner.start(`${segmentLabel} (${tokensLabel}) - curating with Opus 4.5...`)
 
           // Curate the segment
           const result = await curator.curateFromSegment(segment, 'historical')
 
+          // Stop spinner with success message
+          spinner.stop(`        ${style('green', '✓')} ${segmentLabel}: ${result.memories.length} memories (${tokensLabel})`)
+
           // Store memories
           for (const memory of result.memories) {
             await store.storeMemory(project.folderId, session.id, memory)
+            sessionMemories.push(memory)
             totalMemories++
           }
 
-          if (options.verbose && result.memories.length > 0) {
-            console.log(`        ${style('green', '✓')} Extracted ${result.memories.length} memories`)
+          // Keep the most recent session summary
+          if (result.session_summary) {
+            sessionSummary = result.session_summary
           }
         } catch (error: any) {
           failedSegments++
-          if (options.verbose) {
-            console.log(`        ${style('red', '✗')} Failed: ${error.message}`)
+          spinner.stop(`        ${style('red', '✗')} Segment ${segment.segmentIndex + 1}/${segment.totalSegments}: ${error.message}`)
+        }
+      }
+
+      // Run manager if we have memories and manager is enabled
+      if (sessionMemories.length > 0 && managerEnabled) {
+        try {
+          // Start spinner for manager
+          spinner.start(`Managing ${sessionMemories.length} memories - organizing with Opus 4.5...`)
+
+          // Build curation result for manager
+          const curationResult: CurationResult = {
+            memories: sessionMemories,
+            session_summary: sessionSummary,
+            project_snapshot: undefined,
+          }
+
+          const managerResult = await manager.manageWithSDK(
+            project.folderId,
+            1, // session number not relevant for historical ingestion
+            curationResult,
+            storagePaths
+          )
+
+          if (managerResult.success) {
+            managedSessions++
+
+            // Build detailed action summary
+            const actions: string[] = []
+            if (managerResult.superseded > 0) actions.push(`${style('yellow', String(managerResult.superseded))} superseded`)
+            if (managerResult.resolved > 0) actions.push(`${style('blue', String(managerResult.resolved))} resolved`)
+            if (managerResult.linked > 0) actions.push(`${style('cyan', String(managerResult.linked))} linked`)
+            if (managerResult.primerUpdated) actions.push(`${style('magenta', 'primer')} updated`)
+
+            if (actions.length > 0) {
+              spinner.stop(`        ${style('green', '✓')} Manager: ${actions.join(', ')}`)
+            } else {
+              spinner.stop(`        ${style('green', '✓')} Manager: no changes needed`)
+            }
+
+            // Show file operations in verbose mode
+            if (options.verbose && (managerResult.filesRead > 0 || managerResult.filesWritten > 0)) {
+              console.log(`          ${style('dim', `files: ${managerResult.filesRead} read, ${managerResult.filesWritten} written`)}`)
+            }
+          } else {
+            spinner.stop(`        ${style('yellow', '⚠')} Manager: ${managerResult.error || 'unknown error'}`)
           }
+        } catch (error: any) {
+          spinner.stop(`        ${style('yellow', '⚠')} Manager failed: ${error.message}`)
         }
       }
     }
@@ -200,6 +398,9 @@ export async function ingest(options: IngestOptions) {
   logger.info('Ingestion complete')
   console.log(`      ${style('dim', 'segments:')} ${totalSegments}`)
   console.log(`      ${style('dim', 'memories:')} ${style('green', String(totalMemories))}`)
+  if (managerEnabled && managedSessions > 0) {
+    console.log(`      ${style('dim', 'managed:')} ${managedSessions} sessions`)
+  }
   if (failedSegments > 0) {
     console.log(`      ${style('dim', 'failed:')} ${style('yellow', String(failedSegments))}`)
   }
@@ -207,6 +408,9 @@ export async function ingest(options: IngestOptions) {
 
   if (totalMemories > 0) {
     logger.success(`Extracted ${totalMemories} memories from ${totalSegments} segments`)
+    if (managerEnabled && managedSessions > 0) {
+      console.log(`      ${style('dim', 'Manager organized memories in')} ${managedSessions} ${style('dim', 'sessions')}`)
+    }
   } else {
     logger.warn('No memories extracted. Try --verbose to see details.')
   }

package/src/cli/index.ts

@@ -23,7 +23,7 @@ ${c.bold('Commands:')}
   ${c.command('serve')}      Start the memory server ${c.muted('(default)')}
   ${c.command('stats')}      Show memory statistics
   ${c.command('install')}    Set up hooks ${c.muted('(--claude or --gemini)')}
-  ${c.command('ingest')}     Ingest historical sessions into memory ${c.muted('(--project or --all)')}
+  ${c.command('ingest')}     Ingest historical sessions into memory ${c.muted('(--session, --project, or --all)')}
   ${c.command('migrate')}    Upgrade memories to latest schema version
   ${c.command('doctor')}     Check system health
   ${c.command('help')}       Show this help message
@@ -32,8 +32,9 @@ ${c.bold('Options:')}
   ${c.cyan('-p, --port')} <port>    Server port ${c.muted('(default: 8765)')}
   ${c.cyan('-v, --verbose')}        Verbose output
   ${c.cyan('-q, --quiet')}          Minimal output
-  ${c.cyan('--dry-run')}            Preview changes without applying ${c.muted('(migrate)')}
+  ${c.cyan('--dry-run')}            Preview changes without applying ${c.muted('(migrate, ingest)')}
   ${c.cyan('--embeddings')}         Regenerate embeddings for memories ${c.muted('(migrate)')}
+  ${c.cyan('--session')} <id>       Ingest a specific session by ID ${c.muted('(ingest)')}
   ${c.cyan('--claude')}             Install hooks for Claude Code
   ${c.cyan('--gemini')}             Install hooks for Gemini CLI
   ${c.cyan('--version')}            Show version
@@ -44,7 +45,8 @@ ${fmt.cmd('memory serve --port 9000')}  ${c.muted('# Start on custom port')}
 ${fmt.cmd('memory stats')}              ${c.muted('# Show memory statistics')}
 ${fmt.cmd('memory install')}            ${c.muted('# Install Claude Code hooks (default)')}
 ${fmt.cmd('memory install --gemini')}   ${c.muted('# Install Gemini CLI hooks')}
-${fmt.cmd('memory ingest --project foo')}  ${c.muted('# Ingest sessions from a project')}
+${fmt.cmd('memory ingest --session abc123')}  ${c.muted('# Ingest a specific session')}
+${fmt.cmd('memory ingest --project foo')}  ${c.muted('# Ingest all sessions from a project')}
 ${fmt.cmd('memory ingest --all --dry-run')}  ${c.muted('# Preview all sessions to ingest')}
 ${fmt.cmd('memory migrate')}            ${c.muted('# Upgrade memories to v2 schema')}
 ${fmt.cmd('memory migrate --dry-run')}  ${c.muted('# Preview migration without changes')}
@@ -78,6 +80,7 @@ async function main() {
       'dry-run': { type: 'boolean', default: false },
       embeddings: { type: 'boolean', default: false },  // Regenerate embeddings in migrate
       path: { type: 'string' },  // Custom path for migrate
+      session: { type: 'string' },  // Session ID to ingest
       project: { type: 'string' },  // Project to ingest
       all: { type: 'boolean', default: false },  // Ingest all projects
       limit: { type: 'string' },  // Limit sessions per project
@@ -146,6 +149,7 @@ async function main() {
     case 'ingest': {
       const { ingest } = await import('./commands/ingest.ts')
       await ingest({
+        session: values.session,
         project: values.project,
         all: values.all,
         dryRun: values['dry-run'],

package/src/core/curator.ts

@@ -10,7 +10,7 @@ import type { CuratedMemory, CurationResult, CurationTrigger } from '../types/me
 
 /**
  * Get the correct Claude CLI command path
- * Matches Python's get_claude_command() logic
+ * Uses `which` for universal discovery across installation methods
  */
 function getClaudeCommand(): string {
   // 1. Check for explicit override
@@ -19,13 +19,19 @@ function getClaudeCommand(): string {
     return envCommand
   }
 
-  // 2. Check standard Claude Code installation path
+  // 2. Use `which` to find claude in PATH (universal - works with native, homebrew, npm, etc.)
+  const result = Bun.spawnSync(['which', 'claude'])
+  if (result.exitCode === 0) {
+    return result.stdout.toString().trim()
+  }
+
+  // 3. Legacy fallback - hardcoded native install path
   const claudeLocal = join(homedir(), '.claude', 'local', 'claude')
   if (existsSync(claudeLocal)) {
     return claudeLocal
   }
 
-  // 3. Fallback to PATH
+  // 4. Last resort - assume it's in PATH
   return 'claude'
 }
 
@@ -392,15 +398,107 @@ Focus ONLY on technical, architectural, debugging, decision, workflow, and proje
   }
 
   /**
-   * Curate using Anthropic SDK with parsed session messages
+   * Curate using Claude Agent SDK (no API key needed - uses Claude Code OAuth)
    * Takes the actual conversation messages in API format
    */
   async curateWithSDK(
     messages: Array<{ role: 'user' | 'assistant'; content: string | any[] }>,
     triggerType: CurationTrigger = 'session_end'
+  ): Promise<CurationResult> {
+    // Dynamic import to make Agent SDK optional
+    const { query } = await import('@anthropic-ai/claude-agent-sdk')
+
+    const systemPrompt = this.buildCurationPrompt(triggerType)
+
+    // Format the conversation as a readable transcript for the prompt
+    const transcript = this._formatConversationTranscript(messages)
+
+    // Build the prompt with transcript + curation request
+    const prompt = `Here is the conversation transcript to curate:
+
+${transcript}
+
+---
+
+This session has ended. Please curate the memories from this conversation according to your system instructions. Return ONLY the JSON structure with no additional text.`
+
+    // Use Agent SDK - no API key needed, uses Claude Code OAuth
+    const q = query({
+      prompt,
+      options: {
+        systemPrompt,
+        permissionMode: 'bypassPermissions',
+        maxTurns: 1,
+        model: 'claude-opus-4-5-20251101',
+      },
+    })
+
+    // Iterate through the async generator to get the result
+    let resultText = ''
+    for await (const msg of q) {
+      if (msg.type === 'result' && 'result' in msg) {
+        resultText = msg.result
+        break
+      }
+    }
+
+    if (!resultText) {
+      return { session_summary: '', memories: [] }
+    }
+
+    return this.parseCurationResponse(resultText)
+  }
+
+  /**
+   * Format conversation messages into a readable transcript
+   */
+  private _formatConversationTranscript(
+    messages: Array<{ role: 'user' | 'assistant'; content: string | any[] }>
+  ): string {
+    const lines: string[] = []
+
+    for (const msg of messages) {
+      const role = msg.role === 'user' ? 'User' : 'Assistant'
+      let content: string
+
+      if (typeof msg.content === 'string') {
+        content = msg.content
+      } else if (Array.isArray(msg.content)) {
+        // Extract text from content blocks
+        content = msg.content
+          .filter((block: any) => block.type === 'text' && block.text)
+          .map((block: any) => block.text)
+          .join('\n')
+
+        // Also note tool uses (but don't include full details)
+        const toolUses = msg.content.filter((block: any) => block.type === 'tool_use')
+        if (toolUses.length > 0) {
+          const toolNames = toolUses.map((t: any) => t.name).join(', ')
+          content += `\n[Used tools: ${toolNames}]`
+        }
+      } else {
+        content = '[empty message]'
+      }
+
+      if (content.trim()) {
+        lines.push(`**${role}:**\n${content}\n`)
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Legacy method: Curate using Anthropic SDK with API key
+   * Kept for backwards compatibility
+   * @deprecated Use curateWithSDK() which uses Agent SDK (no API key needed)
+   */
+  async curateWithAnthropicSDK(
+    messages: Array<{ role: 'user' | 'assistant'; content: string | any[] }>,
+    triggerType: CurationTrigger = 'session_end'
   ): Promise<CurationResult> {
     if (!this._config.apiKey) {
-      throw new Error('API key required for SDK mode. Set ANTHROPIC_API_KEY environment variable.')
+      throw new Error('API key required for Anthropic SDK mode. Set ANTHROPIC_API_KEY environment variable.')
     }
 
     // Dynamic import to make SDK optional

package/src/core/manager.ts

@@ -11,15 +11,24 @@ import type { CurationResult } from '../types/memory.ts'
 
 /**
  * Get the Claude CLI command path
- * Same logic as curator.ts
+ * Uses `which` for universal discovery across installation methods
  */
 function getClaudeCommand(): string {
+  // 1. Check for explicit override
   const envCommand = process.env.CURATOR_COMMAND
   if (envCommand) return envCommand
 
+  // 2. Use `which` to find claude in PATH (universal - works with native, homebrew, npm, etc.)
+  const result = Bun.spawnSync(['which', 'claude'])
+  if (result.exitCode === 0) {
+    return result.stdout.toString().trim()
+  }
+
+  // 3. Legacy fallback - hardcoded native install path
   const claudeLocal = join(homedir(), '.claude', 'local', 'claude')
   if (existsSync(claudeLocal)) return claudeLocal
 
+  // 4. Last resort
   return 'claude'
 }
 
@@ -374,7 +383,135 @@ Please process these memories according to your management procedure. Use the ex
   }
 
   /**
-   * Manage using CLI subprocess
+   * Manage using Claude Agent SDK (no API key needed - uses Claude Code OAuth)
+   * Use this for ingest command - cleaner than CLI subprocess
+   */
+  async manageWithSDK(
+    projectId: string,
+    sessionNumber: number,
+    result: CurationResult,
+    storagePaths?: StoragePaths
+  ): Promise<ManagementResult> {
+    // Skip if disabled via config or env var
+    if (!this._config.enabled || process.env.MEMORY_MANAGER_DISABLED === '1') {
+      return {
+        success: true,
+        superseded: 0,
+        resolved: 0,
+        linked: 0,
+        filesRead: 0,
+        filesWritten: 0,
+        primerUpdated: false,
+        actions: [],
+        summary: 'Management agent disabled',
+        fullReport: 'Management agent disabled via configuration',
+      }
+    }
+
+    // Skip if no memories
+    if (result.memories.length === 0) {
+      return {
+        success: true,
+        superseded: 0,
+        resolved: 0,
+        linked: 0,
+        filesRead: 0,
+        filesWritten: 0,
+        primerUpdated: false,
+        actions: [],
+        summary: 'No memories to process',
+        fullReport: 'No memories to process - skipped',
+      }
+    }
+
+    // Load skill file
+    const systemPrompt = await this.buildManagementPrompt()
+    if (!systemPrompt) {
+      return {
+        success: false,
+        superseded: 0,
+        resolved: 0,
+        linked: 0,
+        filesRead: 0,
+        filesWritten: 0,
+        primerUpdated: false,
+        actions: [],
+        summary: '',
+        fullReport: 'Error: Management skill file not found',
+        error: 'Management skill not found',
+      }
+    }
+
+    const userMessage = this.buildUserMessage(projectId, sessionNumber, result, storagePaths)
+
+    try {
+      // Dynamic import to make Agent SDK optional
+      const { query } = await import('@anthropic-ai/claude-agent-sdk')
+
+      // Build allowed directories for file access
+      const globalPath = storagePaths?.globalPath ?? join(homedir(), '.local', 'share', 'memory', 'global')
+      const projectPath = storagePaths?.projectPath ?? join(homedir(), '.local', 'share', 'memory')
+
+      // Use Agent SDK with file tools
+      const q = query({
+        prompt: userMessage,
+        options: {
+          systemPrompt,
+          permissionMode: 'bypassPermissions',
+          model: 'claude-opus-4-5-20251101',
+          // Only allow file tools - no Bash, no web
+          allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
+          // Allow access to memory directories
+          additionalDirectories: [globalPath, projectPath],
+          // Limit turns if configured
+          maxTurns: this._config.maxTurns,
+        },
+      })
+
+      // Iterate through the async generator to get the result
+      let resultText = ''
+      for await (const msg of q) {
+        if (msg.type === 'result' && 'result' in msg) {
+          resultText = msg.result
+          break
+        }
+      }
+
+      if (!resultText) {
+        return {
+          success: true,
+          superseded: 0,
+          resolved: 0,
+          linked: 0,
+          filesRead: 0,
+          filesWritten: 0,
+          primerUpdated: false,
+          actions: [],
+          summary: 'No result from management agent',
+          fullReport: 'Management agent completed but returned no result',
+        }
+      }
+
+      return this._parseSDKManagementResult(resultText)
+    } catch (error: any) {
+      return {
+        success: false,
+        superseded: 0,
+        resolved: 0,
+        linked: 0,
+        filesRead: 0,
+        filesWritten: 0,
+        primerUpdated: false,
+        actions: [],
+        summary: '',
+        fullReport: `Error: Agent SDK failed: ${error.message}`,
+        error: error.message,
+      }
+    }
+  }
+
+  /**
+   * Manage using CLI subprocess (for hooks - keeps working while we migrate)
    * Similar to Curator.curateWithCLI
    */
   async manageWithCLI(
@@ -487,6 +624,52 @@ Please process these memories according to your management procedure. Use the ex
 
     return this.parseManagementResponse(stdout)
   }
+
+  /**
+   * Parse management result from Agent SDK response
+   * Similar to parseManagementResponse but for SDK output format
+   */
+  private _parseSDKManagementResult(resultText: string): ManagementResult {
+    // Extract actions section
+    const actionsMatch = resultText.match(/=== MANAGEMENT ACTIONS ===([\s\S]*?)(?:=== SUMMARY ===|$)/)
+    const actions: string[] = []
+    if (actionsMatch) {
+      const actionsText = actionsMatch[1]
+      const actionLines = actionsText.split('\n')
+        .map((line: string) => line.trim())
+        .filter((line: string) => /^(READ|WRITE|RECEIVED|CREATED|UPDATED|SUPERSEDED|RESOLVED|LINKED|PRIMER|SKIPPED|NO_ACTION)/.test(line))
+      actions.push(...actionLines)
+    }
+
+    // Extract the full report
+    const reportMatch = resultText.match(/(=== MANAGEMENT ACTIONS ===[\s\S]*)/)
+    const fullReport = reportMatch ? reportMatch[1].trim() : resultText
+
+    // Extract stats from result text
+    const supersededMatch = resultText.match(/memories_superseded[:\s]+(\d+)/i) || resultText.match(/superseded[:\s]+(\d+)/i)
+    const resolvedMatch = resultText.match(/memories_resolved[:\s]+(\d+)/i) || resultText.match(/resolved[:\s]+(\d+)/i)
+    const linkedMatch = resultText.match(/memories_linked[:\s]+(\d+)/i) || resultText.match(/linked[:\s]+(\d+)/i)
+    const filesReadMatch = resultText.match(/files_read[:\s]+(\d+)/i)
+    const filesWrittenMatch = resultText.match(/files_written[:\s]+(\d+)/i)
+    const primerUpdated = /primer_updated[:\s]+true/i.test(resultText) || /PRIMER\s+OK/i.test(resultText)
+
+    // Count file operations from actions if not in summary
+    const readActions = actions.filter((a: string) => a.startsWith('READ OK')).length
+    const writeActions = actions.filter((a: string) => a.startsWith('WRITE OK')).length
+
+    return {
+      success: true,
+      superseded: supersededMatch ? parseInt(supersededMatch[1]) : 0,
+      resolved: resolvedMatch ? parseInt(resolvedMatch[1]) : 0,
+      linked: linkedMatch ? parseInt(linkedMatch[1]) : 0,
+      filesRead: filesReadMatch ? parseInt(filesReadMatch[1]) : readActions,
+      filesWritten: filesWrittenMatch ? parseInt(filesWrittenMatch[1]) : writeActions,
+      primerUpdated,
+      actions,
+      summary: resultText.slice(0, 500),
+      fullReport,
+    }
+  }
 }
 
 /**

package/src/core/retrieval.ts

@@ -260,7 +260,7 @@ export class SmartVectorRetrieval {
     const min = Math.min(...samples)
     const max = Math.max(...samples)
     const avg = samples.reduce((a, b) => a + b, 0) / samples.length
-    console.log(`[DEBUG] Vector similarities: min=${(min*100).toFixed(1)}% max=${(max*100).toFixed(1)}% avg=${(avg*100).toFixed(1)}% (${samples.length} samples)`)
+    logger.debug(`Vector similarities: min=${(min*100).toFixed(1)}% max=${(max*100).toFixed(1)}% avg=${(avg*100).toFixed(1)}% (${samples.length} samples)`, 'retrieval')
     this._vectorDebugSamples = []  // Reset for next retrieval
   }
 
@@ -516,11 +516,13 @@ export class SmartVectorRetrieval {
     })
 
     // Debug: show top 15 candidates with calculated scores
-    console.log(`[DEBUG] Top 15 candidates (sorted):`)
-    for (let i = 0; i < Math.min(15, projectsSorted.length); i++) {
-      const m = projectsSorted[i]
-      const action = m.memory.action_required ? '⚡' : ''
-      console.log(`  ${i+1}. [${m.signals.count}sig] score=${m.importanceScore.toFixed(2)} ${action} ${m.memory.content.slice(0, 45)}...`)
+    if (logger.isVerbose()) {
+      logger.debug(`Top 15 candidates (sorted):`, 'retrieval')
+      for (let i = 0; i < Math.min(15, projectsSorted.length); i++) {
+        const m = projectsSorted[i]
+        const action = m.memory.action_required ? '⚡' : ''
+        logger.debug(`  ${i+1}. [${m.signals.count}sig] score=${m.importanceScore.toFixed(2)} ${action} ${m.memory.content.slice(0, 45)}...`, 'retrieval')
+      }
     }
 
     for (const item of projectsSorted) {

package/src/core/store.ts

@@ -6,6 +6,7 @@
 import { createDatabase, type Database, type PersistentCollection } from '@rlabs-inc/fsdb'
 import { homedir } from 'os'
 import { join } from 'path'
+import { logger } from '../utils/logger.ts'
 import {
   type CuratedMemory,
   type StoredMemory,
@@ -126,7 +127,7 @@ export class MemoryStore {
 
     // Use the configured global path (always central)
     const globalPath = this._config.globalPath
-    console.log(`🌐 [DEBUG] Initializing global database at ${globalPath}`)
+    logger.debug(`Initializing global database at ${globalPath}`, 'store')
 
     const db = createDatabase({
       name: 'global',
@@ -414,13 +415,13 @@ export class MemoryStore {
    */
   async getProject(projectId: string): Promise<ProjectDB> {
     if (this._projects.has(projectId)) {
-      console.log(`🔄 [DEBUG] Returning cached databases for ${projectId}`)
+      logger.debug(`Returning cached databases for ${projectId}`, 'store')
       return this._projects.get(projectId)!
     }
 
-    console.log(`🆕 [DEBUG] Creating NEW databases for ${projectId}`)
+    logger.debug(`Creating NEW databases for ${projectId}`, 'store')
     const projectPath = join(this._config.basePath, projectId)
-    console.log(`   Path: ${projectPath}`)
+    logger.debug(`Path: ${projectPath}`, 'store')
 
     // Create the database for this project
     const db = createDatabase({
@@ -743,9 +744,7 @@ export class MemoryStore {
   ): Promise<string> {
     const { summaries } = await this.getProject(projectId)
 
-    console.log(`📝 [DEBUG] Storing summary for ${projectId}:`)
-    console.log(`   Summary length: ${summary.length} chars`)
-    console.log(`   Summaries count before: ${summaries.all().length}`)
+    logger.debug(`Storing summary for ${projectId}: ${summary.length} chars`, 'store')
 
     const id = summaries.insert({
       session_id: sessionId,
@@ -754,8 +753,7 @@ export class MemoryStore {
       interaction_tone: interactionTone,
     })
 
-    console.log(`   Summaries count after: ${summaries.all().length}`)
-    console.log(`   Inserted ID: ${id}`)
+    logger.debug(`Summary stored with ID: ${id}`, 'store')
 
     return id
   }
@@ -766,14 +764,14 @@ export class MemoryStore {
   async getLatestSummary(projectId: string): Promise<SessionSummary | null> {
     const { summaries } = await this.getProject(projectId)
 
-    console.log(`📖 [DEBUG] Getting latest summary for ${projectId}:`)
+    logger.debug(`Getting latest summary for ${projectId}`, 'store')
     const all = summaries.all()
-    console.log(`   Summaries found: ${all.length}`)
 
     if (!all.length) {
-      console.log(`   No summaries found!`)
+      logger.debug(`No summaries found for ${projectId}`, 'store')
       return null
     }
+    logger.debug(`Found ${all.length} summaries for ${projectId}`, 'store')
 
     // Sort by created timestamp (most recent first)
     const sorted = [...all].sort((a, b) => b.created - a.created)

package/src/types/memory.ts

@@ -67,6 +67,7 @@ export type CurationTrigger =
   | 'pre_compact'       // Before context compression
   | 'context_full'      // Context window nearly full
   | 'manual'            // Manual trigger
+  | 'historical'        // Historical session ingestion
 
 /**
  * A memory curated by Claude with semantic understanding

package/src/utils/logger.ts

@@ -64,6 +64,16 @@ export const logger = {
     return _verbose
   },
 
+  /**
+   * Debug message (only shown in verbose mode)
+   */
+  debug(message: string, prefix?: string) {
+    if (_verbose) {
+      const pfx = prefix ? style('dim', `[${prefix}] `) : ''
+      console.log(`${style('dim', `🔍 ${pfx}${message}`)}`)
+    }
+  },
+
   /**
    * Info message
    */