runtime-memory

Runtime memory primitives for agent systems.

Install

npm install @devcodex-labs/runtime-memory

Quick Start

import {
  InMemoryMemoryStore,
  createContextBuilder,
} from '@devcodex-labs/runtime-memory';

const memory = new InMemoryMemoryStore();

memory.upsert({
  id: 'fact-1',
  type: 'memory.fact',
  content: 'The runtime-memory package owns context construction and memory retrieval.',
  namespace: 'agent-runtime',
  priority: 10,
});

const context = await createContextBuilder({
  memory,
  budget: { maxTokens: 2048 },
})
  .addItem({
    id: 'task',
    type: 'task.input',
    content: 'Build an agent runtime context.',
    priority: 100,
  })
  .addMemoryQuery({ namespace: 'agent-runtime' })
  .build();

console.log(context.snapshot.digest);

Runtime Surface

• ContextItem is the portable unit passed through context construction, retrieval, budgeting, compression, and snapshots.
• MemoryStore defines the persistence boundary for memory records.
• InMemoryMemoryStore provides a deterministic in-memory implementation for tests and small runtimes.
• retrieveContextItems(store, options) converts memory records into context items with namespace, tag, text, and score filtering.
• applyContextBudget(items, policy) selects items under a token budget using priority and score ordering.
• ContextCompressor allows rejected items to be summarized back into a budgeted context.
• createContextBuilder(options) composes direct items, memory queries, budget selection, compression, and snapshot creation.
• createContextSnapshot(items, budget) produces a stable SHA-256 digest for audit and replay.

Package Boundary

@devcodex-labs/runtime-memory does not execute agent tasks or tools. Use it alongside @devcodex-labs/agent-runtime when a runtime needs a bounded, inspectable context input layer.

Release

Releases are tag-driven. A vX.Y.Z tag must match package.json version X.Y.Z; the publish workflow validates that before npm publish --provenance --access public.

License

Apache-2.0