Index 09: Memory — 跨会话记忆管线

selection（选择）    →  从对话中选出值得长期记住的事实
extraction（提取）   →  把候选格式化为结构化记忆条目
consolidation（整合）→ 与已有记忆合并（新增/更新/跳过）

$ cat-code
🐱 Cat-Code — Index 07: Skill Loading · s08: Context Compact · s09: Memory
> 继续昨天的重构，把 UserService 也改成 Kotlin 风格
[Agent] 好的，我记得昨天我们定了两个约束：项目遵循 Kotlin 官方惯例（project-api-style），
        以及你偏好写操作先过权限审批（user-prefers-safe-writes）。让我先看一下 UserService...

                    ┌─────────────────────────────────────────────┐
                    │          ~/.cat-code/memory/                │
                    │   MEMORY.md（索引，每行一个链接）             │
                    │   user-prefers-vim.md（每记忆一文件）         │
                    │   project-api-style.md                      │
                    └───────────────┬─────────────────────────────┘
                                    │
        ┌───────────────────────────┼──────────────────────────────┐
        │                           │                              │
  会话开始（读路径）            会话中（工具）                  会话结束（写路径）
        │                           │                              │
  MemoryInjectionHook          memory_read / memory_write       MemoryManager
  (PRE_LLM_REQUEST)             (ToolRegistry)                  extractAndConsolidate()
        │                           │                              │
  注入 name+description         按 name 读详情 / 写记忆             ├─ MemoryExtractor
  索引 SYSTEM 消息               （写经 writeEntry 单一写路径）      │   (selection+extraction,
        │                           │                              │    一次 LLM 调用 → 候选)
        │                           │                              ├─ MemoryConsolidator
        │                           │                              │   (consolidation,
        │                           │                              │    一次 LLM 调用 → 操作)
        │                           │                              └─ MemoryStore.apply()

enum class MemoryType { USER, FEEDBACK, PROJECT, REFERENCE }

data class MemoryEntry(
    val name: String,            // kebab-case slug，唯一 key，文件名 = "$name.md"
    val description: String,     // 一句话摘要（用于索引注入，省 token）
    val type: MemoryType,        // 对齐 Claude Code 的 type 分类
    val content: String,         // 记忆正文
    val createdAt: LocalDate = LocalDate.now(),
    val updatedAt: LocalDate = LocalDate.now()
)

data class MemorySummary(val name: String, val description: String)  // 提取器参考用，不含正文
data class CandidateMemory(val type: MemoryType, val name: String, val description: String, val content: String)

enum class MemoryAction { ADD, UPDATE, SKIP }

data class MemoryOperation(
    val action: MemoryAction,
    val targetName: String? = null,   // UPDATE 时的目标条目名
    val entry: CandidateMemory? = null
)

data class ConsolidationReport(
    val candidatesFound: Int,
    val added: List<String>, updated: List<String>, skipped: List<String>,
    val skippedReason: String = ""
)

---
name: user-prefers-vim
description: 用户偏好 vim 编辑器
metadata:
  type: user
  createdAt: 2026-08-06
  updatedAt: 2026-08-06
---
用户偏好 vim 作为编辑器，配置在 ~/.vimrc。

class MemoryStore(private val dir: Path) {
    init { Files.createDirectories(dir); reloadFromDisk() }

    fun loadAll(): List<MemoryEntry>               // 快照副本，按 name 排序
    fun save(entry: MemoryEntry)                   // 新增（同名替换）
    fun update(entry: MemoryEntry)                 // 按 name 更新，保留 createdAt
    fun delete(name: String): Boolean              // 删除
    fun apply(operations: List<MemoryOperation>): AppliedCounts  // 整合产物批量应用
}

fun update(entry: MemoryEntry) {
    val old = entries.firstOrNull { it.name == entry.name }
    val merged = if (old != null) entry.copy(createdAt = old.createdAt) else entry
    entries.removeAll { it.name == merged.name }
    entries.add(merged)
    writeEntryFile(merged)
    rebuildIndex()
}

