cogmem 3.6.5 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.7.0
+
+- Upgraded Memory Atlas into a multi-dimensional navigation graph: canonical episodes and raw events exist once, while time, topic, issue, entity, session/thread, memory-kind, and action-kind facets connect to them with typed edges.
+- Added deterministic episode title and one-line summary generation for Atlas cards, preserving the original long summary in metadata and marking low-confidence titles for review.
+- Added facet query planning for day/month/year, topic, issue, and entity cues, including strict facet intersection, canonicalId dedupe, matched facet/path explanations, and explicit relaxation traces.
+- Added agent-facing Atlas `cards[]` on graph search/explore with `displayTitle`, `oneLineSummary`, `canonicalId`, `matchedFacets`, `matchedPaths`, `relatedButNotSelected`, and source drill-down locators.
+- Extended Atlas cards to timeline results and CLI recall JSON, shared relaxation behavior across graph search/explore/timeline, and made broad “记忆黑盒” recall select the initial Memory Context/sourceContext discussion while listing later graph/runtime and Atlas readability issues as related side context.
+- Renamed the live Atlas projection to `memory_atlas.v2` with 3.7 schema metadata while still consuming legacy `memory_atlas.v1` dirty triggers, so upgraded 3.6.5 databases rebuild the multi-facet projection instead of trusting stale clean state.
+- Integrated facet graph cards into `historical_discussion` recall so OpenClaw/Hermes agents can explain selected memories while still grounding answers in Raw Ledger source locators.
+- Updated OpenClaw plugin 0.7.0 and its generated bridge to preserve strict facet matches through Context Cortex planning and to include selected cards, matched facets/paths, related-but-not-selected side context, and relaxation traces in both volatile recall and Atlas context blocks.
+- Updated README, Memory Atlas docs, OpenClaw/Hermes skills, AGENTS runbooks, and operations references with npm-first install/update flow and the 3.7.0 multi-facet Atlas command playbook.
+
 ## 3.6.5
 
 - Added `cogmem memory plan` as a read-only agent operations summary with queue state, blocking/non-blocking next actions, Dream backlog hints, and vector fallback state.

package/MEMORY_ATLAS.md

@@ -1,4 +1,4 @@
-# Memory Atlas v1
+# Memory Atlas v2
 
 Memory Atlas lets an agent inspect what Cogmem remembers before it chooses a precise recall or Raw Ledger drilldown. It is a rebuildable navigation projection, not a new source of truth.
 
@@ -6,19 +6,30 @@ Memory Atlas lets an agent inspect what Cogmem remembers before it chooses a pre
 
 Atlas projects existing project-scoped records into these node kinds:
 
-- `project`, `topic`, `entity`, `cluster`, `episode`, `belief`, `action`, and `time`.
-- Raw `event` nodes appear only for explicit evidence navigation.
+- Canonical content nodes: `episode`, `raw_event`, `cluster`, `belief`, `action`, `decision`, and `correction`.
+- Facet nodes: `time`, `topic`, `issue`, `entity`, `session`, `thread`, `memoryKind`, and `actionKind`.
 - Action frames are extracted deterministically from raw user evidence and link actor, target, action kind, time, topic, project, and evidence.
 
-Existing memory edges remain canonical. Atlas adds derived navigation edges such as `TARGETS`, `OCCURRED_IN`, and evidence drilldowns without changing the underlying belief or binding graph.
+Existing memory edges remain canonical. Atlas adds derived navigation edges such as `OCCURRED_ON`, `OCCURRED_IN`, `ABOUT_TOPIC`, `PART_OF_ISSUE`, `INVOLVES_ENTITY`, `IN_SESSION`, `IN_THREAD`, and `HAS_EVIDENCE` without changing the underlying belief or binding graph. The 3.7.0 offline curator automatically proposes only bounded `SAME_ISSUE`, `FOLLOWS_UP`, and weak `RELATED_TO` episode relations; stronger relations such as `REFINES`, `CORRECTS`, `CONTRADICTS`, and `SUPERSEDES` remain reserved for explicit evidence-bearing governance/binding flows.
+
+This is not a copied tree. One episode exists once as `episode:<id>`. A day, topic, issue, entity, session, memory kind, or action kind is only a facet entrance:
+
+```text
+time:2026-06-06 ───────┐
+topic:.../memory-blackbox ─┼──> episode:<id>
+issue:memory-context-blackbox ─┘
+episode:<id> ──HAS_EVIDENCE──> raw_event:<eventId>
+```
+
+Search and explore output dedupe by `canonicalId`. When a canonical episode is reached through several facet paths, the result appears once with all `matchedFacets` and `matchedPaths`.
 
 ## Agent workflow
 
 1. Use `graph_overview` when the user asks what is remembered.
