Refactor Ralph session tracking with KV-backed session mapping and configurable TTL (#172)

* Fix Ralph state type safety and null handling in status commands

* Refactor Ralph to use worktree-keyed session mapping instead of sessionId lookups

* Add configurable KV TTL with 7-day default and update agent prompts

* Add --limit flag to CLI status and improve null safety for RalphState fields

* Bump memory package version to 0.0.25

Author: chriswritescode-dev

backend/src/routes/memory.ts

@@ -576,10 +576,10 @@ export function createMemoryRoutes(db: Database): Hono {
   app.post('/ralph/cancel', async (c) => {
     try {
       const body = await c.req.json()
-      const { repoId, sessionId } = body
+      const { repoId, worktreeName, sessionId } = body
 
-      if (!repoId || !sessionId) {
-        return c.json({ error: 'Missing repoId or sessionId' }, 400)
+      if (!repoId || (!worktreeName && !sessionId)) {
+        return c.json({ error: 'Missing repoId or identifier (worktreeName or sessionId)' }, 400)
       }
 
       const repo = getRepoById(db, parseInt(repoId, 10))
@@ -594,8 +594,23 @@ export function createMemoryRoutes(db: Database): Hono {
         return c.json({ cancelled: false })
       }
 
-      const kvEntry = pluginMemory.getKv(projectId, `ralph:${sessionId}`)
+      let worktreeNameToUse: string | undefined
 
+      if (worktreeName) {
+        worktreeNameToUse = worktreeName
+      } else if (sessionId) {
+        const sessionMappingEntry = pluginMemory.getKv(projectId, `ralph-session:${sessionId}`)
+        if (!sessionMappingEntry) {
+          return c.json({ cancelled: false })
+        }
+        worktreeNameToUse = sessionMappingEntry.data as string
+      }
+
+      if (!worktreeNameToUse) {
+        return c.json({ cancelled: false })
+      }
+
+      const kvEntry = pluginMemory.getKv(projectId, `ralph:${worktreeNameToUse}`)
       if (!kvEntry) {
         return c.json({ cancelled: false })
       }
@@ -620,10 +635,10 @@ export function createMemoryRoutes(db: Database): Hono {
         completedAt: new Date().toISOString(),
       }
 
-      pluginMemory.setKv(projectId, `ralph:${sessionId}`, updatedState)
+      pluginMemory.setKv(projectId, `ralph:${worktreeNameToUse}`, updatedState)
 
       try {
-        const abortUrl = new URL(`${OPENCODE_SERVER_URL}/session/${sessionId}/abort`)
+        const abortUrl = new URL(`${OPENCODE_SERVER_URL}/session/${state.sessionId}/abort`)
         abortUrl.searchParams.set('directory', repo.fullPath)
         await fetch(abortUrl.toString(), { method: 'POST' })
       } catch {

backend/test/routes/memory.test.ts

@@ -147,7 +147,7 @@ describe('Memory Routes - Ralph Status', () => {
       mockResolveProjectId.mockResolvedValue('test-project-id')
       mockListKv.mockReturnValue([
         {
-          key: 'ralph:session-123',
+          key: 'ralph:test-worktree',
           data: {
             active: true,
             sessionId: 'session-123',
@@ -194,28 +194,40 @@ describe('Memory Routes - Ralph Status', () => {
       mockResolveProjectId.mockResolvedValue('test-project-id')
       mockListKv.mockReturnValue([
         {
-          key: 'ralph:session-123',
-          data: { active: true, sessionId: 'session-123' },
+          key: 'ralph:test-worktree-1',
+          data: {
+            active: true,
+            sessionId: 'session-123',
+            worktreeName: 'test-worktree-1',
+            worktreeDir: '/tmp/test-worktree-1',
+            iteration: 1,
+            maxIterations: 10,
+            startedAt: new Date().toISOString(),
+            phase: 'coding',
+            errorCount: 0,
+            auditCount: 0,
+            completionPromise: null,
+          },
           createdAt: Date.now(),
           updatedAt: Date.now(),
           expiresAt: Date.now() + 86400000,
         },
         {
-          key: 'ralph:session-456',
+          key: 'ralph:test-worktree-2',
           data: null,
           createdAt: Date.now(),
           updatedAt: Date.now(),
           expiresAt: Date.now() + 86400000,
         },
         {
-          key: 'ralph:session-789',
+          key: 'ralph:test-worktree-3',
           data: 'string-data',
           createdAt: Date.now(),
           updatedAt: Date.now(),
           expiresAt: Date.now() + 86400000,
         },
         {
-          key: 'ralph:session-abc',
+          key: 'ralph:test-worktree-4',
           data: { sessionId: 'session-abc' },
           createdAt: Date.now(),
           updatedAt: Date.now(),

packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-manager/memory",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

packages/memory/src/agents/architect.ts

@@ -59,12 +59,12 @@ ${getInjectedMemory('architect')}
 
 ## Project KV Store
 
-You have access to a project-scoped key-value store with 24-hour TTL for ephemeral state:
+You have access to a project-scoped key-value store with 7-day TTL for ephemeral state:
 - \`memory-kv-set\`: Store planning progress, research findings, or any project state
 - \`memory-kv-get\`: Retrieve previously stored state
 - \`memory-kv-list\`: See all active entries for the project
 
-KV entries are scoped to the current project and expire after 24 hours. Use this for state that needs to survive compaction but isn't permanent enough for memory-write.
+KV entries are scoped to the current project and expire after 7 days. Use this for state that needs to survive compaction but isn't permanent enough for memory-write.
 
 ## Workflow
 

packages/memory/src/agents/auditor.ts

@@ -149,17 +149,17 @@ Example:
 
 The KV store upserts by key, so storing a finding for the same file:line automatically updates the previous entry. No dedup checks needed.
 
-When the calling agent reports that a finding has been fixed, update the finding by calling \`memory-kv-set\` with the same key and the status changed to "resolved" with a resolution date added.
+When a previously open finding has been addressed by the current changes, **delete it** using \`memory-kv-delete\` with the same key. Do not re-store resolved findings — removing them keeps the KV store clean and avoids extending the TTL on stale data.
 
-Findings expire after 24 hours automatically. If an issue persists, the next review will re-discover it.
+Findings expire after 7 days automatically. If an issue persists, the next review will re-discover it.
 
 ## Retrieving Past Findings
 
 At the start of every review, before analyzing the diff:
 1. Call \`memory-kv-list\` to get all active KV entries for the project
 2. Filter entries with keys starting with \`review-finding:\` that match files in the current diff
 3. If open findings exist for files being changed, include them under a "### Previously Identified Issues" heading before new findings
-4. Check if any previously open findings have been addressed by the current changes — if so, update their status to "resolved" via \`memory-kv-set\` with the same key
+4. Check if any previously open findings have been addressed by the current changes — if so, delete them via \`memory-kv-delete\` with the same key
 
 ${getInjectedMemory('auditor')}
 `,

packages/memory/src/agents/code.ts

@@ -79,11 +79,11 @@ You are the execution agent. Your job is to write code, not describe code.
 
 ## Project KV Store
 
-You have access to a project-scoped key-value store with 24-hour TTL for ephemeral state:
+You have access to a project-scoped key-value store with 7-day TTL for ephemeral state:
 - \`memory-kv-set\`: Store ephemeral findings, planning progress, or session state
 - \`memory-kv-get\`: Retrieve previously stored state
 - \`memory-kv-list\`: See all active entries for the project
 
-KV entries are scoped to the current project and expire after 24 hours. Use this for state that needs to survive compaction but isn't permanent enough for memory-write.
+KV entries are scoped to the current project and expire after 7 days. Use this for state that needs to survive compaction but isn't permanent enough for memory-write.
 `,
 }

packages/memory/src/cli/commands/status.ts

@@ -23,6 +23,7 @@ export interface StatusArgs {
   server?: string
   listWorktrees?: boolean
   listWorktreesFilter?: string
+  limit?: number
 }
 
 export async function run(argv: StatusArgs): Promise<void> {
@@ -83,7 +84,7 @@ export async function run(argv: StatusArgs): Promise<void> {
     for (const row of rows) {
       try {
         const state = JSON.parse(row.data) as RalphState
-        if (state.active) {
+        if (state.active && state.sessionId && state.worktreeName && state.iteration != null && state.maxIterations != null && state.phase && state.startedAt) {
           activeLoops.push({
             sessionId: state.sessionId,
             worktreeName: state.worktreeName,
@@ -92,7 +93,7 @@ export async function run(argv: StatusArgs): Promise<void> {
             maxIterations: state.maxIterations,
             phase: state.phase,
             startedAt: state.startedAt,
-            audit: state.audit,
+            audit: state.audit ?? false,
           })
         } else if (state.completedAt) {
           recentLoops.push({ state, row })
@@ -164,7 +165,8 @@ export async function run(argv: StatusArgs): Promise<void> {
         }
 
         const state = JSON.parse(row.data) as RalphState
-        const duration = Date.now() - new Date(state.startedAt).getTime()
+        const startedAt = state.startedAt!
+        const duration = Date.now() - new Date(startedAt).getTime()
         const hours = Math.floor(duration / (1000 * 60 * 60))
         const minutes = Math.floor((duration % (1000 * 60 * 60)) / (1000 * 60))
         const seconds = Math.floor((duration % (1000 * 60)) / 1000)
@@ -184,9 +186,9 @@ export async function run(argv: StatusArgs): Promise<void> {
         console.log(`  Iteration:       ${state.iteration}/${state.maxIterations}`)
         console.log(`  Duration:        ${hours}h ${minutes}m ${seconds}s`)
         console.log(`  Audit:           ${state.audit ? 'Yes' : 'No'}`)
-        console.log(`  Error Count:     ${state.errorCount}`)
-        console.log(`  Audit Count:     ${state.auditCount}`)
-        console.log(`  Started:         ${new Date(state.startedAt).toISOString()}`)
+        console.log(`  Error Count:     ${state.errorCount ?? 0}`)
+        console.log(`  Audit Count:     ${state.auditCount ?? 0}`)
+        console.log(`  Started:         ${new Date(startedAt).toISOString()}`)
         if (state.completionPromise) {
           console.log(`  Completion:      ${state.completionPromise}`)
         }
@@ -196,7 +198,7 @@ export async function run(argv: StatusArgs): Promise<void> {
           }
         }
 
-        const sessionOutput = await tryFetchSessionOutput(argv.server ?? 'http://localhost:5551', state.sessionId, state.worktreeDir)
+        const sessionOutput = await tryFetchSessionOutput(argv.server ?? 'http://localhost:5551', state.sessionId, state.worktreeDir!)
         if (sessionOutput) {
           console.log('Session Output:')
           for (const line of formatSessionOutput(sessionOutput)) {
@@ -207,7 +209,8 @@ export async function run(argv: StatusArgs): Promise<void> {
       } else {
         const state = matchedLoop.loop.state
         const completedAt = state.completedAt!
-        const duration = new Date(completedAt).getTime() - new Date(state.startedAt).getTime()
+        const startedAt = state.startedAt!
+        const duration = new Date(completedAt).getTime() - new Date(startedAt).getTime()
         const hours = Math.floor(duration / (1000 * 60 * 60))
         const minutes = Math.floor((duration % (1000 * 60 * 60)) / (1000 * 60))
         const seconds = Math.floor((duration % (1000 * 60)) / 1000)
@@ -226,15 +229,15 @@ export async function run(argv: StatusArgs): Promise<void> {
         console.log(`  Iteration:       ${state.iteration}/${state.maxIterations}`)
         console.log(`  Duration:        ${hours}h ${minutes}m ${seconds}s`)
         console.log(`  Reason:          ${state.terminationReason ?? 'unknown'}`)
-        console.log(`  Started:         ${new Date(state.startedAt).toISOString()}`)
+        console.log(`  Started:         ${new Date(startedAt).toISOString()}`)
         console.log(`  Completed:       ${new Date(completedAt).toISOString()}`)
         if (state.lastAuditResult) {
           for (const line of formatAuditResult(state.lastAuditResult)) {
             console.log(line)
           }
         }
 
-        const sessionOutput = await tryFetchSessionOutput(argv.server ?? 'http://localhost:5551', state.sessionId, state.worktreeDir)
+        const sessionOutput = await tryFetchSessionOutput(argv.server ?? 'http://localhost:5551', state.sessionId, state.worktreeDir!)
         if (sessionOutput) {
           console.log('Session Output:')
           for (const line of formatSessionOutput(sessionOutput)) {
@@ -270,14 +273,21 @@ export async function run(argv: StatusArgs): Promise<void> {
         console.log('Recently Completed:')
         console.log('')
 
-        for (const loop of recentLoops) {
+        const limit = argv.limit ?? 10
+        const displayedLoops = recentLoops.slice(0, limit)
+        for (const loop of displayedLoops) {
           const reason = loop.state.terminationReason ?? 'unknown'
           const completed = new Date(loop.state.completedAt!).toLocaleString()
 
           console.log(`  ${loop.state.worktreeName}`)
           console.log(`    Iterations: ${loop.state.iteration}  Reason: ${reason}  Completed: ${completed}`)
           console.log('')
         }
+        
+        if (recentLoops.length > limit) {
+          console.log(`  ... and ${recentLoops.length - limit} more. Use 'ocm-mem status <name>' for details.`)
+          console.log('')
+        }
       }
 
       if (activeLoops.length === 0 && recentLoops.length === 0) {
@@ -309,6 +319,7 @@ Options:
   --server <url>          OpenCode server URL (default: http://localhost:5551)
   --list-worktrees        List all worktree names (for shell completion)
                           Optionally provide a filter: --list-worktrees <filter>
+  --limit <n>             Limit recent loops shown (default: 10)
   --project, -p <id>      Project ID (auto-detected from git if not provided)
   --db-path <path>        Path to memory database
   --help, -h              Show this help message
@@ -332,6 +343,8 @@ export async function cli(args: string[], globalOpts: { dbPath?: string; resolve
       if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
         argv.listWorktreesFilter = args[++i]
       }
+    } else if (arg === '--limit') {
+      argv.limit = parseInt(args[++i], 10)
     } else if (arg === '--help' || arg === '-h') {
       help()
       process.exit(0)