fun apply(operations: List<MemoryOperation>): AppliedCounts {
    var added = 0; var updated = 0; var skipped = 0
    for (op in operations) {
        when (op.action) {
            MemoryAction.ADD -> {
                if (op.entry != null) { save(op.entry.toEntry()); added++ }
                else skipped++      // ADD 但无内容 → 计为跳过，不撒谎
            }
            MemoryAction.UPDATE -> {
                val target = op.targetName; val candidate = op.entry
                if (target != null && candidate != null) { update(candidate.toEntry(nameOverride = target)); updated++ }
                else skipped++
            }
            MemoryAction.SKIP -> skipped++
        }
    }
    return AppliedCounts(added, updated, skipped)
}

private fun validateName(name: String) {
    require(name.isNotBlank()) { "Memory name must not be blank" }
    require('/' !in name && '\\' !in name) { "Memory name must not contain path separators" }
    require(name != ".." && !name.startsWith("../") && !name.startsWith("..\\")) { "Memory name must not traverse directories" }
}

# Memory Index

- [project-api-style](project-api-style.md) — 项目 API 风格遵循 Kotlin 官方惯例
- [user-prefers-vim](user-prefers-vim.md) — 用户偏好 vim 编辑器

class MemoryExtractor(
    private val llmProvider: LLMProvider,
    private val config: MemoryConfig = MemoryConfig()
) {
    suspend fun extract(
        messages: List<Message>,              // watermark 之后的新消息窗口
        existingSummaries: List<MemorySummary> // 已有记忆 name+description，防重复提取
    ): List<CandidateMemory> {
        if (messages.isEmpty()) return emptyList()   // 空窗口短路，省一次 LLM 调用
        val prompt = buildExtractPrompt(messages, existingSummaries)
        val response = llmProvider.chat(
            messages = listOf(Message(Role.USER, prompt)),
            options = ChatOptions(maxTokens = config.extractMaxTokens, temperature = 0.3),
            tools = emptyList()
        )
        return parseCandidates(response.content)
    }
}

You are a memory extractor for an AI coding agent. Review the conversation below and
identify facts worth remembering across sessions. Remember:
- User preferences and habits
- Project decisions and constraints
- Key technical facts learned (APIs, file layout, gotchas)
- Anything the user explicitly asked to remember
Ignore: one-off instructions, temporary details, small talk.
If the conversation contains a "[Conversation Summary]" system message, extract from it too.
Do NOT re-extract facts already listed under "## Already Known", and ignore the "# Persistent Memory" index block.
Respond with ONLY a JSON object, no markdown:
{"candidates": [{"type": "user|feedback|project|reference", "name": "kebab-case-slug",
"description": "one-line summary", "content": "the fact to remember"}]}
If nothing is worth remembering, respond with {"candidates": []}

## Already Known
- project-api-style: 项目 API 风格遵循 Kotlin 官方惯例

## Conversation
USER: 继续昨天的重构，把 UserService 也改成 Kotlin 风格
ASSISTANT: 好的，让我先看一下...
  [Tool Calls: read_file]
  [Tool Results: (文件内容预览...)]

internal fun parseCandidates(content: String): List<CandidateMemory> {
    val dto = try {
        json.decodeFromString<CandidatesResponse>(MemoryJson.stripCodeFence(content))
    } catch (e: SerializationException) {
        logger.warn(e) { "Failed to parse extractor output, dropping batch" }
        return emptyList()
    } catch (e: IllegalArgumentException) {
        logger.warn(e) { "Failed to parse extractor output, dropping batch" }
        return emptyList()
    }
    return dto.candidates.mapNotNull { c ->
        val candidate = c.toCandidate()
        if (candidate == null) {
            logger.warn { "Dropping invalid candidate: type=${c.type}, name=${c.name}" }
            null
        } else candidate
    }
}

class MemoryConsolidator(
    private val llmProvider: LLMProvider,
    private val config: MemoryConfig = MemoryConfig()
) {
    suspend fun consolidate(
        candidates: List<CandidateMemory>,
        existing: List<MemoryEntry>     // 现有全部记忆（含正文，供 LLM 对比）
    ): List<MemoryOperation> {
        if (candidates.isEmpty()) return emptyList()   // 空候选短路
        val prompt = buildConsolidatePrompt(candidates, existing)
        val response = llmProvider.chat(
            messages = listOf(Message(Role.USER, prompt)),
            options = ChatOptions(maxTokens = config.extractMaxTokens, temperature = 0.3),
            tools = emptyList()
        )
        return parseOperations(response.content)
    }
}

