cogmem 3.6.4 → 3.6.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+- Made default `cogmem memory candidates --json` return grouped ordinary, `needs_confirmation`, and deferred queues with actionable `nextActions`, while explicit `--status` still lists one queue.
+- Fixed `cogmem memory list --since/--until/--order` so raw-ledger inspection can resume from global sequence cursors instead of silently ignoring the filters.
+- Added `sourceLocator` drill-down commands to raw ledger list rows and Atlas search/explore evidence so agents can move from summaries to exact `memory show` context before quoting or claiming absence.
+- Added a `historical_discussion` recall intent for “did we discuss this before?” questions, with raw-ledger-first routing and expanded cues for Cogmem/OpenClaw memory-black-box discussions.
+- Changed Memory Binding backfill to scan raw events by cursor across the historical ledger rather than only the latest page, so old imported high-value user events can be bound after upgrade.
+- Changed `cogmem connect ... --json` to expose structured `nextSteps` and keep unsafe operator/host actions such as interactive init and host restart out of agent-safe `nextCommands`.
+- Fixed `cogmem memory plan` so Raw Ledger dream coverage lag is reported as non-blocking `raw_dream_ledger_lag` with `resolvableByDreamTick:false` instead of misleading agents into looping `dream tick` when no sealed episode backlog exists.
+- Updated the auto-installed OpenClaw/Hermes skills and operations handbooks with the full npm install, update, migration, import, `memory plan`, historical recall, source drill-down, governance, and maintenance command playbook.
+
 ## 3.6.4
 
 - Fixed OpenClaw/Hermes imports so empty imported episode boundaries are not batch-sealed into Dream work, and mature empty soft seals no longer abort `dream tick`.

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.4`
+Current version: `3.6.5`
 
 Distribution: npm registry. GitHub remains the source mirror and hosts this installer, but package install and upgrade resolve `cogmem` from npm by default.
 
@@ -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.4 schema set with one command:
+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:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -270,7 +270,7 @@ cogmem memory candidates --project my-agent --status needs_confirmation --json
 cogmem memory review --project my-agent --id <candidate-id> --action approve --actor <operator> --reason "confirmed" --confirmation-event <user-event-id> --json
 ```
 
-For a host timer, call `dream tick`; the timer only wakes the scheduler. An empty backlog performs no Dream work:
+For a host timer, call `dream tick`; the timer only wakes the sealed-episode scheduler. An empty episode backlog performs no Dream work, and `undreamedRawCount` by itself is not a reason to loop `dream tick`:
 
 ```bash
 cogmem dream tick --project my-agent --mode auto --max-episodes 10 --json
@@ -278,7 +278,7 @@ 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.
 
-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 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.
+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.
 
 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.
 
@@ -287,13 +287,17 @@ Episode surgery is available through `cogmem episode split|merge|move-event|recl
 Inspect queue state:
 
 ```bash
+cogmem memory plan --project my-agent --json
 cogmem memory status --project my-agent --json
+cogmem memory candidates --project my-agent --json
 cogmem memory candidates --project my-agent --status candidate --json
 cogmem memory govern --project my-agent --json
 cogmem memory candidates --project my-agent --status needs_confirmation --json
 cogmem memory review --project my-agent --id <candidate-id> --action approve --actor <operator> --reason "confirmed" --confirmation-event <user-event-id> --json
 ```
 
+`memory plan` is the read-only agent operations summary. It returns queue counts, Dream backlog, vector fallback state, blocking actions, and safe next commands. Only run `dream_tick` when it appears in `nextActions`; `nonBlocking[].type === "raw_dream_ledger_lag"` reports Raw Ledger coverage lag with `resolvableByDreamTick: false`, so inspect sources or episode/import boundaries instead of retrying `dream tick`. Default `memory candidates --json` groups ordinary, `needs_confirmation`, and deferred work in one payload; pass `--status candidate` or `--status needs_confirmation` only when the user asks for one queue.
+
 `memory govern` intentionally promotes only `candidate`. With `--status needs_confirmation` it lists the review queue and prints the `memory review` command instead of silently promoting the wrong status. Review actions are approve, reject, defer, supersede, and correction relink; every action stores operator identity, reason, and evidence requirements in an immutable audit row. `defer` keeps the candidate in `needs_confirmation` and records `reviewAfter` plus a status reason.
 
 ## Memory Atlas: let an agent see what it remembers
