feat(memory): add task-aware agentic memory

[yyhhyyyyyy]

Adds task-aware agentic memory writing across runtime, kernel, UI, and skill guidance.

• Makes fallback extraction tool-aware, so short tool-using turns can enter memory extraction.
• Prevents empty visible-text spans from consuming the memory cursor.
• Adds agentic memory categories: user_preference, project_fact, task_outcome, heuristic, anti_pattern.
• Shows category badges and category filtering in the Manage tab, with uncategorized handling.
• Adds the bundled memory-management skill and triage guardrail coverage.
• Updates agent memory architecture docs to match the new write-path behavior.

Summary by CodeRabbit

• New Features

  • Added memory categorization system with five categories (user preference, project fact, task outcome, heuristic, anti-pattern).
  • Added category filter to Memory Manager UI for browsing memories by type.
  • Added category badges displayed next to memories for quick visual identification.
  • memory_remember tool now accepts optional category parameter to organize memories.

• Behavior Changes

  • Forgetting a memory now soft-archives it instead of permanently deleting it.

• Documentation

  • Added Memory Management skill guide covering recall, storage, and learning practices.

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces a five-value AgentMemoryCategory taxonomy (user_preference, project_fact, task_outcome, heuristic, anti_pattern) end-to-end: new shared type primitives, SQLite schema migration v37 adding a nullable category column, rewritten extraction/triage prompts, a candidate normalization layer with category-aware importance floors and kind-derivation rules, category propagation through the write coordinator's ADD/UPDATE/SUPERSEDE/CHALLENGE paths, tool and IPC route wiring, a category filter in the settings UI with 18-locale i18n strings, and a new memory-management skill file.

Changes

Agent Memory Category Feature