You are a memory consolidator for an AI coding agent. Decide how to merge the candidate
memories into the existing memory store.
For each candidate decide:
- "add": the fact is new and worth storing
- "update": the fact updates an existing memory with the same or closely related topic;
  set targetName to the existing memory's name
- "skip": the fact duplicates an existing memory, is trivial, or is already known
Existing memories are listed under "## Existing Memories" (name, type, content).
Respond with ONLY a JSON object, no markdown:
{"operations": [{"action": "add|update|skip", "targetName": "<existing name for update, else null>",
"entry": {"type": "user|feedback|project|reference", "name": "kebab-case-slug",
"description": "one-line summary", "content": "the fact"}}]}
Every candidate must appear in exactly one operation. For skip, entry may be null.

## Existing Memories
### user-prefers-vim (user)
用户偏好 vim 编辑器
用户偏好 vim 作为编辑器，配置在 ~/.vimrc。

## Candidates
1. [project] project-api-style: 项目 API 风格遵循 Kotlin 官方惯例
   API 调用、命名、注释都遵循 Kotlin 官方风格指南

class MemoryManager(
    private val store: MemoryStore,
    private val extractor: MemoryExtractor,
    private val consolidator: MemoryConsolidator,
    private val config: MemoryConfig = MemoryConfig()
) {
    private var lastProcessedIndex: Int = 0   // watermark：会话内只增不减

    suspend fun extractAndConsolidate(messages: List<Message>): ConsolidationReport {
        val start = lastProcessedIndex.coerceAtMost(messages.size)
        val newMessages = messages.subList(start, messages.size)

        if (newMessages.size < config.extractMinMessages) {
            return ConsolidationReport(candidatesFound = 0, skippedReason = "消息不足 ...")
        }
        val existing = store.loadAll()
        val candidates = extractor.extract(newMessages, existing.map { MemorySummary(it.name, it.description) })

        if (candidates.isEmpty()) {
            lastProcessedIndex = messages.size      // 已审查过，推进
            return ConsolidationReport(candidatesFound = 0, skippedReason = "无可记内容")
        }
        val operations = consolidator.consolidate(candidates, existing)
        val counts = store.apply(operations)
        lastProcessedIndex = messages.size          // 整合完成，推进
        return buildReport(candidates.size, operations)
    }
}

class MemoryInjectionHook(
    private val store: MemoryStore,
    private val maxInjected: Int = MemoryConfig.DEFAULT_MAX_INJECTED
) {
    fun registerTo(manager: HookManager) {
        val handler: HookHandler = handler@{ event ->
            if (event.type != HookEvent.Type.PRE_LLM_REQUEST) return@handler HookResult.Continue
            val entries = store.loadAll().take(maxInjected)
            if (entries.isEmpty()) return@handler HookResult.Continue
            HookResult.AppendMessages(listOf(Message(Role.SYSTEM, buildMemoryIndexText(entries))))
        }
        manager.on(HookEvent.Type.PRE_LLM_REQUEST, handler)
    }
}

# Persistent Memory

The following memories were saved from previous sessions. Call `memory_read`
with a memory's name to retrieve its full content.

## user-prefers-vim
用户偏好 vim 编辑器

## project-api-style
项目 API 风格遵循 Kotlin 官方惯例

override suspend fun execute(input: JsonObject): ToolResult {
    val name = input["name"]?.jsonPrimitive?.content?.trim()?.takeIf { it.isNotEmpty() }
    val entries = store.loadAll()
    return if (name == null) {
        val text = entries.joinToString("\n\n") { formatEntry(it) }
        ToolResult("", if (text.isBlank()) "No memories stored." else text)
    } else {
        val entry = entries.firstOrNull { it.name == name }
            ?: return ToolResult("", "Memory not found: $name. Use memory_read without name to list all memories.", isError = true)
        ToolResult("", formatEntry(entry))
    }
}

override suspend fun execute(input: JsonObject): ToolResult {
    val name = input["name"]?.jsonPrimitive?.content?.trim().orEmpty()
    if (name.isBlank()) return ToolResult("", "Error: name is required", isError = true)
    val type = parseType(input["type"]?.jsonPrimitive?.content)
        ?: return ToolResult("", "Error: type must be one of user|feedback|project|reference", isError = true)
    val description = input["description"]?.jsonPrimitive?.content ?: ""
    val content = input["content"]?.jsonPrimitive?.content ?: ""
    manager.writeEntry(MemoryEntry(name, description, type, content))   // 单一写路径
    return ToolResult("", "Memory saved: $name")
}

