@try-works/dsh-memory 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-memory",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Git-backed, workspace-scoped memory for the DeepSeek Harness (global layer + per-workspace layers)",
   "type": "module",
   "main": "src/index.js",
@@ -48,7 +48,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-conversation"
       ],
       "external": []
     }

package/src/client/index.js

@@ -148,6 +148,267 @@ window.__ModuleLoader__.load({
       '}',
     ].join('\n')
 
+
+    // ---------------------------------------------------------------------------------
+    // Memory map: the inline face of the memory_map tool.
+    //
+    // It renders the tool result's structured `meta`, which is the value the tool returned.
+    // That is not a shortcut, it is the only honest source: a browser half cannot ask the
+    // host for anything (dsh.client has no data channel, remotes are an allowlisted
+    // application assembly, and the plugin route serves only client JS), so the tool result
+    // IS the channel. Recomputing the numbers here would invent a second source that could
+    // disagree with the one the agent was shown, and the disagreement would be invisible.
+    // ---------------------------------------------------------------------------------
+    const INK = '#1A1A18'
+    const MUTED = '#6E6E6B'
+    const FAINT = '#8A8A87'
+    const LINE = '#EFEFEC'
+    const RUST = '#8A3F1E'
+    const COPPER = '#C77E4A'
+    const QUIET = '#6B6B68'
+    const GEIST = 'Geist, system-ui, -apple-system, sans-serif'
+    const MONO = 'Geist Mono, ui-monospace, SFMono-Regular, monospace'
+    // Deepest tone for the largest layer, so the ramp itself encodes proportion and seven
+    // layers need seven TONES rather than seven hues.
+    const TONES = ['#2A3644', '#3A4757', '#4C5A6B', '#64717F', '#808C99', '#9DA8B3', '#BCC4CC']
+
+    /** Thousands separators, so a four-digit count is readable at a glance. */
+    function fmt(value) {
+      return typeof value === 'number' && Number.isFinite(value) ? value.toLocaleString('en-US') : String(value)
+    }
+
+    /** How a verdict is written and coloured: the WORD carries the meaning, colour agrees. */
+    function verdictStyle(verdict) {
+      if (verdict === 'stale') return { color: RUST, weight: 500 }
+      if (verdict === 'aging') return { color: COPPER, weight: 500 }
+      if (verdict === 'unverified' || verdict === 'empty') return { color: QUIET, weight: 500 }
+      return { color: QUIET, weight: 400 }
+    }
+
+    function box(style, children) { return react.createElement('div', { style: style }, children) }
+
+    /** The stacked layer bar. Each width is a count as a fraction of the total. */
+    function LayerBar(props) {
+      const total = props.layers.reduce(function (sum, l) { return sum + l.count }, 0)
+      if (!total) return null
+      const segs = props.layers.map(function (layer, i) {
+        return react.createElement('div', {
+          key: layer.name,
+          style: { width: (layer.count / total * 100).toFixed(3) + '%', flexShrink: 0, background: TONES[i % TONES.length] },
+        })
+      })
+      return box({ display: 'flex', height: props.height || '26px', borderRadius: '7px', overflow: 'hidden' }, segs)
+    }
+
+    /** The legend: fixed dot and name slots, so every count shares one vertical lane. */
+    function Legend(props) {
+      const items = props.layers.map(function (layer, i) {
+        return box({ key: layer.name, display: 'flex', alignItems: 'center', gap: '7px' }, [
+          react.createElement('div', { key: 'd', style: { width: '6px', height: '6px', flexShrink: 0, borderRadius: '2px', background: TONES[i % TONES.length] } }),
+          react.createElement('div', { key: 'n', style: { fontFamily: GEIST, fontSize: '11px', color: '#3A3A38', width: '62px', flexShrink: 0 } }, layer.name),
+          react.createElement('div', { key: 'c', style: { fontFamily: MONO, fontSize: '10px', color: QUIET } }, fmt(layer.count)),
+        ])
+      })
+      const half = Math.ceil(items.length / 2)
+      return box({ display: 'flex', flexDirection: 'column', gap: '7px' }, [
+        box({ key: 'a', display: 'flex', gap: '22px' }, items.slice(0, half)),
+        box({ key: 'b', display: 'flex', gap: '22px' }, items.slice(half)),
+      ])
+    }
+
+    function Stat(props) {
+      return box({ display: 'flex', alignItems: 'baseline', gap: '6px' }, [
+        react.createElement('div', { key: 'n', style: { fontFamily: MONO, fontSize: props.size || '15px', color: props.color || INK } }, props.value),
+        react.createElement('div', { key: 'l', style: { fontFamily: GEIST, fontSize: '11px', color: MUTED } }, props.label),
+      ])
+    }
+
+    function Chip(props) {
+      return react.createElement('div', {
+        style: { padding: '3px 8px', borderRadius: '5px', fontFamily: MONO, fontSize: '10px', background: props.hot ? '#FAEDE6' : '#F4F4F2', color: props.hot ? RUST : '#3A3A38' },
+      }, props.text)
+    }
+
+    /** Section label, with an optional right-hand note. */
+    function sectionLabel(text, note) {
+      return box({ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }, [
+        react.createElement('div', { key: 'l', style: { fontFamily: GEIST, fontSize: '11px', fontWeight: 500, letterSpacing: '0.08em', color: MUTED } }, text),
+        note ? react.createElement('div', { key: 'r', style: { fontFamily: GEIST, fontSize: '11px', color: FAINT } }, note) : null,
+      ])
+    }
+
+    /** The three-bar mark: a miniature of the layer bar, so the card is identifiable at a glance. */
+    function Glyph() {
+      const bar = function (key, width, tone) {
+        return react.createElement('div', { key: key, style: { height: '2px', width: width, borderRadius: '1px', background: tone } })
+      }
+      return box({ width: '14px', height: '14px', flexShrink: 0, display: 'flex', flexDirection: 'column', gap: '2px', justifyContent: 'center' }, [
+        bar('a', '14px', TONES[0]), bar('b', '10px', TONES[3]), bar('c', '6px', TONES[5]),
+      ])
+    }
+
+    /** The RECEIVED panel: what memory put in front of this session, with its freshness. */
+    function ReceivedPanel(props) {
+      const sections = (props.received && props.received.sections) || []
+      if (!sections.length) return null
+      const rows = sections.map(function (section) {
+        const style = verdictStyle(section.verdict)
+        return box({ key: section.name, display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }, [
+          react.createElement('div', { key: 'n', style: { fontFamily: GEIST, fontSize: '12px', color: '#3A3A38' } }, section.name),
+          react.createElement('div', { key: 'v', style: { fontFamily: MONO, fontSize: '11px', color: style.color, fontWeight: style.weight } }, section.marker ? section.marker.replace(/[\[\]]/g, '').trim() : 'fresh'),
+        ])
+      })
+      return box({ display: 'flex', flexDirection: 'column', gap: '10px' }, [
+        sectionLabel('RECEIVED', fmt(props.received.chars) + ' chars'),
+        box({ key: 'rows', display: 'flex', flexDirection: 'column', gap: '7px' }, rows),
+      ])
+    }
+
+    /** The WRITTEN panel: what THIS session recorded, by layer and by entry. */
+    function WrittenPanel(props) {
+      const written = props.written
+      if (!written || !written.total) return null
+      const chips = Object.keys(written.byLayer).map(function (layer) {
+        return react.createElement(Chip, { key: layer, text: layer + ' ' + written.byLayer[layer] })
+      })
+      const entries = written.entries.map(function (entry) {
+        return box({ key: entry.id, display: 'flex', alignItems: 'baseline' }, [
+          react.createElement('div', { key: 'i', style: { fontFamily: MONO, fontSize: '11px', color: QUIET, width: '186px', flexShrink: 0 } }, entry.id),
+          react.createElement('div', { key: 'l', style: { fontFamily: GEIST, fontSize: '11px', color: FAINT, width: '72px', flexShrink: 0 } }, entry.layer),
+          react.createElement('div', { key: 'h', style: { fontFamily: GEIST, fontSize: '12px', color: '#3A3A38' } }, entry.heading),
+        ])
+      })
+      const more = written.total > written.entries.length
+      return box({ display: 'flex', flexDirection: 'column', gap: '12px' }, [
+        sectionLabel('WRITTEN', fmt(written.total) + ' this session'),
+        box({ key: 'c', display: 'flex', gap: '5px' }, chips),
+        box({ key: 'e', display: 'flex', flexDirection: 'column', gap: '7px' }, entries),
+        more ? react.createElement('div', { key: 'm', style: { fontFamily: GEIST, fontSize: '11px', color: FAINT } }, '+ ' + fmt(written.total - written.entries.length) + ' more') : null,
+      ])
+    }
+
+    /**
+     * The memory_map tool row.
+     *
+     * Every value comes from the result's own `meta`. Nothing is fetched and nothing is
+     * inferred from the rendered text: when the snapshot is absent the card says so, rather
+     * than drawing a shape that merely looks like data.
+     */
+    function MemoryMapCard(props) {
+      const block = props ? props.block : null
+      const meta = block && typeof block.meta === 'object' && block.meta !== null ? block.meta : null
+      const store = meta && meta.store ? meta.store : null
+      const session = meta && meta.session ? meta.session : null
+      const summary = store ? fmt(store.total) + ' entries · ' + fmt(store.scopeTotal) + ' scopes' : ''
+      const headStyle = { height: '46px', flexShrink: 0, display: 'flex', alignItems: 'center', gap: '10px', padding: '0 16px', borderBottom: '1px solid ' + LINE }
+      const head = box(headStyle, [
+        react.createElement(Glyph, { key: 'g' }),
+        react.createElement('div', { key: 't', style: { fontFamily: GEIST, fontSize: '13px', fontWeight: 500, color: INK } }, 'Memory map'),
+        react.createElement('div', { key: 's', style: { flex: 1 } }),
+        react.createElement('div', { key: 'c', style: { fontFamily: GEIST, fontSize: '12px', color: MUTED } }, summary),
+      ])
+      const body = []
+      if (store) {
+        body.push(box({ key: 'l', display: 'flex', flexDirection: 'column', gap: '12px' }, [
+          react.createElement(LayerBar, { key: 'bar', layers: store.layers }),
+          react.createElement(Legend, { key: 'leg', layers: store.layers }),
+        ]))
+        const attention = (store.queue && store.queue.attention) || []
+        const chips = attention.slice(0, 3).map(function (row) {
+          return react.createElement(Chip, { key: row.state + row.reason, text: fmt(row.count) + ' ' + row.state, hot: true })
+        })
+        if (store.queue && store.queue.waiting) chips.push(react.createElement(Chip, { key: 'waiting', text: fmt(store.queue.waiting) + ' waiting' }))
+        const stats = [
+          react.createElement(Stat, { key: 'a', value: fmt(store.freshness.fresh), label: 'fresh' }),
+          store.freshness.stale ? react.createElement(Stat, { key: 'b', value: fmt(store.freshness.stale), label: 'stale', color: RUST }) : null,
+          store.freshness.skip ? react.createElement(Stat, { key: 'c', value: fmt(store.freshness.skip), label: 'superseded' }) : null,
+        ]
+        const footStyle = { display: 'flex', justifyContent: 'space-between', alignItems: 'center', borderTop: '1px solid ' + LINE, paddingTop: '13px', gap: '16px' }
+        body.push(box({ key: 'f', display: 'flex', flexDirection: 'column' }, [
+          box(Object.assign({ key: 'row' }, footStyle), [
+            box({ key: 's', display: 'flex', gap: '18px' }, stats),
+            box({ key: 'q', display: 'flex', gap: '5px', flexWrap: 'wrap' }, chips),
+          ]),
+        ]))
+      }
+      if (session && session.received) body.push(react.createElement(ReceivedPanel, { key: 'r', received: session.received }))
+      if (session && session.written) body.push(react.createElement(WrittenPanel, { key: 'w', written: session.written }))
+      if (!body.length) body.push(react.createElement('div', { key: 'none', style: { fontFamily: GEIST, fontSize: '12px', color: MUTED } }, 'No snapshot was recorded for this call.'))
+      const cardStyle = { maxWidth: '760px', border: '1px solid #E7E7E4', borderRadius: '12px', background: '#FFFFFF', display: 'flex', flexDirection: 'column' }
+      const bodyStyle = { padding: '16px', display: 'flex', flexDirection: 'column', gap: '14px' }
+      return box(cardStyle, [head, box(Object.assign({ key: 'b' }, bodyStyle), body)]);
+    }
+
+    /**
+     * The Memory tab: this session's memory activity, in one place.
+     *
+     * Its data is the most recent memory_map result in this session. That is not a
+     * convenience: a browser half cannot ask the host for anything, so the session record is
+     * the only channel, and a tool result carries its structured value on `meta` (ui-chat's
+     * conversation-nodes/tool.ts does `meta: match.event.data.meta`).
+     *
+     * READING IT: a conversation view gets data through a registered standard hook, so the
+     * plugin provides `memoryMap` via ctx.uiSession.provide and this component receives
+     * `useMemoryMap` as a prop, the way ui-tool's rows receive their history hook. The hook
+     * resolves by scanning the Trajectory target's event nodes for a settled memory_map tool
+     * call; the Trajectory target is the shipped assembly of this session's nodes, and its
+     * snapshot contract is eventNodes: ConversationNode[] with { kind: 'tool', root }.
+     */
+    function findMemorySnapshot(snapshot) {
+      if (!snapshot || !Array.isArray(snapshot.eventNodes)) return null
+      // Newest first: the tab describes the session as it stands now, not as it first was.
+      for (let i = snapshot.eventNodes.length - 1; i >= 0; i -= 1) {
+        const node = snapshot.eventNodes[i]
+        const root = node && node.kind === 'tool' ? node.root : null
+        if (!root || root.isError) continue
+        const name = root.call && root.call.name
+        if (name !== 'memory_map') continue
+        if (root.meta && typeof root.meta === 'object') return root.meta
+      }
+      return null
+    }
+
+    function MemoryTabView(props) {
+      const useMemoryMap = props ? props.useMemoryMap : null
+      const meta = typeof useMemoryMap === 'function' ? useMemoryMap() : null
+      const page = { padding: '32px 28px 0 28px', display: 'flex', flexDirection: 'column', gap: '0' }
+      if (!meta) {
+        // Nothing to draw yet, and saying so beats drawing an empty chart that reads as zero.
+        const empty = { display: 'flex', flexDirection: 'column', gap: '10px', maxWidth: '520px' }
+        return box(page, [box(empty, [
+          react.createElement('div', { key: 'h', style: { fontFamily: GEIST, fontSize: '15px', fontWeight: 500, color: INK } }, 'No memory snapshot in this session yet'),
+          react.createElement('div', { key: 'p', style: { fontFamily: GEIST, fontSize: '13px', lineHeight: 1.6, color: MUTED } }, 'This tab shows what memory put in front of this conversation, what the conversation wrote back, and the state of the store. It fills in once memory_map runs in this session.'),
+        ])]);
+      }
+      const store = meta.store || null
+      const session = meta.session || null
+      const parts = []
+      if (session) {
+        const who = session.workspace ? 'workspace ' + session.workspace : 'global layer'
+        parts.push(react.createElement('div', { key: 'id', style: { fontFamily: GEIST, fontSize: '13px', color: '#3A3A38', paddingBottom: '26px' } }, 'This session · ' + who));
+        if (session.received) parts.push(box({ key: 'r', display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '460px' }, [react.createElement(ReceivedPanel, { key: 'p', received: session.received })]));
+        if (session.written) parts.push(box({ key: 'w', marginTop: '34px', paddingTop: '26px', borderTop: '1px solid ' + LINE, display: 'flex', flexDirection: 'column' }, [react.createElement(WrittenPanel, { key: 'p', written: session.written })]));
+      }
+      if (store) {
+        const attention = (store.queue && store.queue.attention) || []
+        const chips = attention.slice(0, 3).map(function (row) { return react.createElement(Chip, { key: row.state + row.reason, text: fmt(row.count) + ' ' + row.state, hot: true }) });
+        if (store.queue && store.queue.waiting) chips.push(react.createElement(Chip, { key: 'waiting', text: fmt(store.queue.waiting) + ' waiting' }));
+        parts.push(box({ key: 's', marginTop: '34px', paddingTop: '26px', borderTop: '1px solid ' + LINE, display: 'flex', flexDirection: 'column', gap: '15px' }, [
+          sectionLabel('SNAPSHOT', fmt(store.total) + ' entries · ' + fmt(store.scopeTotal) + ' scopes'),
+          react.createElement(LayerBar, { key: 'bar', layers: store.layers, height: '30px' }),
+          react.createElement(Legend, { key: 'leg', layers: store.layers }),
+          box({ key: 'f', display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '16px' }, [
+            box({ key: 'st', display: 'flex', gap: '18px' }, [
+              react.createElement(Stat, { key: 'a', value: fmt(store.freshness.fresh), label: 'fresh' }),
+              store.freshness.stale ? react.createElement(Stat, { key: 'b', value: fmt(store.freshness.stale), label: 'stale', color: RUST }) : null,
+              store.freshness.skip ? react.createElement(Stat, { key: 'c', value: fmt(store.freshness.skip), label: 'superseded' }) : null,
+            ]),
+            box({ key: 'q', display: 'flex', gap: '5px', flexWrap: 'wrap' }, chips),
+          ]),
+        ]));
+      }
+      return box(page, parts);
+    }
     /** Fields rendered on this page, in order. */
     const FIELDS = [
       { key: 'memoryRoot', label: 'Memory root', hint: 'Local folder or drive that holds the store.', placeholder: 'D:\\Memory' },
@@ -351,6 +612,38 @@ window.__ModuleLoader__.load({
 
       ctx.effect(() => {
         const disposers = []
+        // The inline face of memory_map, registered by the tool's WIRE NAME, which is how the
+        // host finds it. The result carries the data, so the view needs no other channel.
+        disposers.push(ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
+          name: 'tool.call.toolview',
+          key: 'memory_map',
+        }, MemoryMapCard)))
+        // The Memory tab. Data arrives through a registered standard hook, because a
+        // conversation view is a slot and slots are fed by hooks, not by direct reads.
+        // The Trajectory target is the shipped assembly of this session's nodes, so the
+        // source re-derives the memory snapshot from it on every projection.
+        ctx.effect(() => ctx.uiSession.provide({
+          hooks: ['memoryMap'],
+          resolve: (binding) => {
+            const target = ctx.uiConversation.binding(binding).target('trajectory')
+            return {
+              hooks: {
+                memoryMap: {
+                  getSnapshot: () => findMemorySnapshot(target.getSnapshot()),
+                  subscribe: (listener) => target.subscribe(listener),
+                },
+              },
+            }
+          },
+        }), 'dsh-memory: memory map hook')
+        disposers.push(ctx.slots.inject('conversation.view', () => ctx.slots.register({
+          name: 'conversation.view',
+          id: 'memory',
+          // ui-chat holds 0 and ui-trajectory 10, so Memory sits after both without
+          // reordering anyone else's tab.
+          order: 20,
+          label: 'Memory',
+        }, MemoryTabView)))
         disposers.push(ctx.slots.inject('settings.section', () => ctx.slots.register({
           name: 'settings.section',
           id: 'memory',
@@ -362,7 +655,7 @@ window.__ModuleLoader__.load({
     }
 
     exports.name = 'dsh-memory'
-    exports.inject = ['slots', 'configForms', 'remote.session']
+    exports.inject = ['slots', 'configForms', 'remote.session', 'uiSession', 'uiConversation']
     exports.apply = apply
     return module.exports
   },

package/src/host.js

@@ -690,5 +690,8 @@ export function wireHost(ctx, store, cfg) {
     })
   }
 
-  return { scheduler, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf }
+  // injectionMaxChars travels with the host so memory_map can describe the card that was
+  // ACTUALLY built: the cap is configuration, and a snapshot built with a different cap would
+  // report a size the session never saw.
+  return { scheduler, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf, injectionMaxChars: cfg.injectionMaxChars }
 }

package/src/index.js

@@ -40,6 +40,7 @@ export function hostExtras(host) {
     rerankSearch: host.rerankSearch,
     workspaceOf: host.workspaceOf,
     historyOf: host.historyOf,
+    injectionMaxChars: host.injectionMaxChars,
   }
 }
 export const name = 'dsh-memory'

package/src/map.js

@@ -0,0 +1,184 @@
+// The UI snapshot behind memory_map: one structured view of the store, and of what THIS
+// session has received from memory and written back to it.
+//
+// Three rules shape this module.
+//
+// Every number is DERIVED, never restated. Freshness comes from freshnessVerdict, the queue
+// from the queue reader, and the RECEIVED panel from the injection's own rendered text. A
+// second set of rules here would drift from the first, and the UI would then lie about the
+// store it exists to describe.
+//
+// The snapshot is LOSSLESS JSON - no undefined, no Date, no Map. It crosses the tool boundary
+// and a browser parses it, so one undefined rejects the whole result.
+//
+// Store and session are separate scopes because they answer different questions and have
+// different lifetimes. The store is what EXISTS; the session is what THIS conversation saw
+// and wrote. A tab can show either without pretending the other is live.
+
+import { buildLedger } from './ledger.js'
+import { LAYERS } from './entry.js'
+import { freshnessVerdict } from './freshness.js'
+import { buildInjectionText } from './inject.js'
+import { problems, summarize } from './queue.js'
+
+/** How many scopes and written entries the snapshot carries before it summarises instead. */
+const SCOPE_LIMIT = 6
+const WRITTEN_LIMIT = 8
+
+/** Doubt, worst first: a group reports the most doubtful thing inside it, not the best. */
+const SEVERITY = { fresh: 0, empty: 1, aging: 2, unverified: 3, stale: 4 }
+
+function worstVerdict(verdicts) {
+  let worst = 'fresh'
+  for (const verdict of verdicts) {
+    if ((SEVERITY[verdict] ?? 0) > (SEVERITY[worst] ?? 0)) worst = verdict
+  }
+  return worst
+}
+
+/** The workspace key a ledger file belongs to, or 'global' for the shared layer. */
+export function scopeKeyOf(file) {
+  const normalised = String(file ?? '').replace(/\\/g, '/')
+  const match = normalised.match(/workspaces\/([^/]+)\//)
+  return match ? match[1] : 'global'
+}
+
+function tally(values) {
+  const out = {}
+  for (const value of values) out[value] = (out[value] ?? 0) + 1
+  return out
+}
+
+/**
+ * Whole-store composition: entries per layer, how fresh they are, which workspaces hold
+ * them, and what the ingest queue is doing.
+ * @param store - the memory store.
+ * @param options.ledger - a prebuilt ledger, so a caller needing two scopes reads the disk once.
+ */
+export function buildStoreSnapshot(store, { ledger, now = Date.now(), scopeLimit = SCOPE_LIMIT } = {}) {
+  const entries = ledger ?? buildLedger(store.root)
+  // The verdict vocabulary belongs to the freshness module. An unrecognised verdict counts as
+  // fresh, so a new one upstream shows up as a total that does not add up - visible - rather
+  // than as a crash or a silent zero.
+  const freshness = { fresh: 0, stale: 0, expired: 0, skip: 0 }
+  for (const entry of entries) {
+    const verdict = freshnessVerdict(entry, now).verdict
+    freshness[Object.hasOwn(freshness, verdict) ? verdict : 'fresh'] += 1
+  }
+  const layerCounts = tally(entries.map((e) => e.layer))
+  const scopeCounts = tally(entries.map((e) => scopeKeyOf(e.file)))
+  const scopes = Object.keys(scopeCounts)
+    .map((key) => ({ key, count: scopeCounts[key] }))
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+  const states = summarize(store.root)
+  // Group problem rows by state and reason: 76 orphaned candidates are ONE fact about the
+  // store, not 76 lines of UI.
+  const grouped = new Map()
+  for (const problem of problems(store.root)) {
+    const reason = problem.reason ?? 'unclassified'
+    const key = problem.state + '|' + reason
+    const seen = grouped.get(key)
+    if (seen) seen.count += 1
+    else grouped.set(key, { state: problem.state, reason, count: 1 })
+  }
+  return {
+    root: store.root,
+    total: entries.length,
+    layers: LAYERS.map((name) => ({ name, count: layerCounts[name] ?? 0 })),
+    freshness,
+    scopes: scopes.slice(0, scopeLimit),
+    scopeTotal: scopes.length,
+    queue: {
+      states,
+      waiting: (states.pending ?? 0) + (states.summarized ?? 0),
+      recoverable: states.orphaned ?? 0,
+      attention: [...grouped.values()].sort((a, b) => b.count - a.count),
+    },
+  }
+}
+
+/** The marker vocabulary the injection actually emits. Matching only these keeps a bracketed
+ * word inside an entry's prose from being read as a freshness verdict. */
+const MARKER = /\[(STALE|AGING|UNVERIFIED|NOT STARTED)\b[^\]]*\]/g
+
+function verdictOfMarker(marker) {
+  if (marker.startsWith('[STALE')) return 'stale'
+  if (marker.startsWith('[AGING')) return 'aging'
+  if (marker.startsWith('[UNVERIFIED')) return 'unverified'
+  if (marker.startsWith('[NOT STARTED')) return 'empty'
+  return 'fresh'
+}
+
+/**
+ * Read the sections back out of the injection's OWN rendered text.
+ *
+ * Parsing text is usually the wrong instinct, and here it is the right one: the question the
+ * panel answers is 'what was actually put in front of this session', and the only artefact
+ * that can answer it without the possibility of disagreement is the text itself. Recomputing
+ * the sections from the same inputs would be a second implementation of one rule.
+ */
+export function parseInjectionSections(text) {
+  const sections = []
+  for (const raw of String(text ?? '').split('\n')) {
+    const heading = raw.match(/^###\s+(.+?)\s*$/)
+    if (heading) {
+      const found = heading[1].match(MARKER) ?? []
+      // The heading is written for the agent ('Working memory - yours'); the panel labels the
+      // same thing more briefly, so the owner suffix is dropped at the boundary.
+      const name = heading[1].replace(MARKER, '').replace(/\s+\u2014\s+yours\s*$/, '').trim()
+      sections.push({ name, markers: [...found] })
+      continue
+    }
+    if (sections.length === 0) continue
+    const found = raw.match(MARKER)
+    if (found) sections[sections.length - 1].markers.push(...found)
+  }
+  return sections.map((section) => {
+    const verdict = worstVerdict(section.markers.map(verdictOfMarker))
+    const marker = section.markers.find((m) => verdictOfMarker(m) === verdict) ?? ''
+    return { name: section.name, verdict, marker }
+  })
+}
+
+/** What memory put in front of this session, sized and broken down as it was sent. */
+export function buildReceived(store, { memoryScope = 'global', key, goal, maxChars } = {}) {
+  const text = buildInjectionText(store, { scope: memoryScope, key, goal, maxChars })
+  return { chars: text.length, sections: parseInjectionSections(text) }
+}
+
+/**
+ * What THIS session wrote back. Attribution is exact rather than inferred from timestamps:
+ * every write already records source 'agent:<sessionId>', so two sessions writing in the same
+ * minute are still told apart.
+ */
+export function buildWritten(store, { ledger, sessionId, limit = WRITTEN_LIMIT } = {}) {
+  if (!sessionId) return { total: 0, byLayer: {}, entries: [] }
+  const marker = 'agent:' + sessionId
+  const written = (ledger ?? buildLedger(store.root)).filter((entry) => entry.source === marker)
+  const ordered = [...written].sort((a, b) => String(b.date ?? '').localeCompare(String(a.date ?? '')))
+  return {
+    total: written.length,
+    byLayer: tally(written.map((e) => e.layer)),
+    entries: ordered.slice(0, limit).map((e) => ({ id: e.id, layer: e.layer, heading: e.heading ?? '' })),
+  }
+}
+
+/**
+ * One snapshot, either scope or both.
+ * @param options.scope - 'store' (what exists), 'session' (what this conversation saw and wrote), or 'all'.
+ * @param options.memoryScope - 'global' or 'workspace': which memory layer this session belongs to.
+ */
+export function buildMap(store, { scope = 'all', sessionId, memoryScope = 'global', key, goal, now = Date.now(), maxChars } = {}) {
+  const ledger = buildLedger(store.root)
+  const snapshot = { scope, generatedAt: new Date(now).toISOString() }
+  if (scope === 'store' || scope === 'all') snapshot.store = buildStoreSnapshot(store, { ledger, now })
+  if (scope === 'session' || scope === 'all') {
+    snapshot.session = {
+      sessionId: sessionId ?? null,
+      workspace: memoryScope === 'workspace' ? (key ?? null) : null,
+      received: buildReceived(store, { memoryScope, key, goal, maxChars }),
+      written: buildWritten(store, { ledger, sessionId }),
+    }
+  }
+  return snapshot
+}

package/src/tools.js

@@ -11,6 +11,7 @@ import { isSubagentSession } from './session.js'
 import { appendActivity, clearActivity, readWorking, workingSummary, writeWorkingSection } from './working.js'
 import { associate, listWorkspaces } from './workspace.js'
 import { forget, forgetUndo } from './forget.js'
+import { buildMap } from './map.js'
 
 function renderHits(hits) {
   if (!hits || hits.length === 0) return [{ type: 'text', text: '(no memory matches)' }]
@@ -29,6 +30,34 @@ function canonicalPath(pathArg, exec) {
   return realpathSync(abs)
 }
 
+
+/** The text face of a map snapshot: what a caller without a UI still needs to know. */
+function renderMap(value) {
+  const parts = []
+  const store = value.store
+  if (store) {
+    const layers = store.layers.filter((l) => l.count > 0).map((l) => l.name + ' ' + l.count).join(', ')
+    parts.push(store.total + ' entries at ' + store.root)
+    parts.push('layers: ' + layers)
+    const f = store.freshness
+    parts.push('freshness: ' + f.fresh + ' fresh' + (f.stale ? ', ' + f.stale + ' STALE' : '') + (f.skip ? ', ' + f.skip + ' superseded' : ''))
+    const q = store.queue
+    const attention = q.attention.length
+      ? ', needs attention: ' + q.attention.slice(0, 3).map((a) => a.count + ' ' + a.state + ' (' + a.reason + ')').join(', ')
+      : ''
+    parts.push('queue: ' + q.waiting + ' waiting' + (q.recoverable ? ', ' + q.recoverable + ' recoverable' : '') + attention)
+  }
+  const session = value.session
+  if (session) {
+    const received = session.received
+    const sections = received.sections.map((s) => s.name + (s.marker ? ' ' + s.marker : '')).join(', ')
+    parts.push('this session received ' + received.chars + ' chars: ' + (sections || '(nothing injected)'))
+    const written = session.written
+    const byLayer = Object.keys(written.byLayer).map((k) => k + ' ' + written.byLayer[k]).join(', ')
+    parts.push('and wrote ' + written.total + ' entr' + (written.total === 1 ? 'y' : 'ies') + (byLayer ? ' (' + byLayer + ')' : ''))
+  }
+  return parts.join('; ') + '.'
+}
 export function registerTools(ctx, store, extras = {}) {
   /**
    * Refuse a WRITE from a subagent session.
@@ -50,6 +79,7 @@ export function registerTools(ctx, store, extras = {}) {
   const rerankSearch = extras.rerankSearch
   const statusNow = extras.status
   const recoverNow = extras.recover
+  const injectionMaxChars = extras.injectionMaxChars
 
   ctx.tools.register(defineTool({
     name: 'memory_search',
@@ -275,6 +305,45 @@ export function registerTools(ctx, store, extras = {}) {
     },
   }))
 
+  ctx.tools.register(defineTool({
+    name: 'memory_map',
+    description: 'Show what memory holds, and what THIS session has done with it. scope "store" reports the whole store - entries per layer, freshness, workspaces, and the ingest queue. scope "session" reports what memory injected into this conversation and what this conversation wrote back. "all" returns both. Read-only, and the data behind the Memory view.',
+    parameters: {
+      scope: { type: 'string', description: 'Which view: "store" (what exists), "session" (what this conversation received and wrote), or "all" (default).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          scope: { type: 'string', required: true },
+          generatedAt: { type: 'string', required: true },
+          store: { type: 'object', additionalProperties: true },
+          session: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderMap(value) }],
+    },
+    async execute(args, exec) {
+      const scope = args.scope === 'store' || args.scope === 'session' ? args.scope : 'all'
+      // The session id is what attributes writes: every tool records source 'agent:<sessionId>'.
+      const sessionId = exec?.agent?.session?.id
+      let key
+      if (workspaceOf && exec?.agent) {
+        try { key = await workspaceOf(exec.agent) } catch { key = undefined }
+      }
+      // The goal and the char cap are read exactly as the injection reads them, so the
+      // RECEIVED panel describes the card that was actually built.
+      const goal = ctx.get('goals')?.get(exec?.agent)?.objective
+      return buildMap(store, {
+        scope,
+        sessionId,
+        memoryScope: key && key !== 'global' ? 'workspace' : 'global',
+        key: key && key !== 'global' ? key : undefined,
+        goal,
+        maxChars: injectionMaxChars,
+      })
+    },
+  }))
   ctx.tools.register(defineTool({
     name: 'memory_state',
     description: 'Record or refresh one section of the CURRENT repository state overview (what is running, the layout, what is pending, health). Replaces that section: state describes now, so a newer statement supersedes the old one. Each section carries a Verified timestamp and stale sections are reported as such.',