Fire-and-forget memory maintenance subprocess

Spawn maintenance agent as a detached `claude` CLI subprocess instead of
injecting a nudge into conversation context. Saves tokens and turns.

- Extract shared spawnClaudeSubprocess() into SubprocessSpawner.swift
- Advise hook spawns maintenance subprocess when CRUD threshold crossed
- Remove maintenanceNudge() from LatticeHelpers and all hook callers
- Refactor OnStop session-learner to use shared spawner
- Use mcp__memory__* wildcard for allowed tools
- Slack release notification now includes changelog highlights

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jsflax

.github/workflows/release.yml

@@ -243,29 +243,31 @@ jobs:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
           TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
           REPO="${{ github.repository }}"
           URL="https://github.com/${REPO}/releases/tag/${TAG}"
-          STATUS="${{ job.status }}"
-
-          if [ "$STATUS" = "success" ]; then
-            EMOJI="✅"
-            TEXT="Release *${TAG}* published successfully"
-          else
-            EMOJI="❌"
-            TEXT="Release *${TAG}* failed"
-          fi
+
+          # Extract changelog section for this version (between ## [version] and next ## [)
+          CHANGES=$(awk "/^## \\[${VERSION}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md \
+            | sed '/^$/d' \
+            | sed 's/^### /\n*/' \
+            | sed 's/^- /• /' \
+            | head -20)
+
+          # Escape for JSON
+          CHANGES_ESCAPED=$(echo "$CHANGES" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read())[1:-1])')
 
           curl -s -X POST "$SLACK_WEBHOOK_URL" \
             -H 'Content-Type: application/json' \
             -d "{
               \"blocks\": [
                 {
                   \"type\": \"header\",
-                  \"text\": {\"type\": \"plain_text\", \"text\": \"${EMOJI} Engram ${TAG}\"}
+                  \"text\": {\"type\": \"plain_text\", \"text\": \"✅ Engram ${TAG} released\"}
                 },
                 {
                   \"type\": \"section\",
-                  \"text\": {\"type\": \"mrkdwn\", \"text\": \"${TEXT}\"},
+                  \"text\": {\"type\": \"mrkdwn\", \"text\": \"${CHANGES_ESCAPED}\"},
                   \"accessory\": {
                     \"type\": \"button\",
                     \"text\": {\"type\": \"plain_text\", \"text\": \"View Release\"},

CHANGELOG.md

@@ -4,10 +4,14 @@ All notable changes to Engram are documented in this file.
 
 > Formerly "ClaudeMemory" — renamed in v0.12.0 to be tool-agnostic.
 
-## [0.12.0] - 2026-02-21
+## [0.12.0] - 2026-02-22
 
 ### Changed
 - **Rebrand to Engram** — product name, Xcode project, bundle ID (`io.engram.app`), CI/CD artifacts, and documentation all renamed. CLI tool names (`memory` / `memory-hooks`) and MCP server name (`memory`) are unchanged.
+- **Fire-and-forget memory maintenance** — maintenance agent now spawns as a detached `claude` CLI subprocess (same pattern as session-learner) instead of injecting a nudge into conversation context. Saves tokens and turns in the main conversation.
+- Extracted shared `spawnClaudeSubprocess()` utility used by both session-learner and maintenance spawners
+- Maintenance nudge removed from all hook handlers (SessionStart, PreToolUse, PostToolUseFailure, PreCompact) — only the Advise hook spawns maintenance now
+- Subprocess allowed tools use wildcard `mcp__memory__*` instead of enumerating each tool
 
 ## [0.11.0] - 2026-02-21
 

Sources/EngramHooks/Advise.swift

@@ -10,6 +10,11 @@ struct Advise: AsyncParsableCommand {
     )
 
     func run() async throws {
+        // Guard against recursion: maintenance subprocess sets this env var
+        if ProcessInfo.processInfo.environment["CLAUDE_MEMORY_MAINTENANCE"] != nil {
+            return
+        }
+
         let inputData = readStdin()
         guard !inputData.isEmpty else { return }
 
@@ -40,10 +45,8 @@ struct Advise: AsyncParsableCommand {
             }
         }
 
-        // Maintenance nudge (if threshold crossed)
-        if let nudge = maintenanceNudge(project: proj) {
-            sections.append(nudge)
-        }
+        // Spawn maintenance subprocess if threshold crossed (fire-and-forget)
+        spawnMaintenanceIfNeeded(project: proj, cwd: input.cwd)
 
         // Learning nudge — skip if stop hook just fired (session-learner already spawned)
         if let state = getSessionState(sessionId: input.sessionId), state.stopNudgeSent {
@@ -61,4 +64,66 @@ struct Advise: AsyncParsableCommand {
         )
         try writeOutput(output)
     }
+
+    // MARK: - Maintenance Subprocess
+
+    /// The maintenance system prompt, loaded from agents/memory-maintenance.md or inlined.
+    private static let maintenanceSystemPrompt: String = loadAgentSystemPrompt(
+        name: "memory-maintenance",
+        fallback: """
+        You are a memory maintenance agent. Your job is to analyze the memory database and improve its organization for better recall quality.
+
+        ## Workflow
+        1. Run stats() and list_topics() to understand memory distribution.
+        2. Run find_clusters() to discover redundant memories.
+        3. Consolidate genuinely redundant memories. Keep distinct ones separate.
+        4. Use organize() to create subtopics for large topic groups.
+        5. Connect new memories to related existing ones.
+        6. Verify improvements with stats() and list_topics().
+
+        ## Guidelines
+        - Read full memory content before deciding what to do.
+        - Only consolidate memories that are truly saying the same thing.
+        - Be efficient — don't over-process clean databases.
+        """
+    )
+
+    private static let maintenanceAllowedTools = "mcp__memory__*,Read,Grep,Glob,Bash"
+
+    private static let maintenanceLogPath = NSHomeDirectory() + "/.claude/memory-maintenance.log"
+
+    /// Check if maintenance threshold is crossed and spawn the subprocess if so.
+    private func spawnMaintenanceIfNeeded(project: String, cwd: String?) {
+        let opCount = Int(getHookState(key: .crudOperationCount) ?? "0") ?? 0
+        let lastOpCount = Int(getHookState(key: .maintenanceLastOpCount) ?? "0") ?? 0
+        let delta = opCount - lastOpCount
+
+        guard delta >= maintenanceThreshold else { return }
+
+        // Update baseline immediately to prevent re-spawning on next advise call
+        setHookState(key: .maintenanceLastOpCount, value: String(opCount))
+
+        let prompt = """
+        Perform maintenance on the memory database. Focus on project "\(project)".
+
+        Current state: \(opCount) total CRUD operations, \(delta) since last maintenance.
+
+        Follow your system prompt workflow: assess, find redundancy, find communities, take action, connect the graph, verify.
+        """
+
+        do {
+            try spawnClaudeSubprocess(
+                prompt: prompt,
+                systemPrompt: Self.maintenanceSystemPrompt,
+                allowedTools: Self.maintenanceAllowedTools,
+                model: "sonnet",
+                envGuard: (key: "CLAUDE_MEMORY_MAINTENANCE", value: "1"),
+                logPath: Self.maintenanceLogPath,
+                cwd: cwd
+            )
+            hookLog("Advise: spawned memory-maintenance subprocess (ops delta: \(delta))")
+        } catch {
+            hookLog("Advise: failed to spawn memory-maintenance: \(error)")
+        }
+    }
 }