Layer / File(s)	Summary
Shared category type definitions and route contracts src/shared/types/agent-memory.ts, src/shared/types/index.d.ts, src/shared/contracts/routes/memory.routes.ts	Adds AGENT_MEMORY_CATEGORIES tuple, AgentMemoryCategory union, CATEGORY_IMPORTANCE_FLOOR map, and isAgentMemoryCategory type guard; re-exports from the types index; extends MemoryItemSchema and memoryAddRoute input with nullable category.
SQLite category column: schema, migration v37, and repair src/main/presenter/sqlitePresenter/tables/agentMemory.ts, src/main/presenter/sqlitePresenter/schemaCatalog.ts	Bumps schema version 35→37; extends AgentMemoryRow and AgentMemoryInsertInput with category; updates CREATE TABLE, adds v37 migration ALTER TABLE, extends insert and updateContent with a category-conditional UPDATE branch, and registers category in repairableColumns.
Admission span heuristics and extraction/triage prompt rewrite src/main/presenter/agentRuntimePresenter/index.ts, src/main/presenter/memoryPresenter/extraction.ts	Refactors buildMemorySpanFromTape to return MemoryAdmissionSpan (hadToolUse, visibleTextChars); adds readToolCallMessageId; gates compaction on visibleTextChars > 0; replaces single-delta fallback threshold with tool-use/delta/visible-text heuristic. Rewrites buildExtractionPrompt for category-shaped JSON with task_outcome cap; updates buildTriagePrompt KEEP criteria; reworks parseMemoryCandidates to validate category, enforce single task_outcome, and return importance as undefined instead of clamped.
Candidate types, normalization helpers, and write-coordinator category propagation src/main/presenter/memoryPresenter/types.ts, src/main/presenter/memoryPresenter/index.ts, src/main/presenter/memoryPresenter/decision.ts	Introduces NormalizedMemoryCandidate with required kind/importance and nullable category. Adds normalizeMemoryCandidate, clampImportance, canCarryCategory. Updates all write paths (ADD/UPDATE/SUPERSEDE/CHALLENGE, applyContentUpdate, directAddMemory, addUserMemory, forgetMemory) to normalize before provenance-key generation and propagate category only when the target kind allows it and its category is NULL. Updates buildDecisionPrompt parameter to NormalizedMemoryCandidate.
Tool schema, runtime port, and IPC route wiring src/main/presenter/toolPresenter/agentTools/agentMemoryTools.ts, src/main/presenter/toolPresenter/runtimePorts.ts, src/main/presenter/index.ts, src/main/routes/index.ts	Extends memory_remember Zod schema with optional category enum; forwards category through tool handler → runtimePorts.rememberMemory → presenter. Adds normalizeMemoryCategory and category field to toMemoryItemDto; wires input.category into memoryAddRoute handler.
Settings UI category filter and i18n strings src/renderer/settings/components/MemoryManagerPanel.vue, src/renderer/src/i18n/*/settings.json	Adds category <Select> alongside search in MemoryManagerPanel; computes displayedMemories filtered by categoryFilter; adds category badge per memory item; introduces emptyMemoryMessage computed; resets filter on agentId change. Adds category filter strings to all 18 locale JSON files.
Tests, fakes, and documentation test/main/presenter/*, test/renderer/components/*, resources/skills/memory-management/SKILL.md, docs/architecture/agent-memory-system/spec.md	Updates FakeRepository insert/updateContent with category; adds tests for SQLite migration v37, admission span signals, extraction parse/prompt/e2e, normalization/propagation/absorption, decision prompt shape, DTO category pass-through, tool category propagation, schema repair, and UI category filter. Adds memory-management SKILL.md and its discovery test. Updates architecture spec.

Sequence Diagram(s)

sequenceDiagram
  participant Agent
  participant AgentRuntimePresenter
  participant ExtractionPipeline
  participant MemoryPresenter
  participant AgentMemoryTable

  Agent->>AgentRuntimePresenter: session turn with tool use / content
  AgentRuntimePresenter->>AgentRuntimePresenter: buildMemorySpanFromTape()<br/>(hadToolUse, visibleTextChars)
  AgentRuntimePresenter->>AgentRuntimePresenter: admission gate<br/>(tool use OR large delta OR sufficient chars)
  AgentRuntimePresenter->>ExtractionPipeline: extractAndStore(spanText)
  ExtractionPipeline->>ExtractionPipeline: buildExtractionPrompt(AGENT_MEMORY_CATEGORIES)
  ExtractionPipeline->>ExtractionPipeline: parseMemoryCandidates()<br/>(validate category, cap task_outcome)
  ExtractionPipeline->>MemoryPresenter: writeMemoriesSync(candidates)
  MemoryPresenter->>MemoryPresenter: normalizeMemoryCandidate()<br/>(derive kind, clamp importance floor)
  MemoryPresenter->>MemoryPresenter: coordinateWrite()<br/>(ADD / UPDATE / SUPERSEDE / CHALLENGE)
  MemoryPresenter->>MemoryPresenter: applyContentUpdate(category)<br/>(propagate if canCarryCategory && row.category === null)
  MemoryPresenter->>AgentMemoryTable: insert / updateContent(category)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• ThinkInAIXYZ/deepchat#1796: Modifies the same parseMemoryCandidates contract and span-handling in memoryPresenter/extraction.ts and the runtime presenter, making it directly intertwined with this PR's category-aware extraction rewrite.

Suggested reviewers

• zerob13

Poem

🐇 Hop, hop, the rabbit sorts with glee,
Five little buckets for each memory!
task_outcome, heuristic, facts so bright,
Each tagged and floored with importance just right.
The forget now soft-archives — vectors remain,
And category badges bloom on the UI lane! 🏷️

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.68% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title "feat(memory): add task-aware agentic memory" accurately and specifically summarizes the primary change: introducing task-aware memory features with agentic categorization to the memory system.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/task-aware-agentic-memory

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main/presenter/memoryPresenter/extraction.ts`:
- Around line 92-99: The issue is that invalid categories are being pushed to
the candidates array even when they fail the isAgentMemoryCategory validation.
Currently, the isAgentMemoryCategory check is only used to guard against
duplicate task_outcome entries, but the category variable is still pushed to
candidates regardless of whether it's a valid category or not. Fix this by
normalizing the category to undefined whenever isAgentMemoryCategory returns
false, so that only valid categories conforming to the five-category contract
are included in the candidates array when candidates.push is called.

In `@src/main/presenter/memoryPresenter/index.ts`:
- Around line 1551-1553: The audit logging at lines 1575-1579 is recording the
raw candidate field values before any normalization occurs, but the write path
normalizes these values (such as category-driven kind coercion or dropping
invalid categories to null). This causes audit records to disagree with what was
actually persisted. Refactor the audit logging to record the final normalized
values that are actually written to storage instead of the raw candidate fields,
ensuring the audit trail accurately reflects what was persisted.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 76818d1d-5adf-4306-8686-06519dbe2895

📥 Commits

Reviewing files that changed from the base of the PR and between 4545791 and 17527cc.

📒 Files selected for processing (50)

• docs/architecture/agent-memory-system/spec.md
• resources/skills/memory-management/SKILL.md
• src/main/presenter/agentRuntimePresenter/index.ts
• src/main/presenter/index.ts
• src/main/presenter/memoryPresenter/decision.ts
• src/main/presenter/memoryPresenter/extraction.ts
• src/main/presenter/memoryPresenter/index.ts
• src/main/presenter/memoryPresenter/types.ts
• src/main/presenter/sqlitePresenter/schemaCatalog.ts
• src/main/presenter/sqlitePresenter/tables/agentMemory.ts
• src/main/presenter/toolPresenter/agentTools/agentMemoryTools.ts
• src/main/presenter/toolPresenter/runtimePorts.ts
• src/main/routes/index.ts
• src/renderer/settings/components/MemoryManagerPanel.vue
• src/renderer/src/i18n/da-DK/settings.json
• src/renderer/src/i18n/de-DE/settings.json
• src/renderer/src/i18n/en-US/settings.json
• src/renderer/src/i18n/es-ES/settings.json
• src/renderer/src/i18n/fa-IR/settings.json
• src/renderer/src/i18n/fr-FR/settings.json
• src/renderer/src/i18n/he-IL/settings.json
• src/renderer/src/i18n/id-ID/settings.json
• src/renderer/src/i18n/it-IT/settings.json
• src/renderer/src/i18n/ja-JP/settings.json
• src/renderer/src/i18n/ko-KR/settings.json
• src/renderer/src/i18n/ms-MY/settings.json
• src/renderer/src/i18n/pl-PL/settings.json
• src/renderer/src/i18n/pt-BR/settings.json
• src/renderer/src/i18n/ru-RU/settings.json
• src/renderer/src/i18n/tr-TR/settings.json
• src/renderer/src/i18n/vi-VN/settings.json
• src/renderer/src/i18n/zh-CN/settings.json
• src/renderer/src/i18n/zh-HK/settings.json
• src/renderer/src/i18n/zh-TW/settings.json
• src/shared/contracts/routes/memory.routes.ts
• src/shared/types/agent-memory.ts
• src/shared/types/index.d.ts
• test/main/presenter/agentMemoryTable.test.ts
• test/main/presenter/agentRuntimePresenter/agentRuntimePresenter.test.ts
• test/main/presenter/fakes/memoryFakes.ts
• test/main/presenter/memoryAdd.test.ts
• test/main/presenter/memoryDecision.test.ts
• test/main/presenter/memoryExtraction.test.ts
• test/main/presenter/memoryPresenter.test.ts
• test/main/presenter/memoryRetrieval.eval.test.ts
• test/main/presenter/skillPresenter/discoveryWorker.test.ts
• test/main/presenter/sqlitePresenter.test.ts
• test/main/presenter/toolPresenter/agentTools/agentMemoryTools.test.ts
• test/main/routes/memoryDto.test.ts
• test/renderer/components/MemoryManagerDialog.test.ts