Memory Types

Type definitions for memory layers, hooks, storage adapters, and projection policies in Noetic.

MemoryLayer

The core memory layer interface.

interface MemoryLayer<TState = unknown> {
  id: string;
  name: string;
  slot: number;
  scope: MemoryScope;
  budget?: BudgetConfig;
  hooks: MemoryHooks<TState>;
  timeouts?: Partial<LayerTimeouts>;
}

Field	Type	Required	Description
`id`	`string`	yes	Unique layer identifier
`name`	`string`	yes	Human-readable name
`slot`	`number`	yes	Ordering priority (lower = earlier in prompt)
`scope`	`MemoryScope`	yes	Persistence boundary
`budget`	`BudgetConfig`	no	Token budget allocation
`hooks`	`MemoryHooks<TState>`	yes	Lifecycle callbacks
`timeouts`	`Partial<LayerTimeouts>`	no	Per-hook timeout overrides (ms)

MemoryScope

type MemoryScope = 'thread' | 'resource' | 'global' | 'execution';

BudgetConfig

type BudgetConfig =
  | number
  | { min: number; max: number }
  | 'auto';

Slot Constants

const Slot = {
  WORKING_MEMORY: 100,
  ENTITY: 150,
  OBSERVATIONS: 200,
  PROCEDURAL: 250,
  EPISODIC: 300,
  RAG: 350,
  SEMANTIC_RECALL: 400,
} as const;

MemoryHooks

interface MemoryHooks<TState = unknown> {
  init?: (params: InitParams) => Promise<InitResult<TState>>;
  recall?: (params: RecallParams<TState>) => Promise<RecallResult<TState> | null>;
  store?: (params: StoreParams<TState>) => Promise<StoreResult<TState> | undefined>;
  onSpawn?: (params: SpawnParams<TState>) => Promise<SpawnResult<TState> | null>;
  onReturn?: (params: ReturnParams<TState>) => Promise<ReturnResult<TState> | undefined>;
  onComplete?: (params: CompleteParams<TState>) => Promise<void | { state: TState }>;
  dispose?: (params: DisposeParams<TState>) => Promise<void>;
}

Hook Parameter Types

InitParams

Field	Type	Description
`storage`	`ScopedStorage`	Scoped storage for this layer
`scopeKey`	`string`	Resolved scope key
`ctx`	`ExecutionContext`	Execution context

InitResult

Field	Type	Description
`state`	`TState`	Initial layer state

RecallParams

Field	Type	Description
`log`	`ItemLog`	Current conversation log
`query`	`string`	Current user query
`ctx`	`ExecutionContext`	Execution context
`state`	`TState`	Current layer state
`budget`	`number`	Allocated token budget

RecallResult

Field	Type	Description
`items`	`Item[]`	Items to inject into the prompt
`tokenCount`	`number`	Tokens consumed by the items
`state`	`TState`	Updated state (optional)

StoreParams

Field	Type	Description
`newItems`	`Item[]`	New items from the LLM response
`log`	`ItemLog`	Full conversation log
`response`	`LLMResponse`	Complete LLM response
`ctx`	`ExecutionContext`	Execution context
`state`	`TState`	Current layer state

StoreResult

Field	Type	Description
`state`	`TState`	Updated state

SpawnParams

Field	Type	Description
`parentState`	`TState`	Parent layer state
`childCtx`	`ExecutionContext`	Child execution context

SpawnResult

Field	Type	Description
`childState`	`TState \| null`	State for the child (null = don't propagate)
`items`	`Item[]`	Additional items for the child (optional)

ReturnParams

Field	Type	Description
`childState`	`TState`	Child's final state
`childLog`	`ItemLog`	Child's conversation log
`parentState`	`TState`	Parent's current state
`result`	`unknown`	Child's completion result

ReturnResult

Field	Type	Description
`parentState`	`TState`	Updated parent state
`result`	`unknown`	Transformed result for pipeline (optional)

CompleteParams

Field	Type	Description
`log`	`ItemLog`	Full conversation log
`ctx`	`ExecutionContext`	Execution context
`state`	`TState`	Current layer state
`outcome`	`ExecutionOutcome`	How the execution ended

DisposeParams

Field	Type	Description
`state`	`TState`	Final layer state

ExecutionOutcome

type ExecutionOutcome = 'success' | 'failure' | 'aborted';

ExecutionContext

Context available to memory layer hooks (different from the step Context).

interface ExecutionContext {
  executionId: string;
  threadId: string;
  resourceId?: string;
  depth: number;
  stepNumber: number;
  tokenUsage: { input: number; output: number };
  cost: number;
  model?: string;
  tokenize(text: string): number;
  trace: {
    setAttribute(key: string, value: string | number | boolean): void;
    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
  };
}

LayerTimeouts

Field	Type	Description
`init`	`number`	Timeout for init hook (ms, optional)
`recall`	`number`	Timeout for recall hook (ms, optional)
`store`	`number`	Timeout for store hook (ms, optional)
`onSpawn`	`number`	Timeout for onSpawn hook (ms, optional)
`onReturn`	`number`	Timeout for onReturn hook (ms, optional)
`onComplete`	`number`	Timeout for onComplete hook (ms, optional)
`dispose`	`number`	Timeout for dispose hook (ms, optional)

ProjectionPolicy

interface ProjectionPolicy {
  tokenBudget: number;
  responseReserve: number;
  overflow: 'truncate' | 'summarize' | 'sliding_window';
  overflowModel?: string;
  windowSize?: number;
}

Field	Type	Required	Description
`tokenBudget`	`number`	yes	Total token budget for all layers
`responseReserve`	`number`	yes	Tokens reserved for the model response
`overflow`	`'truncate' \| 'summarize' \| 'sliding_window'`	yes	Strategy when total recall exceeds budget
`overflowModel`	`string`	no	Model for summarization overflow
`windowSize`	`number`	no	Items to keep for sliding window overflow

StorageAdapter

interface StorageAdapter {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix: string): Promise<string[]>;
}

Method	Description
`get(key)`	Retrieve a value by key (returns null if not found)
`set(key, value)`	Store a value
`delete(key)`	Delete a value
`list(prefix)`	List all keys with the given prefix

ScopedStorage

Same interface as StorageAdapter but scoped to a specific layer and scope key.

interface ScopedStorage {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix?: string): Promise<string[]>;
}

MemoryTraceSpan

Observability data for a single memory hook execution.

interface MemoryTraceSpan {
  layerId: string;
  hook: 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onComplete' | 'dispose';
  durationMs: number;
  status: 'ok' | 'error' | 'timeout' | 'skipped';
  budget?: { allocated: number; used: number; yielded: number };
  itemCount?: number;
  error?: { message: string; stack?: string };
}

Memory Types

On this page