#395 — Reflection Items Lack Resolution Mechanism

[jlin53882]

Problem

The reflection pipeline is unidirectional: extract → store → decay → inject. There is no resolve → invalidate → suppress path.

Once a reflection item is written, it continues to be injected into every new session until maxAgeDays naturally expires (45 days for invariant items by default). When a problem is solved, the stale derived lessons about that problem keep being injected, occupying the injection budget and blocking relevant items.

Example:

• Session A: Rerank misconfiguration problem occurs → 6 derived lessons extracted
• Session B: Rerank is confirmed working
• Sessions C, D, E...: The 6 stale items continue to be injected on every new session, for up to 45 days

Proposed Solution: Option A — resolvedAt field + manual resolve tool

1. Add resolvedAt to ReflectionItemMetadata

interface ReflectionItemMetadata {
  // ... existing fields ...
  resolvedAt?: number;      // Unix timestamp when marked resolved
  resolvedBy?: string;    // agentId that marked it resolved
  resolutionNote?: string; // optional note
}

2. Add filterByResolved() in reflection recall

In reflection-recall.ts, after filterByMaxAge:

function filterByResolved(items: ReflectionItem[]): ReflectionItem[] {
  return items.filter(item => item.metadata.resolvedAt === undefined);
}

This applies to all injection paths (derived-focus and inherited-rules) since they all consume the same recall output.

3. Add memory_reflection_resolve tool

memory_reflection_resolve({
  query?: string,    // BM25 match — resolves all matching items
  id?: string,       // Direct ID match — resolves one specific item
  note?: string      // Optional resolution note
})

Flow:

1. If id provided → directly resolve by ID
2. If query provided → bm25Search() for semantic match → resolve all results
3. Set resolvedAt = Date.now(), resolvedBy, optional note
4. Return "resolved N items"

Why Option A over Option B/C?

Option	Effort	Risk
A — resolvedAt + tool	Low	Minimal — existing fields unchanged, new field is additive
B — Cross-pipeline suppression	Medium	Needs semantic similarity classification; high complexity for unclear accuracy
C — Full status schema	Medium-High	Requires schema migration; most robust but overkill for the problem

Option A requires no schema migration and solves the core issue.

Questions for Author

1. Does the resolvedAt field approach work for your use case?
2. Should resolving an item automatically resolve all items with the same strictKey?
3. Should there be a memory_reflection_list tool to let agents review their reflection items before resolving?

Related: #395

[jlin53882]

Additional Analysis

Q1 — Does resolvedAt field approach work?

✅ Yes. Clean, non-breaking, lowest cost solution.

Q2 — Should resolving automatically resolve all items with the same strictKey?

Yes, and it should.

Rationale: strictKey represents multiple perspectives on the same underlying problem. When a problem is resolved, all its perspectives should be marked — leaving some unresolved would let them continue polluting the injection budget.

Q3 — Should there be a memory_reflection_list tool?

Yes — this tool is essential, not optional.

Without a list tool, the agent cannot discover what reflection items exist and therefore cannot meaningfully call resolve. Recommend also adding memory_reflection_stats:

memory_reflection_list({
  status: 'active' | 'resolved' | 'all',  // default: 'active'
  scope: 'global',
  limit: 20
})

memory_reflection_stats()
// Returns: { total, active, resolved, byKind: { invariant, derived }, byScope }

Proposed tool set for Option A

Tool	Purpose
memory_reflection_list	Browse reflection items before resolving
memory_reflection_stats	Show counts by status/kind/scope
memory_reflection_resolve({ query?, id?, note? })	Mark items as resolved (by query or id)

[AliceLJY]

Good analysis, and the resolvedAt field approach is the right one — lightweight, non-breaking, and it solves the core injection-budget pollution.

A few alignment points:

1. strictKey cascading: Agree that resolving by strictKey should mark all items under that key. The underlying problem is one, the perspectives are many — leaving some unresolved defeats the purpose.

2. Interaction with decay: Once resolvedAt is set, should the item still decay naturally, or should it be immediately excluded from all recall paths? I'd lean toward immediate exclusion (the filterByResolved approach you described), with decay continuing in the background for eventual GC cleanup.

3. memory_reflection_resolve tool: The dual-mode input (query vs id) makes sense. One consideration: if using query + BM25 match, we should surface the matched items to the user before actually resolving, to avoid accidental bulk-resolve of unrelated items. A dryRun flag or a two-step flow (search → confirm → resolve) would be safer.