@@ -314,6 +318,8 @@ Atlas filtering is not limited to entity + time + action. The query compiler com
 
 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 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.
 
 Agents should use Atlas for broad inventory, history, and relationship questions; use normal recall for a direct fact. See [MEMORY_ATLAS.md](./MEMORY_ATLAS.md) for the complete CLI, MCP, OpenClaw, activation, and provenance contract.
@@ -351,7 +357,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. 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. 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 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.
 
@@ -374,6 +380,8 @@ 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.
 
+`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`.
+
 `ProspectiveMemoryService` stores future intentions, commitments, reminders, open loops, and plans as candidates only. A candidate is not actionable until an explicit user event confirms it. Rejected candidates stay suppressed unless genuinely new evidence creates a new version. The service and `cogmem prospective` CLI manage state only; they expose no task or tool execution capability.
 
 ```bash
@@ -459,9 +467,9 @@ From the OpenClaw workspace:
 
 ```bash
 cd ~/.openclaw/workspace
-cogmem init --agent openclaw --scope project
+npm install cogmem@latest --save
+./node_modules/.bin/cogmem connect openclaw --workspace . --auto --force
 cogmem doctor
-cogmem connect openclaw --workspace . --auto --force
 ```
 
 Import existing OpenClaw memory:
@@ -500,7 +508,9 @@ By default, `selective_compile` uses user text as the durable compile signal, ex
 After updates or config drift:
 
 ```bash
-cogmem doctor --fix --agent openclaw --workspace .
+cogmem update --yes
+cogmem doctor --fix --agent openclaw --workspace . --plugin-only
+openclaw gateway restart
 ```
 
 ## Hermes
@@ -622,6 +632,7 @@ Useful intents:
 ```bash
 cogmem memory recall --query "上个会话我们聊了什么" --intent previous_session_summary --project openclaw --agent openclaw --json
 cogmem memory recall --query "我当时关于记忆黑盒的原话是什么" --intent forensic_quote --project openclaw --agent openclaw --json
+cogmem memory recall --query "几个月前我们是不是讨论过 Cogmem 的记忆黑盒" --intent historical_discussion --project openclaw --agent openclaw --json
 ```
 
 Recall results include:
@@ -647,6 +658,15 @@ cogmem memory show --event <eventId> --before 2 --after 2 --json
 
 Raw-ledger fallback is not limited to the latest fixed event window. When Chinese FTS cannot match a cue directly, Cogmem runs a project/workspace/thread/time-scoped ledger text fallback and prefers an original user event over an assistant retelling when both match equally. Imported OpenClaw Markdown also accepts empty `user:` / `assistant:` headers whose body follows on later lines and collapses only adjacent exact duplicate exports.
 
+For ledger audits or resumable import/binding checks, use global sequence cursors:
+
+```bash
+cogmem memory list --project openclaw --since <global-seq> --order asc --json
+cogmem memory list --project openclaw --since <global-seq> --until <global-seq> --order asc --json
+```
+
+Each listed event includes a `sourceLocator` with a `memory show` command. Use it before saying an event ID or exact source is unavailable.
+
 ## TypeScript API
 
 ```ts
@@ -770,7 +790,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.4`. 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.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`.
 
 Publish manually only for emergency fallback:
 

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,11 @@
-# cogmem 3.6.4 Release Checklist
+# cogmem 3.6.5 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.4`.
+- `package.json` version is `3.6.5`.
 - `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.
@@ -60,7 +60,9 @@ MCP `tools/list` includes strategy, episode append/import/status/seal/repair, to
 - README and skills explain Strategy Cortex templates, no-instruction-authority lifecycle, one-retry replanning, strategy-conditioned retrieval, offline-only rollout comparison, and read-only MemoryUseJudge telemetry.
 - 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 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`.