-2. Use `graph_explore` for broad history, project-state, or relationship questions.
-3. Use `graph_search` when a topic/entity/cluster is already known.
+2. Use `graph_explore` for broad history, project-state, relationship, or multi-facet questions.
+3. Use `graph_search` when a topic/entity/cluster is already known and no expansion is needed.
 4. Use `graph_node`, `graph_neighbors`, `graph_path`, or `graph_timeline` to narrow the graph. Timeline applies the available facets to any timestamped Atlas nodes; action frames are an optional richer result, not a requirement.
-5. Use returned `eventId` values and `cogmem memory show` before quoting exact source text.
+5. Use returned `sourceLocator.command` or event IDs with `cogmem memory show` before quoting exact source text.
 6. Use normal `cogmem_recall` for a direct factual memory question.
 
 Atlas summaries are `hint_only_not_evidence` in effect. Project scope, raw evidence ownership, and governance still decide what may be claimed as durable memory.
@@ -27,16 +38,41 @@ Atlas summaries are `hint_only_not_evidence` in effect. Project scope, raw evide
 
 Activation controls default visibility, not existence. Maintenance decays Atlas activation deterministically; an explicit `cogmem_graph_touch` raises nodes that the agent actually used. Read-only overview/search/explore calls do not change ranking. A query can still surface a cold node when its available facets match.
 
-Facets include project, time, topic, person/object, event, decision, correction, goal, preference, plan, action, and ordinary keywords. The engine combines the facets actually present in the message, similar to filtering multiple columns in a table. It does not require the fixed combination entity + time + action.
+Facets include project, day/month/year, topic, issue, entity/person/project, session/thread, memory kind, action kind, and ordinary keywords. The engine combines the facets actually present in the message, similar to filtering multiple columns in a table. It does not require the fixed combination entity + time + action.
 
 For example, all of these can revive cold memory:
 
+- `6月6号聊过什么`
+- `6月6号关于记忆黑盒聊过什么`
+- `记忆黑盒后来有没有继续讨论`
+- `memory graph 卡死的问题修了吗`
 - `2025 Hermes 的决策`
 - `在留更新里被纠正过的计划`
 - `去年 OpenClaw 失败的配置事件`
 - `餐车 POS 项目中关于库存的偏好`
 
-Exact constraints may bypass the visibility floor. They never bypass `projectId`, evidence validation, or traversal limits.
+Exact constraints may bypass the visibility floor. They never bypass `projectId`, evidence validation, or traversal limits. If strict intersection is empty, Atlas may relax day to parent month or issue to parent topic, but JSON must include `relaxationTrace`; it must not silently substitute a nearby memory.
+
+`graph-search` and `graph-explore` include agent-facing `cards` when canonical episodes match:
+
+```json
+{
+  "canonicalId": "episode:episode-xxx",
+  "displayTitle": "CogMem Memory Context 黑盒与原文下钻",
+  "oneLineSummary": "用户指出注入的 CogMem Memory Context 像黑盒，需要能从摘要下钻到原始对话。",
+  "matchedFacets": [
+    { "type": "time", "value": "2026-06-06" },
+    { "type": "topic", "value": "PROJECT/Cogmem/memory-blackbox" }
+  ],
+  "matchedPaths": [],
+  "relatedButNotSelected": [],
+  "sourceLocator": {
+    "command": "cogmem memory show --event evt-... --before 2 --after 2 --json"
+  }
+}
+```
+
+Agents should prefer `cards` over raw node labels for historical discussion because cards preserve the canonical episode, match reason, and drilldown command.
 
 ## Bounds
 
@@ -58,6 +94,7 @@ BrainEval release fixtures fail closed on Atlas project isolation, node/hop boun
 cogmem memory graph --project <id> --json
 cogmem memory graph-search --project <id> --query <query> --json
 cogmem memory graph-explore --project <id> --query <query> --json
+cogmem memory graph-explore --project openclaw --query "6月6号关于记忆黑盒聊过什么" --json
 cogmem memory graph-node --project <id> --id <node-id> --json
 cogmem memory graph-neighbors --project <id> --id <node-id> --hops 1 --json
 cogmem memory graph-path --project <id> --from <node-id> --to <node-id> --json