4. Relationship to PR [Feature Request / Enhancement] Reflection items lack resolution/invalidation mechanism after underlying problem is solved #395 original: This issue reframes [Feature Request / Enhancement] Reflection items lack resolution/invalidation mechanism after underlying problem is solved #395 with concrete implementation. If you'd like to contribute a PR, I'd suggest starting with the resolvedAt field + filterByResolved() in reflection recall — that's the minimum viable fix. The resolve tool can come as a follow-up.

Welcome to submit a PR!

[jlin53882]

Thanks for the detailed feedback, Alice! Our design (v2.3) addresses all 4 points — here's the alignment:

1. strictKey cascading Already covered. The memory_reflection_resolve tool accepts an optional strictKey parameter. When provided, it resolves all reflection items sharing that strictKey atomically in a single store transaction. When id is provided directly, it resolves just that item.

2. Immediate exclusion + background decay Already covered. We use filterByResolved on all recall paths — resolved items are excluded from injection immediately after resolvedAt is set. Natural decay continues in the background (via invalidated_at or TTL) for eventual GC cleanup. No stale items pollute the injection budget.

3. dryRun for BM25 query mode Already covered. The tool has a dryRun: boolean parameter:

• dryRun: true → returns wouldResolveIds and the matched items for user confirmation before any write
• dryRun: false → executes the resolve and returns resolvedIds

4. Minimum viable → full implementation Agreed. Our implementation order:

• Phase 1 (Steps 1–2): Add resolvedAt + resolutionNote fields to SmartMemoryMetadata, implement filterByResolved() in all recall paths (~45 min)
• Phase 2 (Steps 3–4): Add memory_reflection_resolve tool with dryRun support (~75 min)
• Phase 3 (Steps 5–7): Integrate confirmed_use_count feedback signal and BM25 expansion (~60 min)

Full design doc: https://gist.github.com/jlin53882/3fdd6176a6051fe3c27c3f21ba097e7e

Welcome to review and PR!

[AliceLJY]

Thanks — this is now too wide for a single PR, so please split it.

1. For this issue, start with the minimal fix only: add resolvedAt / resolutionNote metadata and filterByResolved() on all reflection recall paths, with tests.
2. Keep memory_reflection_resolve as a follow-up once the passive suppression path is in.
3. Do not bundle the feedback-signal / BM25-enrichment work here; that belongs to the Proposal A/B track from [RFC] Proposal A & B Implementation Analysis #445 and PRs feat: Proposal A - dynamic importance feedback signals (Phase 1 + Phase 2) #462-feat: Proposal B Phase 2 - full retrieval neighbor enrichment #464.

The dryRun preview and strictKey cascading make sense for the follow-up tool, but I do not want them blocking the first fix.

[jlin53882]

處理完成

已實作 Issue #447 的 minimal fix — 被動抑制 resolved reflection items。

修改內容

檔案	變動
src/reflection-item-store.ts	在 ReflectionItemMetadata interface 加入 resolvedAt?、resolvedBy?、resolutionNote? 三個 optional 欄位
src/reflection-store.ts	在 loadAgentReflectionSlicesFromEntries() 加入 filterByResolved()，過濾掉 resolvedAt !== undefined 的 items
test/memory-reflection.test.mjs	3 個測試：invariant suppression、derived suppression、unresolved items unchanged

實作邏輯

loadAgentReflectionSlicesFromEntries()
  → reflectionRows（從 store 取出）
  → itemRows（只取 type="memory-reflection-item"）
  → unresolvedItemRows（過濾 resolvedAt !== undefined）← 這裡
  → buildInvariantCandidates(unresolvedItemRows, legacyRows)
  → buildDerivedCandidates(unresolvedItemRows, legacyRows)

這樣 filterByResolved() 自動作用於所有呼叫 loadAgentReflectionSlicesFromEntries 的地方，包括 inherited-rules 和 derived-focus 兩條 injection paths。

測試結果

3 個新測試全部通過：

✔ suppresses resolved invariant items from recall output
✔ suppresses resolved derived items from recall output
✔ passes unresolved items through unchanged when no resolvedAt is set

35/36 測試通過。1 個失敗的測試 (defaults to systemSessionMemory) 與本次修改無關，是預先存在的問題。

PR: #483

設計選擇

• 純 additive：不需要 migration，舊有 items 沒有 resolvedAt 欄位 → 視為 unresolved
• minimal fix：只做被動抑制，memory_reflection_resolve tool 留到 follow-up
• 不包含 dryRun / strictKey cascading：那些是 tool 的設計細節，不該阻擋 first fix

PR #478 (#437) 也已合併，感謝作者的提案方向。