@ai2070/memex 0.9.0

package/src/bulk.ts

@@ -0,0 +1,128 @@
+import type {
+  GraphState,
+  MemoryItem,
+  MemoryFilter,
+  MemoryLifecycleEvent,
+  QueryOptions,
+} from "./types.js";
+import { getItems } from "./query.js";
+import { mergeItem } from "./reducer.js";
+
+export interface ScoreAdjustment {
+  authority?: number;
+  conviction?: number;
+  importance?: number;
+}
+
+function clamp(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+export type ItemTransform = (item: MemoryItem) => Partial<MemoryItem> | null;
+
+/**
+ * Apply a transform to all matching items in a single pass.
+ * Clones the items Map once, not per item.
+ */
+export function applyMany(
+  state: GraphState,
+  filter: MemoryFilter,
+  transform: ItemTransform,
+  author: string,
+  reason?: string,
+  options?: QueryOptions,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  const matched = getItems(state, filter, options);
+
+  if (matched.length === 0) {
+    return { state, events: [] };
+  }
+
+  const items = new Map(state.items);
+  const allEvents: MemoryLifecycleEvent[] = [];
+  let changed = false;
+
+  for (const item of matched) {
+    if (!items.has(item.id)) continue;
+
+    const partial = transform(item);
+
+    if (partial === null) {
+      items.delete(item.id);
+      allEvents.push({
+        namespace: "memory",
+        type: "memory.retracted",
+        item,
+        cause_type: "memory.retract",
+      });
+      changed = true;
+    } else if (Object.keys(partial).length > 0) {
+      const merged = mergeItem(item, partial);
+      items.set(item.id, merged);
+      allEvents.push({
+        namespace: "memory",
+        type: "memory.updated",
+        item: merged,
+        cause_type: "memory.update",
+      });
+      changed = true;
+    }
+  }
+
+  if (!changed) return { state, events: [] };
+
+  return { state: { items, edges: state.edges }, events: allEvents };
+}
+
+export function bulkAdjustScores(
+  state: GraphState,
+  criteria: MemoryFilter,
+  delta: ScoreAdjustment,
+  author: string,
+  reason?: string,
+  basis?: Record<string, unknown>,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  return applyMany(
+    state,
+    criteria,
+    (item) => {
+      const partial: Record<string, unknown> = {};
+      if (delta.authority !== undefined) {
+        partial.authority = clamp((item.authority ?? 0) + delta.authority);
+      }
+      if (delta.conviction !== undefined) {
+        partial.conviction = clamp((item.conviction ?? 0) + delta.conviction);
+      }
+      if (delta.importance !== undefined) {
+        partial.importance = clamp((item.importance ?? 0) + delta.importance);
+      }
+      return partial;
+    },
+    author,
+    reason,
+  );
+}
+
+/**
+ * Decay importance on items created before a cutoff time.
+ */
+export function decayImportance(
+  state: GraphState,
+  olderThanMs: number,
+  factor: number,
+  author: string,
+  reason?: string,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  const cutoff = Date.now() - olderThanMs;
+  return applyMany(
+    state,
+    { created: { before: cutoff } },
+    (item) => {
+      const current = item.importance ?? 0;
+      if (current === 0) return {};
+      return { importance: clamp(current * factor) };
+    },
+    author,
+    reason ?? "time-based importance decay",
+  );
+}

package/src/envelope.ts

@@ -0,0 +1,52 @@
+import { uuidv7 } from "uuidv7";
+import type {
+  EventEnvelope,
+  MemoryLifecycleEvent,
+  MemoryItem,
+  Edge,
+} from "./types.js";
+
+export function wrapLifecycleEvent(
+  event: MemoryLifecycleEvent,
+  causeId: string,
+  traceId?: string,
+): EventEnvelope<MemoryLifecycleEvent & { cause_id: string }> {
+  return {
+    id: uuidv7(),
+    namespace: "memory",
+    type: event.type,
+    ts: new Date().toISOString(),
+    ...(traceId ? { trace_id: traceId } : {}),
+    payload: { ...event, cause_id: causeId },
+  };
+}
+
+export function wrapStateEvent(
+  item: MemoryItem,
+  causeId: string,
+  traceId?: string,
+): EventEnvelope<{ item: MemoryItem; cause_id: string }> {
+  return {
+    id: uuidv7(),
+    namespace: "memory",
+    type: "state.memory",
+    ts: new Date().toISOString(),
+    ...(traceId ? { trace_id: traceId } : {}),
+    payload: { item, cause_id: causeId },
+  };
+}
+
+export function wrapEdgeStateEvent(
+  edge: Edge,
+  causeId: string,
+  traceId?: string,
+): EventEnvelope<{ edge: Edge; cause_id: string }> {
+  return {
+    id: uuidv7(),
+    namespace: "memory",
+    type: "state.edge",
+    ts: new Date().toISOString(),
+    ...(traceId ? { trace_id: traceId } : {}),
+    payload: { edge, cause_id: causeId },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+export class MemoryNotFoundError extends Error {
+  constructor(itemId: string) {
+    super(`Memory item not found: ${itemId}`);
+    this.name = "MemoryNotFoundError";
+  }
+}
+
+export class EdgeNotFoundError extends Error {
+  constructor(edgeId: string) {
+    super(`Edge not found: ${edgeId}`);
+    this.name = "EdgeNotFoundError";
+  }
+}
+
+export class DuplicateMemoryError extends Error {
+  constructor(itemId: string) {
+    super(`Memory item already exists: ${itemId}`);
+    this.name = "DuplicateMemoryError";
+  }
+}
+
+export class DuplicateEdgeError extends Error {
+  constructor(edgeId: string) {
+    super(`Edge already exists: ${edgeId}`);
+    this.name = "DuplicateEdgeError";
+  }
+}

package/src/graph.ts

@@ -0,0 +1,15 @@
+import type { GraphState } from "./types.js";
+
+export function createGraphState(): GraphState {
+  return {
+    items: new Map(),
+    edges: new Map(),
+  };
+}
+
+export function cloneGraphState(state: GraphState): GraphState {
+  return {
+    items: new Map(state.items),
+    edges: new Map(state.edges),
+  };
+}

package/src/helpers.ts

@@ -0,0 +1,51 @@
+import { uuidv7 } from "uuidv7";
+import type { MemoryItem, Edge, EventEnvelope } from "./types.js";
+
+function validateScore(value: number | undefined, name: string): void {
+  if (value !== undefined && (value < 0 || value > 1)) {
+    throw new RangeError(`${name} must be between 0 and 1, got ${value}`);
+  }
+}
+
+export function createMemoryItem(
+  input: Omit<MemoryItem, "id"> & { id?: string },
+): MemoryItem {
+  validateScore(input.authority, "authority");
+  validateScore(input.conviction, "conviction");
+  validateScore(input.importance, "importance");
+
+  return {
+    ...input,
+    id: input.id ?? uuidv7(),
+  };
+}
+
+export function createEdge(
+  input: Omit<Edge, "edge_id" | "active"> & {
+    edge_id?: string;
+    active?: boolean;
+  },
+): Edge {
+  validateScore(input.authority, "authority");
+
+  return {
+    ...input,
+    edge_id: input.edge_id ?? uuidv7(),
+    active: input.active ?? true,
+  };
+}
+
+export function createEventEnvelope<T>(
+  type: string,
+  payload: T,
+  opts?: { trace_id?: string },
+): EventEnvelope<T> {
+  return {
+    id: uuidv7(),
+    namespace: "memory",
+    type,
+    ts: new Date().toISOString(),
+    payload,
+    ...(opts?.trace_id ? { trace_id: opts.trace_id } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+// @ai2070/memex — Memory Layer
+// Graph of memory items and edges over an append-only event log
+
+export type {
+  KnownMemoryKind,
+  MemoryKind,
+  MemoryItem,
+  KnownEdgeKind,
+  EdgeKind,
+  Edge,
+  KnownNamespace,
+  Namespace,
+  EventEnvelope,
+  GraphState,
+  MemoryCommand,
+  LifecycleEventType,
+  MemoryLifecycleEvent,
+  MemoryFilter,
+  EdgeFilter,
+  SortField,
+  SortOption,
+  QueryOptions,
+  DecayInterval,
+  DecayType,
+  DecayConfig,
+  ScoreWeights,
+  ScoredItem,
+} from "./types.js";
+
+export {
+  createMemoryItem,
+  createEdge,
+  createEventEnvelope,
+} from "./helpers.js";
+export { createGraphState, cloneGraphState } from "./graph.js";
+export {
+  MemoryNotFoundError,
+  EdgeNotFoundError,
+  DuplicateMemoryError,
+  DuplicateEdgeError,
+} from "./errors.js";
+export { applyCommand } from "./reducer.js";
+export {
+  getItems,
+  getEdges,
+  getItemById,
+  getEdgeById,
+  getRelatedItems,
+  getParents,
+  getChildren,
+  getScoredItems,
+  extractTimestamp,
+} from "./query.js";
+export type { ScoredQueryOptions } from "./query.js";
+export { applyMany, bulkAdjustScores, decayImportance } from "./bulk.js";
+export type { ItemTransform, ScoreAdjustment } from "./bulk.js";
+export {
+  wrapLifecycleEvent,
+  wrapStateEvent,
+  wrapEdgeStateEvent,
+} from "./envelope.js";
+export { replayCommands, replayFromEnvelopes } from "./replay.js";
+export {
+  getContradictions,
+  markContradiction,
+  resolveContradiction,
+  getStaleItems,
+  getDependents,
+  cascadeRetract,
+  markAlias,
+  getAliases,
+  getAliasGroup,
+  getItemsByBudget,
+} from "./integrity.js";
+export type { Contradiction, StaleItem, BudgetOptions } from "./integrity.js";
+export {
+  getSupportTree,
+  getSupportSet,
+  filterContradictions,
+  surfaceContradictions,
+  applyDiversity,
+  smartRetrieve,
+} from "./retrieval.js";
+export type {
+  SupportNode,
+  DiversityOptions,
+  SmartRetrievalOptions,
+} from "./retrieval.js";
+export { toJSON, fromJSON, stringify, parse } from "./serialization.js";
+export type { SerializedGraphState } from "./serialization.js";
+export { getStats } from "./stats.js";
+export type { GraphStats } from "./stats.js";
+
+// Intent graph
+export {
+  createIntentState,
+  createIntent,
+  applyIntentCommand,
+  getIntents,
+  getIntentById,
+  IntentNotFoundError,
+  DuplicateIntentError,
+  InvalidIntentTransitionError,
+} from "./intent.js";
+export type {
+  IntentStatus,
+  Intent,
+  IntentState,
+  IntentCommand,
+  IntentLifecycleEvent,
+  IntentFilter,
+} from "./intent.js";
+
+// Task graph
+export {
+  createTaskState,
+  createTask,
+  applyTaskCommand,
+  getTasks,
+  getTaskById,
+  getTasksByIntent,
+  TaskNotFoundError,
+  DuplicateTaskError,
+  InvalidTaskTransitionError,
+} from "./task.js";
+export type {
+  TaskStatus,
+  Task,
+  TaskState,
+  TaskCommand,
+  TaskLifecycleEvent,
+  TaskFilter,
+} from "./task.js";
+
+// Transplant (export/import slices)
+export { exportSlice, importSlice } from "./transplant.js";
+export type {
+  ExportOptions,
+  MemexExport,
+  ImportOptions,
+  ImportReport,
+} from "./transplant.js";