@@ -98,4 +135,4 @@ Upgrade an existing 3.5.2 database with:
 cogmem migrate --yes --backup --json
 ```
 
-Migration 0025 creates and backfills the disposable projection. Migration 0026 adds exact memory-kind metadata, projection health, and candidate-review audit state. Migration 0027 corrects 3.6.0-upgraded databases by marking Atlas projections dirty until the real action/time rebuild runs. A 3.5.2 schema-24 database, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database reaches the 3.6.1 schema-27 state with the same command. `cogmem memory tick` refreshes only dirty projects, records rebuild errors, prunes old access telemetry, and decays navigation activation without starting a daemon.
+Migration 0025 creates and backfills the disposable projection. Migration 0026 adds exact memory-kind metadata, projection health, and candidate-review audit state. Migration 0027 corrects 3.6.0-upgraded databases by marking Atlas projections dirty until the real action/time rebuild runs. Cogmem 3.7.0 keeps the projection-first schema and adds facet nodes, canonical cards, issue hints, and episode relation edges during Atlas rebuild/maintenance. `cogmem memory tick` refreshes only dirty projects, records rebuild errors, prunes old access telemetry, and decays navigation activation without starting a daemon.

package/README.md

@@ -11,7 +11,7 @@ It is not a knowledge-base app, a note-taking app, a vector RAG wrapper, an Obsi
 
 ## Status
 
-Current version: `3.6.5`
+Current version: `3.7.0`
 
 Distribution: npm registry. GitHub remains the source mirror and hosts this installer, but package install and upgrade resolve `cogmem` from npm by default.
 
@@ -89,7 +89,7 @@ Memory Binding
   CPU-canonicalized raw-event bindings to stable entity/topic paths, claim-key clusters, and activation-aware graph edges for source-anchored organization before fact promotion.
 
 Memory Atlas
-  A bounded, project-scoped content map over topics, entities, clusters, episodes, beliefs, actions, time, and their source-anchored relations. Agents use it to inventory, filter, navigate, and then drill down to Raw Ledger evidence.
+  A bounded, project-scoped, multi-dimensional memory navigation graph. Canonical episodes and raw evidence exist once; time, topic, issue, entity, session, memory-kind, and action-kind facets connect to them with typed edges. Agents use it to intersect facets, dedupe by canonicalId, explain why a memory matched, and then drill down to Raw Ledger evidence.
 
 User-Shaped Topic Ontology
   A stable memory-class skeleton plus project-scoped topic names, aliases, parent paths, relations, and reversible audit operations learned from explicit user language.
@@ -229,7 +229,7 @@ cogmem migrate --dry-run --json
 
 For a manual migration, run `cogmem migrate --yes --backup`. The migration runner adopts the existing `_meta.schema_version`, applies only later idempotent migrations, preserves Raw Ledger rows, and creates a timestamped, transaction-consistent standalone database backup before changing an on-disk database. The backup includes committed SQLite WAL pages instead of copying only the main database file.
 
-Upgrade a 3.5.2 database, a 3.6.0 database, or a pre-release schema-25 test database into the 3.6.5 schema set with one command:
+Upgrade a 3.5.2 database, a 3.6.x database, or a pre-release schema-25 test database into the current 3.7.0 schema and projection set with one command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -276,9 +276,9 @@ For a host timer, call `dream tick`; the timer only wakes the sealed-episode sch
 cogmem dream tick --project my-agent --mode auto --max-episodes 10 --json
 ```
 
-Raw events are always written first. `KernelAgentMemoryBackend` and OpenClaw plugin 0.6.3 assemble live turns automatically. The foreground hook uses deterministic rules and previous assistant/user context; background import and repair paths may use the advisory hybrid classifier. Advisory output is allow-listed and cannot directly mutate durable memory. Unknown turns now fail closed as ambiguous. Continuation requires explicit continuation language or project/topic/entity/semantic overlap; Cogmem does not route domains with an expanding hard-coded keyword dictionary.
+Raw events are always written first. `KernelAgentMemoryBackend` and OpenClaw plugin 0.7.0 assemble live turns automatically. The foreground hook uses deterministic rules and previous assistant/user context; background import and repair paths may use the advisory hybrid classifier. Advisory output is allow-listed and cannot directly mutate durable memory. Unknown turns now fail closed as ambiguous. Continuation requires explicit continuation language or project/topic/entity/semantic overlap; Cogmem does not route domains with an expanding hard-coded keyword dictionary.
 
-Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and skip legacy empty Dream jobs so one bad imported episode cannot block the queue. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
+Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. Cogmem skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
 
 User-shaped topic state is project-scoped. Explicit user operations become active and auditable; model-proposed topics, aliases, and relations remain candidates. Use MCP `cogmem_topic_list` to inspect nodes, `cogmem_topic_operate` to create, rename, alias, move, merge, split, or relate topics, and `cogmem_topic_rollback` to reverse an audited operation. Alias collisions fail closed as `needs_review`; applications can also call `TopicGovernance.rollback()` through the public API.
 
@@ -304,21 +304,24 @@ cogmem memory review --project my-agent --id <candidate-id> --action approve --a
 
 `cogmem memory map` remains the system anatomy map. Memory Atlas is the content map. It does not replace recall or create a second fact store; it projects existing topics, entities, clusters, episodes, beliefs, action frames, time buckets, bindings, and evidence into a bounded navigation surface.
 
+In 3.7.0, Atlas is a multi-dimensional navigation graph rather than a folder tree. A remembered episode has one canonical node such as `episode:<id>`. Time, topic, issue, entity, session/thread, memory-kind, and action-kind nodes are facet entrances connected to that canonical episode with typed edges. Results dedupe by `canonicalId` and explain `matchedFacets` plus `matchedPaths`.
+
 ```bash
 cogmem memory graph --project my-agent --json
 cogmem memory graph-search --project my-agent --query "Hermes" --json
 cogmem memory graph-explore --project my-agent --query "去年我让你对 Hermes 做过什么" --json
+cogmem memory graph-explore --project openclaw --query "6月6号关于记忆黑盒聊过什么" --json
 cogmem memory graph-node --project my-agent --id "entity:<id>" --json
 cogmem memory graph-neighbors --project my-agent --id "entity:<id>" --hops 2 --json
 cogmem memory graph-path --project my-agent --from "entity:<id>" --to "action:<id>" --json
 cogmem memory graph-timeline --project my-agent --query "2025 Hermes 的决策和修复" --json
 ```
 
-Atlas filtering is not limited to entity + time + action. The query compiler combines whichever facets are actually present, such as project, time range, topic, person/object, event, decision, correction, goal, preference, plan, action, and ordinary keywords. Exact multi-facet matches may surface cold nodes even when their activation has decayed. Project scope and raw evidence validation are never bypassed.
+Atlas filtering is not limited to entity + time + action. The facet planner combines whichever facets are actually present, such as project, day/month/year, topic, issue, entity/person/project, session/thread, memory kind, action kind, and ordinary keywords. Strict multi-facet matches may surface cold nodes even when their activation has decayed. If strict intersection is empty, JSON includes `relaxationTrace` instead of silently pretending an exact match existed. Project scope and raw evidence validation are never bypassed.
 
 Defaults are 8 nodes, one hop, and two evidence IDs per node. Hard limits are 30 nodes, two hops, ten evidence IDs, six path hops, and 2,000 visited nodes. Raw excerpts are omitted unless `--include-evidence` or `includeEvidence: true` is explicit. `evidenceTotal` reports all known evidence while `evidenceReturned` reports the bounded payload. Every returned evidence item carries an `eventId` and a `cogmem memory show` drilldown command.
 
-In 3.6.5, Atlas search and explore evidence also carries `sourceLocator.command` and `sourceLocator.contextCommand`. Agents should run that locator before quoting exact wording, before claiming a historical topic is absent, or when a graph summary looks relevant but underspecified.
+Atlas search and explore return agent-facing `cards` for canonical episodes. Each card includes `canonicalId`, `displayTitle`, `oneLineSummary`, `matchedFacets`, `matchedPaths`, `relatedButNotSelected`, and `sourceLocator.command` / `sourceLocator.contextCommand` when evidence is available. Agents should run that locator before quoting exact wording, before claiming a historical topic is absent, or when a graph summary looks relevant but underspecified.
 
 Atlas reads do not brighten everything they display. MCP graph queries are read-only/idempotent; call `cogmem_graph_touch` only after the agent actually uses selected nodes. Maintenance decays activation, refreshes dirty projections only, and prunes old access telemetry.
 
@@ -357,7 +360,7 @@ Operational cost classes:
 
 Never overlap maintenance writers against one database. Wait for each command to exit, use returned `durationMs`, backlog, and failure details to set the next interval, and keep routine status/candidate inspection on the read-only path. A `vectors` count of zero is not by itself a failure: `memory status --json` includes `vectorState.recallAvailableWithoutVectors` and the active fallback status.
 