+- `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.
 - README and skills explain user-shaped topic operations, user-explicit versus model-candidate authority, alias collision review, operation rollback, and project isolation.
@@ -91,7 +93,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.4`. 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.6.5`. 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

@@ -61,6 +61,7 @@ export interface AgentRecallSourceAnchor {
 }
 export interface AgentRecallSourceContextEvent {
     eventId: string;
+    globalSeq?: number;
     label: string;
     role?: MemoryEvent['role'];
     rawEventType?: MemoryEvent['rawEventType'];
@@ -89,7 +90,10 @@ export interface AgentRecallSourceContext {
     window: SourceContextWindowMetadata;
     locator: {
         eventId: string;
+        globalSeq?: number;
+        projectId?: string;
         command: string;
+        contextCommand?: string;
         threadId?: string;
         sessionId?: string;
         localDate?: string;
@@ -172,7 +176,7 @@ export interface AgentRecallResult {
 export interface AgentRecallDecisionTrace {
     version: 'agent_recall_decision.v1';
     selectedLane: 'graph' | 'compiled' | 'brain_fallback' | 'raw_ledger' | 'mixed' | 'none';
-    reason: 'previous_session' | 'forensic_quote' | 'graph_selected' | 'raw_cue_match_preferred' | 'compiled_cue_match' | 'brain_fallback_selected' | 'raw_ledger_only' | 'no_recall_evidence';
+    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;
         navigation: number;
@@ -242,6 +246,7 @@ export declare class KernelAgentMemoryBackend {
     recallPack(query: AgentRecallQuery): AgentRecallPackResult;
     private recallPreviousSession;
     private recallForensicQuote;
+    private recallHistoricalDiscussion;
     private recallForensicAnchor;
     private searchRawEventsByQueryPlan;
     private rawLedgerFallbackItemsForQuery;

package/dist/agent/AgentMemoryBackend.js

@@ -254,6 +254,9 @@ export class KernelAgentMemoryBackend {
         if (query.intent === 'forensic_quote') {
             return this.recallForensicQuote(query, queryPlan);
         }
+        if (queryPlan.intent === 'historical_discussion') {
+            return this.recallHistoricalDiscussion(query, queryPlan);
+        }
         const limit = query.limit ?? 5;
         const allowsGraph = laneAllowed(query.retrievalPolicy, 'graph');
         const allowsCompiled = laneAllowed(query.retrievalPolicy, 'compiled');
@@ -490,6 +493,46 @@ export class KernelAgentMemoryBackend {
             }, items.length),
         };
     }
+    recallHistoricalDiscussion(query, queryPlan) {
+        const limit = query.limit ?? 5;
+        const allowsGraph = laneAllowed(query.retrievalPolicy, 'graph');
+        const allowsCompiled = laneAllowed(query.retrievalPolicy, 'compiled');
+        const allowsRawSource = laneAllowed(query.retrievalPolicy, 'raw_source');
+        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))
+            : [];
+        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';
+        return {
+            recallMode: rawItems.length > 0 ? 'raw_ledger_fallback' : 'brain_recall_fallback',
+            items,
+            fallbackUsed: true,
+            queryPlan,
+            decisionTrace: recallDecisionTrace(selectedLane, 'historical_discussion', {
+                graph: graphItems.length,
+                navigation: compiledItems.length,
+                scopedNavigation: compiledItems.length,
+                brainFallback: 0,
+                rawLedger: rawItems.length,
+            }, items.length),
+        };
+    }
     recallForensicAnchor(query, limit) {
         if (!query.anchorEventId)
             return [];
@@ -928,7 +971,10 @@ export class KernelAgentMemoryBackend {
             window: normalized.window,
             locator: {
                 eventId: event.eventId,
-                command: `cogmem memory show --event ${event.eventId} --before 2 --after 2`,
+                globalSeq: event.globalSeq,
+                projectId: event.projectId,
+                command: `cogmem memory show --event ${cliArg(event.eventId)}${event.projectId ? ` --project ${cliArg(event.projectId)}` : ''} --before 2 --after 2 --json`,
+                contextCommand: `cogmem memory show --event ${cliArg(event.eventId)}${event.projectId ? ` --project ${cliArg(event.projectId)}` : ''} --before 3 --after 3 --json`,
                 threadId: event.threadId,
                 sessionId: event.sessionId,
                 localDate: event.localDate,
@@ -939,6 +985,7 @@ export class KernelAgentMemoryBackend {
         const text = this.eventText(event);
         return {
             eventId: event.eventId,
+            globalSeq: event.globalSeq,
             label: memoryEventLabel(event),
             role: event.role,
             rawEventType: event.rawEventType,
@@ -1270,3 +1317,6 @@ function uniqueNonEmpty(values) {
 function laneAllowed(policy, lane) {
     return !policy || policy.allowedLanes.includes(lane);
 }
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/agent/AgentRecallQueryCompiler.d.ts

@@ -1,4 +1,4 @@
-export type AgentRecallIntent = 'memory_recall' | 'previous_session_summary' | 'forensic_quote';
+export type AgentRecallIntent = 'memory_recall' | 'previous_session_summary' | 'forensic_quote' | 'historical_discussion';
 export interface AgentRecallQueryCompileInput {
     query: string;
     intent?: AgentRecallIntent;

package/dist/agent/AgentRecallQueryCompiler.js

@@ -99,6 +99,9 @@ export function inferAgentRecallIntent(query) {
     if (/原话|怎么说的|完整对话|上一句|下一句|exact quote|verbatim/.test(text)) {
         return 'forensic_quote';
     }
+    if (/记得.{0,12}(聊过|讨论过|说过)|还记得|之前.{0,12}(聊过|讨论过|说过)|以前.{0,12}(聊过|讨论过|说过)|(过去|几个月前|半年前|上个月|前几天|昨天|上次|上个).{0,20}(聊过|讨论过|说过)|当时.{0,12}(聊|说|问)|那次.{0,12}(聊|说|问)|有没有.{0,12}(记录|聊过|讨论过)|have we discussed|did we talk about|previously discussed/.test(text)) {
+        return 'historical_discussion';
+    }
     return 'memory_recall';
 }
 export function extractRecallKeywords(text) {
@@ -168,10 +171,19 @@ function buildSemanticCuePhrases(keywords, query, anchorText) {
     const hasBlackBox = merged.includes('黑盒') || /黑盒|black\s*box/iu.test(text);
     if (hasMemory && hasBlackBox) {
         out.push('记忆 黑盒');
+        out.push('记忆黑盒');
+        out.push('CogMem Memory Context');
+        out.push('Memory Context');
+        out.push('上下文注入');
+        out.push('sourceContext 原文下钻');
         out.push('存档 黑盒');
         out.push('对话 存档 黑盒');
         out.push('上下文 黑盒');
         out.push('黑盒');
+        if (/graph|图|卡死|database locked|zombie|锁/iu.test(text)) {
+            out.push('memory graph 黑盒');
+            out.push('database locked zombie');
+        }
     }
     else if (hasBlackBox) {
         out.push('黑盒');

package/dist/atlas/MemoryAtlasService.d.ts

@@ -16,6 +16,7 @@ export declare class MemoryAtlasService {
         maxHops?: number;
     }): MemoryAtlasPathResult;
     timeline(query: string, options: MemoryAtlasQueryOptions): MemoryAtlasTimelineResult;
+    private attachEvidence;
     private evidence;
     private edgesFor;
     private safeEdges;

package/dist/atlas/MemoryAtlasService.js

@@ -15,7 +15,8 @@ export class MemoryAtlasService {
     search(query, options) {
         const projectId = requiredProject(options.projectId);
         const nodes = this.store.search(boundedQuery(query), projectId, boundedLimit(options.limit));
-        return slice(projectId, nodes, this.edgesFor(nodes, projectId), query);
+        const withEvidence = this.attachEvidence(nodes, projectId, options);
+        return slice(projectId, withEvidence, this.edgesFor(withEvidence, projectId), query);
     }
     explore(query, options) {
         const projectId = requiredProject(options.projectId);
@@ -32,8 +33,9 @@ export class MemoryAtlasService {
                 from: compiled.range?.from, to: compiled.range?.to, limit });
             nodes = uniqueNodes([...actions.map((action) => this.store.getNode(action.id, projectId)).filter((node) => Boolean(node)), ...nodes]).slice(0, limit);
         }
-        const edges = this.edgesFor(nodes, projectId);
-        const result = slice(projectId, nodes, edges, query);
+        const nodesWithEvidence = this.attachEvidence(nodes, projectId, options);
+        const edges = this.edgesFor(nodesWithEvidence, projectId);
+        const result = slice(projectId, nodesWithEvidence, edges, query);
         result.facets = { time: compiled.range, target: target.labels.join(', ') || compiled.target, memoryKinds: compiled.memoryKinds, keywords: compiled.keywords };
         const hasFacet = Boolean(compiled.range || compiled.target || compiled.memoryKinds.length || compiled.tokens.length);
         result.coldMemoryResurrected = hasFacet && nodes.some((node) => node.activation <= 0.1);
@@ -155,14 +157,28 @@ export class MemoryAtlasService {
         return { version: 'memory_atlas.v1', projectId, query, range: compiled.range,
             temporalResurrection: Boolean(compiled.range && [...nodes, ...actions].length), nodes, actions, warnings: [] };
     }
+    attachEvidence(nodes, projectId, options) {
+        return nodes.map((node) => {
+            const evidence = this.evidence(node.id, projectId, options.evidenceLimit, options.includeEvidence);
+            const evidenceTotal = this.store.evidenceTotal(node.id, projectId);
+            return { ...node, evidenceCount: evidenceTotal, evidenceTotal, evidenceReturned: evidence.length, evidence };
+        });
+    }
     evidence(nodeId, projectId, requested, includeExcerpt) {
         const limit = Math.max(1, Math.min(requested ?? 2, 10));
         return this.store.evidenceIds(nodeId, projectId, limit).flatMap((eventId) => {
             const event = this.eventStore.getEvent(eventId);
             if (!event || event.projectId !== projectId)
                 return [];
-            return [{ eventId, drilldown: `cogmem memory show --event ${eventId} --project ${projectId} --json`,
-                    excerpt: includeExcerpt ? eventTextForMemory(event).slice(0, 500) : undefined }];
+            const sourceLocator = atlasSourceLocator(event, projectId);
+            return [{
+                    eventId,
+                    globalSeq: event.globalSeq,
+                    projectId,
+                    drilldown: sourceLocator.command,
+                    sourceLocator,
+                    excerpt: includeExcerpt ? eventTextForMemory(event).slice(0, 500) : undefined,
+                }];
         });
     }
     edgesFor(nodes, projectId) {
@@ -214,3 +230,21 @@ function chunked(values, size) {
     return chunks;
 }
 function slice(projectId, nodes, edges, query) { return { version: 'memory_atlas.v1', projectId, query, nodes, edges, nextActions: nodes.slice(0, 5).map((node) => ({ label: `Inspect ${node.label}`, tool: 'cogmem_graph_node', args: { id: node.id, projectId } })), warnings: [] }; }
+function atlasSourceLocator(event, projectId) {
+    const project = projectId || event.projectId;
+    const projectArg = project ? ` --project ${cliArg(project)}` : '';
+    const base = `cogmem memory show --event ${cliArg(event.eventId)}${projectArg}`;
+    return {
+        eventId: event.eventId,
+        globalSeq: event.globalSeq,
+        projectId: project,
+        threadId: event.threadId,
+        sessionId: event.sessionId,
+        localDate: event.localDate,
+        command: `${base} --before 2 --after 2 --json`,
+        contextCommand: `${base} --before 3 --after 3 --json`,
+    };
+}
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/atlas/MemoryAtlasTypes.d.ts

@@ -1,7 +1,19 @@
 export type MemoryAtlasNodeType = 'project' | 'topic' | 'entity' | 'cluster' | 'episode' | 'belief' | 'action' | 'time' | 'event';
 export interface MemoryAtlasEvidence {
     eventId: string;
+    globalSeq?: number;
+    projectId?: string;
     drilldown: string;
+    sourceLocator?: {
+        eventId: string;
+        globalSeq?: number;
+        projectId?: string;
+        threadId?: string;
+        sessionId?: string;
+        localDate?: string;
+        command: string;
+        contextCommand: string;
+    };
     excerpt?: string;
 }
 export interface MemoryAtlasNode {
@@ -24,6 +36,8 @@ export interface MemoryAtlasNode {
     evidenceTotal: number;
     /** Number of evidence records returned in this response. */
     evidenceReturned?: number;
+    /** Bounded first-hop raw evidence locators for agent-facing graph search/explore responses. */
+    evidence?: MemoryAtlasEvidence[];
 }
 export interface MemoryAtlasEdge {
     source: string;

package/dist/bin/connect.js

@@ -90,21 +90,92 @@ function defaultSkillPath(agent, workspaceRoot) {
     return join(process.env.HOME || homedir(), '.hermes', 'skills', 'cogmem-memory', 'SKILL.md');
 }
 function nextCommands(agent) {
+    return nextSteps(agent)
+        .filter((step) => step.safeForAutomation && step.actor === 'agent')
+        .map((step) => step.command);
+}
+function nextSteps(agent) {
+    const project = agent === 'openclaw' ? 'openclaw' : 'hermes';
+    const importCommand = agent === 'openclaw' ? 'import-openclaw' : 'import-hermes';
+    const steps = [
+        {
+            id: 'doctor',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem doctor',
+            when: 'after installation or update',
+            purpose: 'verify package, config, and database access',
+        },
+        {
+            id: 'import_dry_run',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --dry-run --json`,
+            when: 'before importing legacy memory',
+            purpose: 'preview source discovery and import counts',
+        },
+        {
+            id: 'import_apply',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --json`,
+            when: 'after dry-run looks correct',
+            purpose: 'idempotently import legacy memory into Cogmem',
+        },
+        {
+            id: 'memory_plan',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory plan --project ${project} --json`,
+            when: 'after import, update, or user asks for governance progress',
+            purpose: 'read agent-safe next actions instead of guessing from raw counters',
+        },
+        {
+            id: 'memory_status',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory status --project ${project} --json`,
+            when: 'for read-only health checks',
+            purpose: 'inspect raw ledger, vector fallback, dream backlog, and queue summary',
+        },
+        {
+            id: 'interactive_init',
+            actor: 'operator',
+            safeForAutomation: false,
+            command: `./node_modules/.bin/cogmem init --agent ${agent} --scope project`,
+            when: 'only if no Cogmem config exists and a human operator is present',
+            purpose: 'interactive first-time config wizard; agents must not run this unattended',
+        },
+    ];
     if (agent === 'openclaw') {
-        return [
-            './node_modules/.bin/cogmem doctor',
-            './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
-            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw --dry-run',
-            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw',
-            './node_modules/.bin/cogmem memory status --project openclaw --json',
-        ];
+        steps.splice(1, 0, {
+            id: 'openclaw_diagnose',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
+            when: 'after connect --auto --force or before investigating injection failures',
+            purpose: 'verify generated plugin files, audit log, queue lock, and hook diagnostics',
+        });
+        steps.push({
+            id: 'restart_gateway',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'openclaw gateway restart',
+            when: 'after plugin files or OpenClaw config changed',
+            purpose: 'reload OpenClaw hooks so the refreshed Cogmem plugin is active',
+        });
     }
-    return [
-        './node_modules/.bin/cogmem doctor',
-        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes --dry-run',
-        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes',
-        './node_modules/.bin/cogmem memory status --project hermes --json',
-    ];
+    else {
+        steps.push({
+            id: 'reload_hermes',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'restart or reload Hermes MCP server',
+            when: 'after Hermes MCP config changed',
+            purpose: 'reload the cogmem MCP server entry',
+        });
+    }
+    return steps;
 }
 function usage() {
     return [
@@ -238,6 +309,7 @@ function installSkill(args) {
         installed: !args.dryRun && !alreadyCurrent,
         alreadyCurrent,
         nextCommands: nextCommands(args.agent),
+        nextSteps: nextSteps(args.agent),
         hostConfigSnippet: hostConfigSnippet(args.agent, args.workspaceRoot, args.auto),
         autoMemory,
         hermesMcp,