@klarkxy/dsh-memory 0.1.2 → 0.1.4

package/lib/contracts.d.ts

@@ -36,6 +36,8 @@ interface DreamSnapshotEntry {
   status: MemoryRecord['status'];
   scope: KnowledgeScope;
   expiresAt?: number;
+  kind?: KnowledgeKind;
+  context?: MemoryRecord['context'];
 }
 interface DreamProposal {
   title: string;
@@ -46,6 +48,7 @@ interface DreamProposal {
   evidence: EvidenceRef[];
   sourceIds: string[];
   scope: KnowledgeScope;
+  context?: MemoryRecord['context'];
 }
 interface DreamPlan {
   id: string;
@@ -72,6 +75,12 @@ interface MemoryPersistedState {
   tombstones: MemoryTombstone[];
   dreams: DreamPlan[];
   lastAttemptAt?: number;
+  /** Bounded per-session source cursors; retained when a derived record is deleted. */
+  observations?: Array<{
+    sessionId: string;
+    seq: number;
+    updatedAt: number;
+  }>;
 }
 interface MemoryStatus {
   runningDreams?: string[];

package/lib/contracts.js

@@ -24,7 +24,9 @@ const MAX_PROJECT_ID_CHARS = 32768;
 const INJECT_KINDS = [
 	"preference",
 	"project-fact",
-	"decision"
+	"decision",
+	"vocabulary",
+	"activity"
 ];
 const RECALL_EXCLUDED_STATUSES = [
 	"candidate",

package/lib/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","names":["FROZEN_CHAT_EVENTS_SLOT","frozenProjectIdFromCwd"],"sources":["../src/contracts.ts"],"sourcesContent":["/** Browser-safe contracts. MemoryRecord / MemoryService match frozen @klarkxy/dsh-ai-services. */\nimport {\n  CHAT_EVENTS_SLOT as FROZEN_CHAT_EVENTS_SLOT,\n  projectIdFromCwd as frozenProjectIdFromCwd,\n} from '@klarkxy/dsh-ai-services/contracts'\nimport type {\n  AiFeatureScope,\n  AiServices,\n  AuxiliaryRequest,\n  AuxiliaryResult,\n  EvidenceRef,\n  KnowledgeKind,\n  KnowledgeScope,\n  MemoryQuery,\n  MemoryRecord,\n  MemoryService,\n  NewMemoryRecord,\n  PurposeSpec,\n  ProducerMessageSource,\n  RpcResult,\n  UsageReceipt,\n} from '@klarkxy/dsh-ai-services/contracts'\n\nexport type {\n  AiFeatureScope,\n  AiServices,\n  AuxiliaryRequest,\n  AuxiliaryResult,\n  EvidenceRef,\n  KnowledgeKind,\n  KnowledgeScope,\n  MemoryQuery,\n  MemoryRecord,\n  MemoryService,\n  NewMemoryRecord,\n  PurposeSpec,\n  ProducerMessageSource,\n  RpcResult,\n  UsageReceipt,\n}\n\n/** Frozen shared chat-events seat. Must stay equal to @klarkxy/dsh-ai-services CHAT_EVENTS_SLOT. */\nexport const CHAT_EVENTS_SLOT = FROZEN_CHAT_EVENTS_SLOT\n/** Shared untruncated cwd identity. Drive roots (`/` / `C:/`) stay intact. */\nexport const projectIdFromCwd = frozenProjectIdFromCwd\nexport const MEMORY_PLUGIN = '@klarkxy/dsh-memory'\nexport const MEMORY_SOURCE_KIND = 'plugin:@klarkxy/dsh-memory' as const\nexport const MEMORY_RPC_CHANNEL = '/dsh-memory'\nexport const MEMORY_DREAM_PURPOSE = 'memory.dream'\nexport const MEMORY_INJECTION_SECTION = 'dsh-memory:recall'\n/** Frozen pluginName now accepts scoped ids. */\nexport const MEMORY_ACTIVATE_ID = MEMORY_PLUGIN\n\nexport const DEFAULT_IDLE_MS = 15 * 60 * 1000\nexport const MIN_IDLE_MS = 60_000\nexport const MAX_IDLE_MS = 180 * 60_000\nexport const DREAM_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000\nexport const DREAM_MIN_MATERIAL = 3\nexport const MIN_RECALL_RECORDS = 1\nexport const MAX_RECALL_RECORDS = 5\nexport const MAX_RECALL_TOKENS = 800\nexport const MAX_PROJECT_ID_CHARS = 32_768\nexport const INJECT_KINDS: readonly KnowledgeKind[] = ['preference', 'project-fact', 'decision']\nexport const RECALL_EXCLUDED_STATUSES: readonly MemoryRecord['status'][] = [\n  'candidate', 'rejected', 'revoked', 'deleted', 'superseded',\n]\n\nexport interface MemorySettings {\n  revision: number\n  injectEnabled: boolean\n  dreamIdleEnabled: boolean\n  idleMs: number\n}\n\nexport const defaultSettings = (): MemorySettings => ({\n  revision: 0,\n  injectEnabled: true,\n  dreamIdleEnabled: true,\n  idleMs: DEFAULT_IDLE_MS,\n})\n\nexport type DreamPlanStatus = 'preview' | 'applied' | 'cancelled' | 'stale' | 'failed' | 'noop'\n\nexport interface DreamSnapshotEntry {\n  id: string\n  revision: number\n  status: MemoryRecord['status']\n  scope: KnowledgeScope\n  expiresAt?: number\n}\n\nexport interface DreamProposal {\n  title: string\n  content: string\n  kind: Exclude<KnowledgeKind, 'lesson'>\n  tags: string[]\n  exceptions: string[]\n  evidence: EvidenceRef[]\n  sourceIds: string[]\n  scope: KnowledgeScope\n}\n\nexport interface DreamPlan {\n  id: string\n  revision: number\n  sessionId: string\n  projectId?: string\n  status: DreamPlanStatus\n  sourceVersion: string\n  snapshot: DreamSnapshotEntry[]\n  proposals: DreamProposal[]\n  generation: number\n  createdAt: number\n  updatedAt: number\n  error?: string\n}\n\nexport interface MemoryTombstone {\n  id: string\n  deletedAt: number\n  lastRevision: number\n}\n\nexport interface MemoryPersistedState {\n  settings: MemorySettings\n  records: MemoryRecord[]\n  tombstones: MemoryTombstone[]\n  dreams: DreamPlan[]\n  lastAttemptAt?: number\n}\n\nexport interface MemoryStatus {\n  runningDreams?: string[]\n  settings: MemorySettings\n  records: MemoryRecord[]\n  dreams: DreamPlan[]\n  projectId?: string\n  storageFailed: boolean\n  aiAvailable: boolean\n}\n\n/** Matches frozen MemoryService optional mutation identity/lifetime guards. */\nexport interface MemoryMutationOptions { signal?: AbortSignal; isCurrent?: () => boolean }\n\nexport interface PreStepEnter {\n  kind: 'enter'\n  messages: unknown[]\n  startsRequestSeries?: true\n}\nexport type PreStepDecision = { kind: 'reject' } | PreStepEnter\n\nexport interface InjectedMemoryMessage {\n  content: Array<{ type: 'text'; text: string }>\n  source: ProducerMessageSource & {\n    kind: typeof MEMORY_SOURCE_KIND\n    plugin: typeof MEMORY_PLUGIN\n    form: 'snapshot'\n    sections: Array<{ name: string; text: string }>\n  }\n}\n\nexport function fail<T = never>(code: string, message: string): RpcResult<T> {\n  return { ok: false, error: { code, message } }\n}\n\nexport function ok<T>(value: T): RpcResult<T> {\n  return { ok: true, value }\n}\n\nexport function parseSessionId(payload: unknown): string | undefined {\n  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return undefined\n  const sessionId = (payload as { sessionId?: unknown }).sessionId\n  return typeof sessionId === 'string' && sessionId.length > 0 && sessionId.length <= 200 ? sessionId : undefined\n}\n\nexport function sessionCwd(session: unknown): string | undefined {\n  if (!session || typeof session !== 'object') return undefined\n  const row = session as { meta?: { cwd?: unknown }; header?: { cwd?: unknown } }\n  const cwd = row.meta?.cwd ?? row.header?.cwd\n  return typeof cwd === 'string' ? cwd : undefined\n}\n\nexport function scopesEqual(left: KnowledgeScope, right: KnowledgeScope): boolean {\n  if (left.kind === 'global') return right.kind === 'global'\n  return right.kind === 'project' && left.projectId === right.projectId\n}\n\nexport function scopeKey(scope: KnowledgeScope): string {\n  return scope.kind === 'global' ? 'global' : `project:${scope.projectId}`\n}\n\nexport function cloneRecord(record: MemoryRecord): MemoryRecord {\n  return structuredClone(record)\n}\n"],"mappings":";;;;AA0CA,MAAa,mBAAmBA;;AAEhC,MAAa,mBAAmBC;AAChC,MAAa,gBAAgB;AAC7B,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,uBAAuB;AACpC,MAAa,2BAA2B;;AAExC,MAAa,qBAAqB;AAElC,MAAa,kBAAkB;AAC/B,MAAa,cAAc;AAC3B,MAAa,cAAc;AAC3B,MAAa,wBAAwB;AACrC,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,oBAAoB;AACjC,MAAa,uBAAuB;AACpC,MAAa,eAAyC;CAAC;CAAc;CAAgB;AAAU;AAC/F,MAAa,2BAA8D;CACzE;CAAa;CAAY;CAAW;CAAW;AACjD;AASA,MAAa,yBAAyC;CACpD,UAAU;CACV,eAAe;CACf,kBAAkB;CAClB,QAAQ;AACV;AAkFA,SAAgB,KAAgB,MAAc,SAA+B;CAC3E,OAAO;EAAE,IAAI;EAAO,OAAO;GAAE;GAAM;EAAQ;CAAE;AAC/C;AAEA,SAAgB,GAAM,OAAwB;CAC5C,OAAO;EAAE,IAAI;EAAM;CAAM;AAC3B;AAEA,SAAgB,eAAe,SAAsC;CACnE,IAAI,CAAC,WAAW,OAAO,YAAY,YAAY,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAA;CAC9E,MAAM,YAAa,QAAoC;CACvD,OAAO,OAAO,cAAc,YAAY,UAAU,SAAS,KAAK,UAAU,UAAU,MAAM,YAAY,KAAA;AACxG;AAEA,SAAgB,WAAW,SAAsC;CAC/D,IAAI,CAAC,WAAW,OAAO,YAAY,UAAU,OAAO,KAAA;CACpD,MAAM,MAAM;CACZ,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,QAAQ;CACzC,OAAO,OAAO,QAAQ,WAAW,MAAM,KAAA;AACzC;AAEA,SAAgB,YAAY,MAAsB,OAAgC;CAChF,IAAI,KAAK,SAAS,UAAU,OAAO,MAAM,SAAS;CAClD,OAAO,MAAM,SAAS,aAAa,KAAK,cAAc,MAAM;AAC9D;AAEA,SAAgB,SAAS,OAA+B;CACtD,OAAO,MAAM,SAAS,WAAW,WAAW,WAAW,MAAM;AAC/D;AAEA,SAAgB,YAAY,QAAoC;CAC9D,OAAO,gBAAgB,MAAM;AAC/B"}
+{"version":3,"file":"contracts.js","names":["FROZEN_CHAT_EVENTS_SLOT","frozenProjectIdFromCwd"],"sources":["../src/contracts.ts"],"sourcesContent":["/** Browser-safe contracts. MemoryRecord / MemoryService match frozen @klarkxy/dsh-ai-services. */\nimport {\n  CHAT_EVENTS_SLOT as FROZEN_CHAT_EVENTS_SLOT,\n  projectIdFromCwd as frozenProjectIdFromCwd,\n} from '@klarkxy/dsh-ai-services/contracts'\nimport type {\n  AiFeatureScope,\n  AiServices,\n  AuxiliaryRequest,\n  AuxiliaryResult,\n  EvidenceRef,\n  KnowledgeKind,\n  KnowledgeScope,\n  MemoryQuery,\n  MemoryRecord,\n  MemoryService,\n  NewMemoryRecord,\n  PurposeSpec,\n  ProducerMessageSource,\n  RpcResult,\n  UsageReceipt,\n} from '@klarkxy/dsh-ai-services/contracts'\n\nexport type {\n  AiFeatureScope,\n  AiServices,\n  AuxiliaryRequest,\n  AuxiliaryResult,\n  EvidenceRef,\n  KnowledgeKind,\n  KnowledgeScope,\n  MemoryQuery,\n  MemoryRecord,\n  MemoryService,\n  NewMemoryRecord,\n  PurposeSpec,\n  ProducerMessageSource,\n  RpcResult,\n  UsageReceipt,\n}\n\n/** Frozen shared chat-events seat. Must stay equal to @klarkxy/dsh-ai-services CHAT_EVENTS_SLOT. */\nexport const CHAT_EVENTS_SLOT = FROZEN_CHAT_EVENTS_SLOT\n/** Shared untruncated cwd identity. Drive roots (`/` / `C:/`) stay intact. */\nexport const projectIdFromCwd = frozenProjectIdFromCwd\nexport const MEMORY_PLUGIN = '@klarkxy/dsh-memory'\nexport const MEMORY_SOURCE_KIND = 'plugin:@klarkxy/dsh-memory' as const\nexport const MEMORY_RPC_CHANNEL = '/dsh-memory'\nexport const MEMORY_DREAM_PURPOSE = 'memory.dream'\nexport const MEMORY_INJECTION_SECTION = 'dsh-memory:recall'\n/** Frozen pluginName now accepts scoped ids. */\nexport const MEMORY_ACTIVATE_ID = MEMORY_PLUGIN\n\nexport const DEFAULT_IDLE_MS = 15 * 60 * 1000\nexport const MIN_IDLE_MS = 60_000\nexport const MAX_IDLE_MS = 180 * 60_000\nexport const DREAM_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000\nexport const DREAM_MIN_MATERIAL = 3\nexport const MIN_RECALL_RECORDS = 1\nexport const MAX_RECALL_RECORDS = 5\nexport const MAX_RECALL_TOKENS = 800\nexport const MAX_PROJECT_ID_CHARS = 32_768\nexport const INJECT_KINDS: readonly KnowledgeKind[] = ['preference', 'project-fact', 'decision', 'vocabulary', 'activity']\nexport const RECALL_EXCLUDED_STATUSES: readonly MemoryRecord['status'][] = [\n  'candidate', 'rejected', 'revoked', 'deleted', 'superseded',\n]\n\nexport interface MemorySettings {\n  revision: number\n  injectEnabled: boolean\n  dreamIdleEnabled: boolean\n  idleMs: number\n}\n\nexport const defaultSettings = (): MemorySettings => ({\n  revision: 0,\n  injectEnabled: true,\n  dreamIdleEnabled: true,\n  idleMs: DEFAULT_IDLE_MS,\n})\n\nexport type DreamPlanStatus = 'preview' | 'applied' | 'cancelled' | 'stale' | 'failed' | 'noop'\n\nexport interface DreamSnapshotEntry {\n  id: string\n  revision: number\n  status: MemoryRecord['status']\n  scope: KnowledgeScope\n  expiresAt?: number\n  kind?: KnowledgeKind\n  context?: MemoryRecord['context']\n}\n\nexport interface DreamProposal {\n  title: string\n  content: string\n  kind: Exclude<KnowledgeKind, 'lesson'>\n  tags: string[]\n  exceptions: string[]\n  evidence: EvidenceRef[]\n  sourceIds: string[]\n  scope: KnowledgeScope\n  context?: MemoryRecord['context']\n}\n\nexport interface DreamPlan {\n  id: string\n  revision: number\n  sessionId: string\n  projectId?: string\n  status: DreamPlanStatus\n  sourceVersion: string\n  snapshot: DreamSnapshotEntry[]\n  proposals: DreamProposal[]\n  generation: number\n  createdAt: number\n  updatedAt: number\n  error?: string\n}\n\nexport interface MemoryTombstone {\n  id: string\n  deletedAt: number\n  lastRevision: number\n}\n\nexport interface MemoryPersistedState {\n  settings: MemorySettings\n  records: MemoryRecord[]\n  tombstones: MemoryTombstone[]\n  dreams: DreamPlan[]\n  lastAttemptAt?: number\n  /** Bounded per-session source cursors; retained when a derived record is deleted. */\n  observations?: Array<{ sessionId: string; seq: number; updatedAt: number }>\n}\n\nexport interface MemoryStatus {\n  runningDreams?: string[]\n  settings: MemorySettings\n  records: MemoryRecord[]\n  dreams: DreamPlan[]\n  projectId?: string\n  storageFailed: boolean\n  aiAvailable: boolean\n}\n\n/** Matches frozen MemoryService optional mutation identity/lifetime guards. */\nexport interface MemoryMutationOptions { signal?: AbortSignal; isCurrent?: () => boolean }\n\nexport interface PreStepEnter {\n  kind: 'enter'\n  messages: unknown[]\n  startsRequestSeries?: true\n}\nexport type PreStepDecision = { kind: 'reject' } | PreStepEnter\n\nexport interface InjectedMemoryMessage {\n  content: Array<{ type: 'text'; text: string }>\n  source: ProducerMessageSource & {\n    kind: typeof MEMORY_SOURCE_KIND\n    plugin: typeof MEMORY_PLUGIN\n    form: 'snapshot'\n    sections: Array<{ name: string; text: string }>\n  }\n}\n\nexport function fail<T = never>(code: string, message: string): RpcResult<T> {\n  return { ok: false, error: { code, message } }\n}\n\nexport function ok<T>(value: T): RpcResult<T> {\n  return { ok: true, value }\n}\n\nexport function parseSessionId(payload: unknown): string | undefined {\n  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return undefined\n  const sessionId = (payload as { sessionId?: unknown }).sessionId\n  return typeof sessionId === 'string' && sessionId.length > 0 && sessionId.length <= 200 ? sessionId : undefined\n}\n\nexport function sessionCwd(session: unknown): string | undefined {\n  if (!session || typeof session !== 'object') return undefined\n  const row = session as { meta?: { cwd?: unknown }; header?: { cwd?: unknown } }\n  const cwd = row.meta?.cwd ?? row.header?.cwd\n  return typeof cwd === 'string' ? cwd : undefined\n}\n\nexport function scopesEqual(left: KnowledgeScope, right: KnowledgeScope): boolean {\n  if (left.kind === 'global') return right.kind === 'global'\n  return right.kind === 'project' && left.projectId === right.projectId\n}\n\nexport function scopeKey(scope: KnowledgeScope): string {\n  return scope.kind === 'global' ? 'global' : `project:${scope.projectId}`\n}\n\nexport function cloneRecord(record: MemoryRecord): MemoryRecord {\n  return structuredClone(record)\n}\n"],"mappings":";;;;AA0CA,MAAa,mBAAmBA;;AAEhC,MAAa,mBAAmBC;AAChC,MAAa,gBAAgB;AAC7B,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,uBAAuB;AACpC,MAAa,2BAA2B;;AAExC,MAAa,qBAAqB;AAElC,MAAa,kBAAkB;AAC/B,MAAa,cAAc;AAC3B,MAAa,cAAc;AAC3B,MAAa,wBAAwB;AACrC,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,oBAAoB;AACjC,MAAa,uBAAuB;AACpC,MAAa,eAAyC;CAAC;CAAc;CAAgB;CAAY;CAAc;AAAU;AACzH,MAAa,2BAA8D;CACzE;CAAa;CAAY;CAAW;CAAW;AACjD;AASA,MAAa,yBAAyC;CACpD,UAAU;CACV,eAAe;CACf,kBAAkB;CAClB,QAAQ;AACV;AAuFA,SAAgB,KAAgB,MAAc,SAA+B;CAC3E,OAAO;EAAE,IAAI;EAAO,OAAO;GAAE;GAAM;EAAQ;CAAE;AAC/C;AAEA,SAAgB,GAAM,OAAwB;CAC5C,OAAO;EAAE,IAAI;EAAM;CAAM;AAC3B;AAEA,SAAgB,eAAe,SAAsC;CACnE,IAAI,CAAC,WAAW,OAAO,YAAY,YAAY,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAA;CAC9E,MAAM,YAAa,QAAoC;CACvD,OAAO,OAAO,cAAc,YAAY,UAAU,SAAS,KAAK,UAAU,UAAU,MAAM,YAAY,KAAA;AACxG;AAEA,SAAgB,WAAW,SAAsC;CAC/D,IAAI,CAAC,WAAW,OAAO,YAAY,UAAU,OAAO,KAAA;CACpD,MAAM,MAAM;CACZ,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,QAAQ;CACzC,OAAO,OAAO,QAAQ,WAAW,MAAM,KAAA;AACzC;AAEA,SAAgB,YAAY,MAAsB,OAAgC;CAChF,IAAI,KAAK,SAAS,UAAU,OAAO,MAAM,SAAS;CAClD,OAAO,MAAM,SAAS,aAAa,KAAK,cAAc,MAAM;AAC9D;AAEA,SAAgB,SAAS,OAA+B;CACtD,OAAO,MAAM,SAAS,WAAW,WAAW,WAAW,MAAM;AAC/D;AAEA,SAAgB,YAAY,QAAoC;CAC9D,OAAO,gBAAgB,MAAM;AAC/B"}

package/lib/index.d.ts

@@ -23,6 +23,8 @@ declare class MemoryRuntime implements MemoryService {
   private pending;
   private ai?;
   private unregisterPurpose?;
+  private unregisterObserverPurpose?;
+  private readonly observationJobs;
   private readonly jobs;
   private readonly now;
   private readonly customId?;
@@ -48,6 +50,9 @@ declare class MemoryRuntime implements MemoryService {
     signal: AbortSignal;
     next: () => Promise<PreStepDecision>;
   }): Promise<PreStepDecision>;
+  /** Bounded human-only observation, independent of editor services and idle consolidation. */
+  observeSession(sessionId: string, session: unknown, signal: AbortSignal): Promise<void>;
+  private collectContext;
   previewDream(sessionId: string, projectId: string | undefined, trigger?: 'manual' | 'idle'): Promise<DreamPlan>;
   runIdleDream(sessionId: string, projectId: string | undefined, trigger?: 'manual' | 'idle'): Promise<DreamPlan>;
   get dreamLastAttemptAt(): number | undefined;