class MemoryCommand : ReplCommand {
    // /memory            → 立即运行提取+整合管线，输出报告
    // /memory list       → 列出所有记忆（name - description (type)）
    // /memory show <name> → 显示一条记忆完整内容
    // /memory clear      → 清空记忆库
}

private suspend fun runPipeline(ctx: ReplContext): ReplCommandResult {
    val report = try {
        ctx.memoryManager.extractAndConsolidate(ctx.agentLoop.messagesHistory)
    } catch (e: Exception) {
        // fail-open：提取/整合的 LLM 调用异常不应中断 REPL 会话
        println("Memory pipeline failed: ${e.message}")
        return ReplCommandResult.Continue
    }
    println("Memory pipeline complete:")
    println("  candidates: ${report.candidatesFound}")
    if (report.skippedReason.isNotEmpty()) println("  note: ${report.skippedReason}")
    if (report.added.isNotEmpty()) println("  added: ${report.added.joinToString()}")
    if (report.updated.isNotEmpty()) println("  updated: ${report.updated.joinToString()}")
    if (report.skipped.isNotEmpty()) println("  skipped: ${report.skipped.joinToString()}")
    return ReplCommandResult.Continue
}

// s09: 构建记忆系统（文件存储 + 提取/整合管线 + 注入 hook + 工具）
val memoryConfig = MemoryConfig()
val memoryStore = MemoryStore(memoryConfig.resolvedMemoryDir())
val memoryExtractor = MemoryExtractor(llmProvider, memoryConfig)
val memoryConsolidator = MemoryConsolidator(llmProvider, memoryConfig)
memoryManager = MemoryManager(memoryStore, memoryExtractor, memoryConsolidator, memoryConfig)
MemoryInjectionHook(memoryStore, memoryConfig.maxInjectedSummaries).registerTo(hookManager)
toolRegistry.register(MemoryReadTool(memoryStore))
toolRegistry.register(MemoryWriteTool(memoryManager))

} finally {
    subagentScope.cancel()
    logger.info { "Subagent scope cancelled" }

    // s09: 会话结束自动提取记忆（fail-open，失败不阻断退出）
    try {
        val report = runBlocking { memoryManager.extractAndConsolidate(agentLoop.messagesHistory) }
        logger.info { "Session-end memory: ${report.added.size} added, ${report.updated.size} updated" }
    } catch (e: Exception) {
        logger.warn(e) { "Session-end memory extraction failed" }
    }
}

data class MemoryConfig(
    val memoryDir: String = DEFAULT_MEMORY_DIR,          // "~/.cat-code/memory"
    val extractMinMessages: Int = 4,                     // 至少 4 条新消息才触发提取
    val extractMaxTokens: Int = 2048,                    // 提取/整合 LLM 输出 token 上限
    val maxInjectedSummaries: Int = 30                   // 注入索引条数上限
)

用户启动 REPL（记忆库为空，注入 Hook 返回 Continue，不浪费 token）
用户："用 vim 编辑，别动 tests 目录"
智能体："好的，记住了。"
  →（用户 Ctrl+D 退出）
  → finally: extractAndConsolidate(messagesHistory)
      → 提取器：LLM 审阅对话，产出候选 [{type:user, name:user-prefers-vim, ...}]
      → 整合器：现有记忆为空，决策 ADD
      → MemoryStore.apply → 写入 user-prefers-vim.md + 重建 MEMORY.md
  [INFO] Session-end memory: 1 added, 0 updated

用户启动 REPL
  → MemoryInjectionHook: PRE_LLM_REQUEST → 追加 "# Persistent Memory / ## user-prefers-vim / 用户偏好 vim 编辑器"
用户："继续重构 UserService"
  → LLM 看到索引，想起用户偏好，主动遵守
  →（若需要详情）调用 memory_read(user-prefers-vim) 读全文

智能体发现一个 API 坑 → 想记住 → 调用 memory_write{name: api-gotcha, type: reference, ...}
  → 用户批准（权限管线）→ writeEntry → 立即持久化