-`memory bind` backfills Memory Binding for raw user events written outside the agent turn path, including imported OpenClaw/Hermes history and adapter-written raw events. In 3.6.5 it scans by Raw Ledger cursor rather than only the latest page. Use `--since <globalSeq>` to resume from a known ledger sequence.
+`memory bind` backfills Memory Binding for raw user events written outside the agent turn path, including imported OpenClaw/Hermes history and adapter-written raw events. It scans by Raw Ledger cursor rather than only the latest page. Use `--since <globalSeq>` to resume from a known ledger sequence.
 
 `memory map` includes Memory Binding and Graph Recall counters. Bindings attach valuable user raw events to stable topic/entity paths before any fact promotion, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down. Correction events create explicit correction edges and review flags instead of poisoning the active cluster. Treat bindings, clusters, and graph edges as organization hints, not as verified long-term facts.
 
@@ -378,7 +381,7 @@ cogmem strategy plan --project hermes --query "我当时的原话是什么？" -
 cogmem strategy outcomes --project hermes --json
 ```
 
-OpenClaw plugin 0.6.3 skips Cogmem entirely for greetings, uses only session state/turn bridge for short continuations, and applies Strategy Cortex before full recall. Navigation turns use one bridge/kernel lifecycle for Atlas exploration, evidence-bearing node/timeline drill-down, and recall. The bounded volatile `<COGMEM_MEMORY_ATLAS>` block includes evidence event IDs and drill-down commands; OpenClaw does not need MCP for this path.
+OpenClaw plugin 0.7.0 skips Cogmem entirely for greetings, uses only session state/turn bridge for short continuations, and applies Strategy Cortex before full recall. Navigation turns use one bridge/kernel lifecycle for Atlas exploration, evidence-bearing node/timeline drill-down, and recall. The bounded volatile `<COGMEM_MEMORY_ATLAS>` block includes selected memory cards, matched facets, matched paths, related-but-not-selected cards, evidence event IDs, and drill-down commands; OpenClaw does not need MCP for this path.
 
 `cogmem connect openclaw --auto --force --json` and `cogmem connect hermes --auto --force --json` now return structured `nextSteps`. Only `nextSteps` with `actor: "agent"` and `safeForAutomation: true` are mirrored into `nextCommands`. Interactive setup, gateway restart, and Hermes reload remain visible as operator/host steps but are intentionally absent from `nextCommands`.
 
@@ -790,7 +793,7 @@ npm pack --dry-run --json
 npm publish --dry-run --access public
 ```
 
-Create a GitHub Release from the matching version tag, for example `v3.6.5`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
+Create a GitHub Release from the matching version tag, for example `v3.7.0`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
 
 Publish manually only for emergency fallback:
 

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,11 @@
-# cogmem 3.6.5 Release Checklist
+# cogmem 3.7.0 Release Checklist
 
 This release is distributed through the npm registry. GitHub remains the source and review mirror.
 
 ## Required Metadata
 
 - `package.json` name is `cogmem`.
-- `package.json` version is `3.6.5`.
+- `package.json` version is `3.7.0`.
 - `package.json` has `publishConfig.access = public`.
 - Public export `.` points to `dist/public.js` and `dist/public.d.ts`.
 - Internal subpath `./internal` exists only as an explicit advanced subpath.
@@ -61,7 +61,8 @@ MCP `tools/list` includes strategy, episode append/import/status/seal/repair, to
 - README and skills explain Raw Ledger-first episode assembly, soft/hard sealing, explicit conditional Dream ticks, raw-event evidence grounding, repair/retry, and hookless Hermes MCP/import usage.
 - README and skills give the full post-import maintenance sequence: status, episode status, Dream status, bounded Dream tick, candidate listing, govern candidate, needs-confirmation listing, explicit review, and recall verification.
 - README and skills explain that 3.6.4+ skips empty imported episode boundaries and legacy empty Dream jobs instead of letting them abort `dream tick`.
-- README and skills explain the 3.6.5 agent operations protocol: `memory plan` for next actions, default grouped `memory candidates --json`, `memory list --since/--until/--order`, historical-discussion recall intent, Atlas evidence `sourceLocator`, and cursor-based `memory bind`.
+- README and skills explain the 3.7.0 agent operations protocol: `memory plan` for next actions, default grouped `memory candidates --json`, `memory list --since/--until/--order`, historical-discussion recall intent, Atlas canonical cards, `matchedFacets`, `relatedButNotSelected`, `relaxationTrace`, Atlas evidence `sourceLocator`, and cursor-based `memory bind`.
+- README, `MEMORY_ATLAS.md`, and installed skills explain the multi-dimensional Atlas model: a canonical episode/raw event exists once, facet nodes connect through typed edges, query results intersect facets, and display/injection dedupes by `canonicalId`.
 - `connect openclaw|hermes --json` documents structured `nextSteps`; `nextCommands` must contain only agent-safe, non-interactive commands and must not include `cogmem init`, `cogmem-init`, gateway restart, or Hermes reload.
 - README and skills document `cogmem mcp` as the preferred MCP server command for new configs while preserving `cogmem-mcp` as a compatibility bin.
 - README and skills explain CPU foreground versus hybrid background classification, contextual short replies, registry-aware topic boundaries, safe reopen, semantic-summary non-evidence status, per-job Dream modes/failures, stable import identity, and schema migration 24.
