fix(memory): harden recall hot path

[yyhhyyyyyy]

• add query embedding timeout and in-flight gate
• use corpus-aware keyword recall for agent-facing paths
• batch recall access updates
• surface missing memory model hints
• archive rejected memory wave specs

Summary by CodeRabbit

• New Features

  • Added smarter memory recall keyword matching, including support for broader query matching and corpus-aware term selection.
  • Added batch access tracking for recalled memories to improve consistency.
  • Added clearer setup hints when required memory models are not configured.

• Bug Fixes

  • Improved recall behavior for long, mixed-language, and CJK queries.
  • Preserved recall performance when embedding requests are slow or already in progress.
  • Kept management search precise while allowing recall to use broader matching.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b34e6d80-9a9b-4a9d-a56c-4ad4ea2242f0

📥 Commits

Reviewing files that changed from the base of the PR and between 6a0c7e4 and 8ffc67a.

📒 Files selected for processing (14)

• docs/issues/memory-recall-hot-path-keyword-recall/plan.md
• docs/issues/memory-recall-hot-path-keyword-recall/spec.md
• docs/issues/memory-recall-hot-path-keyword-recall/tasks.md
• src/main/presenter/memoryPresenter/index.ts
• src/main/presenter/memoryPresenter/recallKeyword.ts
• src/main/presenter/memoryPresenter/types.ts
• src/main/presenter/sqlitePresenter/tables/agentMemory.ts
• src/renderer/settings/components/MemoryConfigPanel.vue
• test/main/presenter/agentMemoryTable.test.ts
• test/main/presenter/fakes/memoryFakes.ts
• test/main/presenter/memoryPresenter.test.ts
• test/main/presenter/memorySearch.test.ts
• test/main/presenter/recallKeyword.test.ts
• test/renderer/components/MemoryConfigPanel.test.ts

---

📝 Walkthrough

Walkthrough

Introduces corpus-aware keyword recall for agent-facing memory search, replacing static stopword filtering with dynamic term statistics. Adds query-embedding soft-timeout and in-flight deduplication, extends repository contracts with matchMode search, term stats, and batched access recording, and updates settings UI hints.

Changes

Keyword Recall Hot Path

Layer / File(s)	Summary
Planning and spec docs docs/issues/memory-recall-hot-path-keyword-recall/plan.md, .../spec.md, .../tasks.md	Adds plan, specification, and task-checklist documents describing the keyword-recall hot-path feature scope and behavior.
Repository contract, SQLite implementation, and fakes src/main/presenter/memoryPresenter/types.ts, src/main/presenter/sqlitePresenter/tables/agentMemory.ts, test/main/presenter/fakes/memoryFakes.ts, test/main/presenter/agentMemoryTable.test.ts	Extends search with a matchMode option, adds getRecallKeywordTermStats and recordAccessBatch to the repository port, SQLite table, and fake repository, with tests validating match-mode filtering, term-stat aggregation, and batched access updates.
Recall keyword extraction and selection module src/main/presenter/memoryPresenter/recallKeyword.ts, test/main/presenter/recallKeyword.test.ts	Adds extractRecallKeywordCandidates, selectRecallKeywordTerms, and buildRecallKeywordQuery for tokenizing ASCII/code/CJK terms and ranking them by corpus frequency, with unit tests for extraction caps and selection ordering.
MemoryPresenter recall wiring, embedding timeout, batched access src/main/presenter/memoryPresenter/index.ts, test/main/presenter/memoryPresenter.test.ts, test/main/presenter/memorySearch.test.ts	Adds a soft-timeout wrapper and in-flight query-embedding tracking, routes agent-facing recall/injection through keywordized OR matching while keeping management search on all-term matching, replaces per-item access recording with recordAccessBatch, and clears in-flight state on cleanup/dispose.
Settings panel model hints src/renderer/settings/components/MemoryConfigPanel.vue, test/renderer/components/MemoryConfigPanel.test.ts	Updates embedding/extraction model hint styling to show an amber attention style when the model is unset instead of a fixed muted style.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant MemoryPresenter
  participant QueryEmbeddingInFlight
  participant EmbeddingProvider
  participant AgentMemoryTable

  Caller->>MemoryPresenter: recall(query)
  MemoryPresenter->>QueryEmbeddingInFlight: startQueryEmbedding(agentId, providerId, modelId)
  alt already in-flight and fresh
    QueryEmbeddingInFlight-->>MemoryPresenter: skip vector recall
  else new request
    MemoryPresenter->>EmbeddingProvider: getEmbeddings(query)
    MemoryPresenter->>MemoryPresenter: withSoftTimeout(embedding promise)
    alt timeout
      MemoryPresenter-->>MemoryPresenter: skip vector, keep vector-store readiness
    else resolved in time
      EmbeddingProvider-->>MemoryPresenter: embedding vector
    end
  end
  MemoryPresenter->>AgentMemoryTable: search(keywordQuery, matchMode: any)
  AgentMemoryTable-->>MemoryPresenter: matched rows
  MemoryPresenter->>AgentMemoryTable: recordAccessBatch(ids, now)
  MemoryPresenter-->>Caller: fused recall results

Loading

Possibly related PRs

• ThinkInAIXYZ/deepchat#1770: Builds on the same AgentMemoryTable.search and MemoryPresenter recall wiring foundation extended in this PR.
• ThinkInAIXYZ/deepchat#1796: Also modifies embedding/reindex lifecycle logic in src/main/presenter/memoryPresenter/index.ts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: hardening the memory recall hot path with reliability and behavior fixes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/memory-recall-hot-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}