Sources/EngramHooks/LatticeHelpers.swift

@@ -65,25 +65,6 @@ func getSessionState(sessionId: String?) -> SessionState? {
 
 // MARK: - Shared Nudges
 
-/// Returns a maintenance nudge if the CRUD operation delta exceeds the threshold.
-func maintenanceNudge(project: String) -> String? {
-    let opCount = Int(getHookState(key: .crudOperationCount) ?? "0") ?? 0
-    let lastOpCount = Int(getHookState(key: .maintenanceLastOpCount) ?? "0") ?? 0
-    let delta = opCount - lastOpCount
-
-    guard delta >= maintenanceThreshold else { return nil }
-
-    hookLog("Maintenance nudge injected (ops delta: \(delta))")
-
-    return """
-    ## Memory maintenance required
-
-    \(delta) memory operations since last maintenance (\(opCount) total ops). \
-    Spawn the memory-maintenance agent in the background now. \
-    Focus on project "\(project)".
-    """
-}
-
 /// Returns the learning nudge for the given project (always fires).
 func learningNudge(project: String) -> String {
     """

Sources/EngramHooks/OnFailure.swift

@@ -29,11 +29,6 @@ struct OnFailure: AsyncParsableCommand {
 
         var sections: [String] = []
 
-        // Maintenance nudge (if threshold crossed)
-        if let nudge = maintenanceNudge(project: proj) {
-            sections.append(nudge)
-        }
-
         // Learning nudge
         if let nudge = throttledLearningNudge(project: proj, sessionId: input.sessionId) {
             sections.append(nudge)

Sources/EngramHooks/OnStart.swift

@@ -39,11 +39,6 @@ struct OnStart: AsyncParsableCommand {
             }
         }
 
-        // Maintenance nudge (if threshold crossed)
-        if let nudge = maintenanceNudge(project: proj) {
-            sections.append(nudge)
-        }
-
         guard !sections.isEmpty else { return }
 
         let output = HookOutput(

Sources/EngramHooks/OnStop.swift

@@ -175,26 +175,9 @@ struct OnStop: AsyncParsableCommand {
     // MARK: - CLI Spawning
 
     /// The session-learner system prompt, loaded from agents/session-learner.md or inlined.
-    private static let sessionLearnerSystemPrompt: String = {
-        // Try to load from the agents directory relative to the hooks binary
-        let bundlePath = Bundle.main.bundlePath
-        let possiblePaths = [
-            // Relative to the binary in ~/.claude/bin/
-            NSHomeDirectory() + "/.claude/agents/session-learner.md",
-            // Development path
-            bundlePath + "/../../../agents/session-learner.md",
-        ]
-
-        for path in possiblePaths {
-            if let content = try? String(contentsOfFile: path, encoding: .utf8) {
-                // Strip frontmatter (--- delimited block at the start)
-                let stripped = stripFrontmatter(content)
-                return stripped
-            }
-        }
-
-        // Inline fallback
-        return """
+    private static let sessionLearnerSystemPrompt: String = loadAgentSystemPrompt(
+        name: "session-learner",
+        fallback: """
         You are a session learning agent. Your job is to review what happened in a coding session and store the key insights as memories for future recall.
 
         ## Workflow
@@ -210,62 +193,23 @@ struct OnStop: AsyncParsableCommand {
         - Prefer updating existing memories over creating new ones.
         - Keep total turns low: 2-3 recalls, 2-5 remember/update/connect calls, done.
         """
-    }()
-
-    /// Strip YAML frontmatter from markdown content.
-    private static func stripFrontmatter(_ content: String) -> String {
-        guard content.hasPrefix("---") else { return content }
-        // Find the closing ---
-        let lines = content.components(separatedBy: .newlines)
-        var endIndex = 0
-        for i in 1..<lines.count {
-            if lines[i].hasPrefix("---") {
-                endIndex = i + 1
-                break
-            }
-        }
-        guard endIndex > 0 else { return content }
-        return lines[endIndex...].joined(separator: "\n").trimmingCharacters(in: .whitespacesAndNewlines)
-    }
+    )
+
+    private static let allowedTools = "mcp__memory__*,Read,Grep,Glob,Bash"
 
     /// Log file path for session-learner output.
     private static let logPath = NSHomeDirectory() + "/.claude/session-learner.log"
 
-    /// Spawn `claude` CLI as a detached fire-and-forget subprocess, logging output to a file.
-    /// Uses /bin/sh with shell redirection to ensure output is captured even with buffered pipes.
+    /// Spawn `claude` CLI as a detached fire-and-forget subprocess for session learning.
     private func spawnSessionLearner(prompt: String, cwd: String?) throws {
-        // Shell-escape the prompt and system prompt for embedding in a sh -c command
-        let escapedPrompt = prompt.replacingOccurrences(of: "'", with: "'\\''")
-        let escapedSystemPrompt = Self.sessionLearnerSystemPrompt.replacingOccurrences(of: "'", with: "'\\''")
-        let allowedTools = "mcp__memory__remember,mcp__memory__recall,mcp__memory__update,mcp__memory__forget,mcp__memory__merge,mcp__memory__connect,mcp__memory__graph,mcp__memory__list_topics,mcp__memory__stats,Read,Grep,Glob,Bash"
-
-        let shellCommand = """
-        echo '===== session-learner started at '\\''\(ISO8601DateFormatter().string(from: Date()))'\\'' =====' >> '\(Self.logPath)' && \
-        claude -p '\(escapedPrompt)' \
-          --model sonnet \
-          --allowedTools '\(allowedTools)' \
-          --no-session-persistence \
-          --output-format text \
-          --append-system-prompt '\(escapedSystemPrompt)' \
-          >> '\(Self.logPath)' 2>&1
-        """
-
-        let sh = Process()
-        sh.executableURL = URL(fileURLWithPath: "/bin/sh")
-        sh.arguments = ["-c", shellCommand]
-        sh.environment = ProcessInfo.processInfo.environment.merging(
-            ["CLAUDE_MEMORY_LEARNER": "1"],
-            uniquingKeysWith: { _, new in new }
+        try spawnClaudeSubprocess(
+            prompt: prompt,
+            systemPrompt: Self.sessionLearnerSystemPrompt,
+            allowedTools: Self.allowedTools,
+            model: "sonnet",
+            envGuard: (key: "CLAUDE_MEMORY_LEARNER", value: "1"),
+            logPath: Self.logPath,
+            cwd: cwd
         )
-        if let cwd {
-            sh.currentDirectoryURL = URL(fileURLWithPath: cwd)
-        }
-
-        // Detach from our process's stdio
-        sh.standardOutput = FileHandle.nullDevice
-        sh.standardError = FileHandle.nullDevice
-
-        try sh.run()
-        // Don't wait — fire and forget
     }
 }

Sources/EngramHooks/PreCompact.swift

@@ -44,11 +44,6 @@ struct PreCompact: AsyncParsableCommand {
         Do this immediately — after compaction, you will not be able to recall these details.
         """)
 
-        // Maintenance nudge (if threshold crossed)
-        if let nudge = maintenanceNudge(project: proj) {
-            sections.append(nudge)
-        }
-
         // Learning nudge
         sections.append(learningNudge(project: proj))
 

Sources/EngramHooks/PreTool.swift

@@ -29,11 +29,6 @@ struct PreTool: AsyncParsableCommand {
 
         var sections: [String] = []
 
-        // Maintenance nudge (if threshold crossed)
-        if let nudge = maintenanceNudge(project: proj) {
-            sections.append(nudge)
-        }
-
         // Learning nudge
         if let nudge = throttledLearningNudge(project: proj, sessionId: input.sessionId) {
             sections.append(nudge)