@@ -93,7 +94,7 @@ npm publish --dry-run --access public
 
 The pack dry-run must include built public API files, CLI files, examples, docs, and `install.sh`. It must not include local databases or machine-specific files.
 
-After verification, create a GitHub Release from the matching version tag, for example `v3.6.5`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
+After verification, create a GitHub Release from the matching version tag, for example `v3.7.0`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
 
 Emergency manual fallback:
 

package/dist/agent/AgentMemoryBackend.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryKernel, MemoryKernelNavigationResult } from '../factory.js';
+import type { MemoryAtlasCard, MemoryAtlasRelatedCard, MemoryAtlasRelaxationStep } from '../atlas/MemoryAtlasTypes.js';
 import { type MemoryEventCharRange, type MemoryEventSourceRange, type SourceContextWindowMetadata } from '../recall/SourceContextMetadata.js';
 import type { BeliefRecord, MemoryEvent } from '../types/index.js';
 import type { StrategyRetrievalPolicy } from '../strategy/StrategyCapsule.js';
@@ -152,6 +153,10 @@ export interface AgentRecallItem {
     text: string;
     projectId?: string;
     topicPath?: string;
+    canonicalId?: string;
+    displayTitle?: string;
+    matchedFacets?: MemoryAtlasCard['matchedFacets'];
+    matchedPaths?: MemoryAtlasCard['matchedPaths'];
     tags: string[];
     source?: string;
     sourceType?: 'compiled_memory' | 'imported_summary' | 'raw_ledger' | 'raw_ledger_session';
@@ -170,12 +175,15 @@ export interface AgentRecallResult {
     runtime?: NonNullable<MemoryKernelNavigationResult['navigation']>['runtime'];
     fallbackUsed: boolean;
     queryPlan?: AgentRecallQueryPlan;
+    atlasCards?: MemoryAtlasCard[];
+    relatedButNotSelected?: MemoryAtlasRelatedCard[];
+    relaxationTrace?: MemoryAtlasRelaxationStep[];
     /** Present on all kernel-produced results. Optional for source compatibility with external result mocks. */
     decisionTrace?: AgentRecallDecisionTrace;
 }
 export interface AgentRecallDecisionTrace {
     version: 'agent_recall_decision.v1';
-    selectedLane: 'graph' | 'compiled' | 'brain_fallback' | 'raw_ledger' | 'mixed' | 'none';
+    selectedLane: 'facet_graph_raw_ledger' | 'graph' | 'compiled' | 'brain_fallback' | 'raw_ledger' | 'mixed' | 'none';
     reason: 'previous_session' | 'forensic_quote' | 'historical_discussion' | 'graph_selected' | 'raw_cue_match_preferred' | 'compiled_cue_match' | 'brain_fallback_selected' | 'raw_ledger_only' | 'no_recall_evidence';
     candidateCounts: {
         graph: number;
@@ -247,6 +255,8 @@ export declare class KernelAgentMemoryBackend {
     private recallPreviousSession;
     private recallForensicQuote;
     private recallHistoricalDiscussion;
+    private facetGraphItemsForQuery;
+    private toAgentRecallItemFromAtlasCard;
     private recallForensicAnchor;
     private searchRawEventsByQueryPlan;
     private rawLedgerFallbackItemsForQuery;
@@ -257,6 +267,8 @@ export declare class KernelAgentMemoryBackend {
     private recallCueTerms;
     private itemSearchableText;
     private mergeRecallItems;
+    private mergeHistoricalRecallItems;
+    private compiledItemsForHistoricalQuery;
     private dedupeRawEventsByTurnPreferUser;
     private expandRawSearchTexts;
     private findPreviousSessionId;

package/dist/agent/AgentMemoryBackend.js

@@ -498,41 +498,82 @@ export class KernelAgentMemoryBackend {
         const allowsGraph = laneAllowed(query.retrievalPolicy, 'graph');
         const allowsCompiled = laneAllowed(query.retrievalPolicy, 'compiled');
         const allowsRawSource = laneAllowed(query.retrievalPolicy, 'raw_source');
+        const facetResult = allowsGraph ? this.facetGraphItemsForQuery(query, limit) : { items: [], cards: [], relatedButNotSelected: [], relaxationTrace: [] };
+        const facetItems = allowsRawSource ? facetResult.items : [];
         const graphItems = allowsGraph ? this.memoryBindingGraphItemsForQuery(query, queryPlan, limit) : [];
         const rawItems = allowsRawSource ? this.rawLedgerFallbackItemsForQuery(queryPlan, query, Math.max(limit * 2, 10)) : [];
-        const retrievalLimit = Math.max(limit * 4, 24);
         const compiledItems = allowsCompiled
-            ? this.filterAgentEvidence(this.kernel.navigateMemory(queryPlan.primarySearchText, {
-                projectId: query.projectId,
-                limit: retrievalLimit,
-                startTime: query.startTime,
-                endTime: query.endTime,
-            }).rawEvidence, query.agentId, query.collection, query.excludeSessionId)
-                .slice(0, limit)
-                .map((neuron) => this.toAgentRecallItem(neuron))
+            ? this.compiledItemsForHistoricalQuery(queryPlan, query, limit)
             : [];
-        const items = this.mergeRecallItems(rawItems, this.mergeRecallItems(graphItems, compiledItems, limit), limit);
-        const selectedLane = rawItems.length > 0
-            ? 'raw_ledger'
-            : graphItems.length > 0
-                ? 'graph'
-                : compiledItems.length > 0
-                    ? 'compiled'
-                    : 'none';
+        const items = this.mergeHistoricalRecallItems(facetItems, rawItems, graphItems, compiledItems, limit);
+        const selectedLane = facetItems.length > 0
+            ? 'facet_graph_raw_ledger'
+            : rawItems.length > 0
+                ? 'raw_ledger'
+                : graphItems.length > 0
+                    ? 'graph'
+                    : compiledItems.length > 0
+                        ? 'compiled'
+                        : 'none';
         return {
-            recallMode: rawItems.length > 0 ? 'raw_ledger_fallback' : 'brain_recall_fallback',
+            recallMode: facetItems.length > 0 || rawItems.length > 0 ? 'raw_ledger_fallback' : 'brain_recall_fallback',
             items,
             fallbackUsed: true,
             queryPlan,
+            atlasCards: facetResult.cards,
+            relatedButNotSelected: facetResult.relatedButNotSelected,
+            relaxationTrace: facetResult.relaxationTrace,
             decisionTrace: recallDecisionTrace(selectedLane, 'historical_discussion', {
-                graph: graphItems.length,
+                graph: graphItems.length + facetItems.length,
                 navigation: compiledItems.length,
                 scopedNavigation: compiledItems.length,
                 brainFallback: 0,
-                rawLedger: rawItems.length,
+                rawLedger: rawItems.length + facetItems.length,
             }, items.length),
         };
     }
+    facetGraphItemsForQuery(query, limit) {
+        try {
+            const atlas = this.kernel.graphExplore(query.query, {
+                projectId: query.projectId,
+                limit,
+                includeEvidence: true,
+                evidenceLimit: 2,
+                refresh: true,
+                staleOk: true,
+            });
+            const cards = (atlas.cards ?? []).slice(0, limit);
+            const items = cards.map((card) => this.toAgentRecallItemFromAtlasCard(card, query)).filter((item) => Boolean(item));
+            const relatedButNotSelected = cards.flatMap((card) => card.relatedButNotSelected ?? []).slice(0, 8);
+            return { items, cards, relatedButNotSelected, relaxationTrace: atlas.relaxationTrace ?? [] };
+        }
+        catch {
+            return { items: [], cards: [], relatedButNotSelected: [], relaxationTrace: [] };
+        }
+    }
+    toAgentRecallItemFromAtlasCard(card, query) {
+        const eventId = card.sourceLocator?.eventId ?? card.evidenceEventIds[0];
+        const sourceContext = eventId ? this.toAgentSourceContext(eventId) : undefined;
+        const anchorEvent = sourceContext?.event;
+        return {
+            id: `facet:${card.canonicalId}`,
+            text: [card.displayTitle, card.oneLineSummary].filter(Boolean).join(': '),
+            projectId: query.projectId,
+            topicPath: card.parentTopics[0],
+            canonicalId: card.canonicalId,
+            displayTitle: card.displayTitle,
+            matchedFacets: card.matchedFacets,
+            matchedPaths: card.matchedPaths,
+            tags: ['facet_graph', card.eventKind, card.issueType].filter((tag) => Boolean(tag)),
+            source: 'memory_atlas',
+            sourceType: 'raw_ledger',
+            sourceAnchor: anchorEvent ? this.toAgentSourceAnchorFromContextEvent(anchorEvent) : eventId ? { eventId } : undefined,
+            sourceContext,
+            confidence: Math.min(1, 0.7 + card.matchedFacets.length * 0.08),
+            whyMatched: card.whyMatched,
+            canAnswerExactQuote: Boolean(sourceContext),
+        };
+    }
     recallForensicAnchor(query, limit) {
         if (!query.anchorEventId)
             return [];
@@ -698,15 +739,55 @@ export class KernelAgentMemoryBackend {
         const out = [];
         const seen = new Set();
         for (const item of [...primary, ...secondary]) {
-            if (seen.has(item.id))
+            const keys = [item.canonicalId, item.sourceAnchor?.eventId, item.id].filter((value) => Boolean(value));
+            if (keys.some((key) => seen.has(key)))
                 continue;
-            seen.add(item.id);
+            for (const key of keys)
+                seen.add(key);
             out.push(item);
             if (out.length >= limit)
                 break;
         }
         return out;
     }
+    mergeHistoricalRecallItems(facetItems, rawItems, graphItems, compiledItems, limit) {
+        const merged = this.mergeRecallItems(facetItems, this.mergeRecallItems(rawItems, this.mergeRecallItems(graphItems, compiledItems, limit), limit), limit);
+        if (merged.some((item) => item.sourceType === 'imported_summary'))
+            return merged;
+        const importedSupport = compiledItems.find((item) => item.sourceType === 'imported_summary');
+        if (!importedSupport)
+            return merged;
+        const withoutDuplicate = merged.filter((item) => item.id !== importedSupport.id && item.sourceAnchor?.eventId !== importedSupport.sourceAnchor?.eventId);
+        if (withoutDuplicate.length < limit)
+            return [...withoutDuplicate, importedSupport];
+        return [...withoutDuplicate.slice(0, Math.max(0, limit - 1)), importedSupport];
+    }
+    compiledItemsForHistoricalQuery(queryPlan, query, limit) {
+        const retrievalLimit = Math.max(limit * 4, 24);
+        const out = [];
+        const seen = new Set();
+        for (const searchText of uniqueNonEmpty([queryPlan.primarySearchText, ...queryPlan.searchTexts, queryPlan.originalQuery])) {
+            const rawEvidence = this.kernel.navigateMemory(searchText, {
+                projectId: query.projectId,
+                limit: retrievalLimit,
+                startTime: query.startTime,
+                endTime: query.endTime,
+            }).rawEvidence;
+            const items = this.filterAgentEvidence(rawEvidence, query.agentId, query.collection, query.excludeSessionId)
+                .map((neuron) => this.toAgentRecallItem(neuron));
+            for (const item of items) {
+                const key = item.id || item.sourceAnchor?.eventId;
+                if (key && seen.has(key))
+                    continue;
+                if (key)
+                    seen.add(key);
+                out.push(item);
+                if (out.length >= limit)
+                    return out;
+            }
+        }
+        return out;
+    }
     dedupeRawEventsByTurnPreferUser(events) {
         const byTurn = new Map();
         for (const event of events) {

package/dist/atlas/EpisodeTitleGenerator.d.ts

@@ -0,0 +1,31 @@
+import type { MemoryEvent } from '../types/index.js';
+export interface EpisodeTitleInput {
+    episodeId: string;
+    summary?: string | null;
+    topicPath?: string | null;
+    episodeType?: string | null;
+    startedAt?: number | null;
+    events: MemoryEvent[];
+}
+export interface EpisodeTitleResult {
+    displayTitle: string;
+    oneLineSummary: string;
+    topicHints: string[];
+    issueHints: string[];
+    eventKind: string;
+    userIntent?: string;
+    localDate?: string;
+    confidence: number;
+    reviewNeeded: boolean;
+    sourceEventIds: string[];
+    generatorTrace: {
+        usedUserText: boolean;
+        usedAssistantText: boolean;
+        fallback: boolean;
+        matchedRules: string[];
+    };
+}
+export declare class EpisodeTitleGenerator {
+    generate(input: EpisodeTitleInput): EpisodeTitleResult;
+}
+//# sourceMappingURL=EpisodeTitleGenerator.d.ts.map