@kestrel-agents/memory

Use this package when an application needs governed retrieval across Kestrel memory backends. It provides strict lifecycle, policy, read-binding, query, result, and provenance contracts together with a trusted MemoryGateway.

Install

pnpm add @kestrel-agents/memory@0.8.5

Node.js 20 or newer is required.

Core APIs

Backends and MemoryGateway

MemoryGateway owns authorization and canonical result validation. A MemoryBackendAdapterV1 owns storage-specific retrieval and publishes a descriptor tied to one namespace and policy revision. The in-memory backend is for development and tests; production persistence remains application-owned.

Query authorized memory

import {
  InMemoryMemoryBackend,
  MemoryGateway,
  createMemoryTierPolicyV1,
  parseMemoryQueryV1,
} from "@kestrel-agents/memory";
 
const policy = createMemoryTierPolicyV1({
  tierPolicyId: "semantic-knowledge",
  namespace: "semantic_knowledge",
  writerAuthorities: ["knowledge-ingest"],
  readerAuthorities: ["agent-runtime"],
  sourceOfTruth: "hosted_knowledge_store",
  retention: { mode: "indefinite" },
  lifecyclePolicyId: "semantic-knowledge-lifecycle",
});
 
const backend = new InMemoryMemoryBackend({
  backendId: "local-memory",
  policyRevision: policy.revision,
});
 
const result = await new MemoryGateway().query({
  context: {
    tenantId: "acme",
    userId: "user-1",
    agentId: "agent-1",
    taskId: "task-1",
    issuerKind: "trusted_runtime",
    issuerAuthorityId: "agent-runtime",
    policyRevision: policy.revision,
    now: "2026-08-04T00:00:00.000Z",
  },
  binding: {
    version: "memory_read_binding_v1",
    bindingId: "binding-1",
    tenantId: "acme",
    userId: "user-1",
    agentId: "agent-1",
    taskId: "task-1",
    policyRevision: policy.revision,
    permittedNamespaces: ["semantic_knowledge"],
    permittedScopes: [{ kind: "tenant", tenantId: "acme" }],
    documentAccess: { mode: "scope" },
    issuer: { kind: "trusted_runtime", authorityId: "agent-runtime" },
    issuedAt: "2026-08-04T00:00:00.000Z",
  },
  query: parseMemoryQueryV1({
    version: "memory_query_v1",
    queryId: "query-1",
    namespace: "semantic_knowledge",
    scope: { kind: "tenant", tenantId: "acme" },
    text: "deployment policy",
    limit: 10,
  }),
  backend,
});

Canonical results and provenance

Results identify query, backend, namespace, policy revision, canonical grouping, and source/evaluator provenance. Consumers must not replace those fields with a private routing score or merge results across unauthorized scopes.

Mutations and idempotency

The public 0.8 gateway owns reads. Applications own ingestion and mutation through their trusted backend boundary, enforce writer authority, validate canonical content, retain source provenance, and require an idempotency key. A read binding never authorizes a write.

Security boundary

• The model supplies only the bounded query. It cannot widen the trusted read binding.
• Bindings are exact to tenant, user, agent, task, policy revision, namespace, and scope.
• Backends return source and evaluator provenance instead of a routing score.
• Persisted and network values must pass the exported parsers before use.
• Application code remains responsible for issuing bindings from trusted runtime authority.

Compatibility and persistence ownership

Use the exact 0.8 Memory package with the 0.8 integration. Session history, SDK-managed session memory, Kestrel One Knowledge, and a governed Memory backend are different stores with explicit owners and retention.

Read Session memory for SDK-managed session state or Security for the broader runtime authority model.