@trylucy/agent-memory 0.0.0-stage → 0.1.2

package/schemas/v1/replace-proposal-request.schema.json

@@ -0,0 +1,46 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/replace-proposal-request.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "content": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/content"
+    },
+    "expected_version": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/expectedVersion"
+    },
+    "idempotency_key": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/idempotencyKey"
+    },
+    "justification": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/justification"
+    },
+    "key": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/key"
+    },
+    "memory_id": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/memoryId"
+    },
+    "operation": {
+      "const": "replace"
+    },
+    "scope": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/scope"
+    },
+    "source_ref": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/sourceRef"
+    }
+  },
+  "required": [
+    "operation",
+    "memory_id",
+    "expected_version",
+    "key",
+    "scope",
+    "content",
+    "justification",
+    "idempotency_key"
+  ],
+  "title": "Replace memory proposal request",
+  "type": "object"
+}

package/schemas/v1/replace-transition.schema.json

@@ -0,0 +1,19 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/replace-transition.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "current": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/memory.schema.json"
+    },
+    "proposal": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/replace-proposal-request.schema.json"
+    }
+  },
+  "required": [
+    "current",
+    "proposal"
+  ],
+  "title": "Replacement transition validation envelope",
+  "type": "object"
+}

package/schemas/v1/scope.schema.json

@@ -0,0 +1,10 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/scope.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/scope"
+    }
+  ],
+  "title": "Memory scope"
+}

package/scripts/lib/am01.mjs

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const CONTRACT_PATH = "contracts/agent-memory-api.contract.json";
+export const EXPECTED_CONTRACT_VERSION = "2026-08-09";
+export const EXPECTED_SCHEMA_VERSION = "1";
+export const SCHEMA_BASE = "https://schemas.trylucy.ai/agent-memory/v1/";
+
+export async function loadJson(relativePath) {
+  return JSON.parse(await readFile(path.join(ROOT, relativePath), "utf8"));
+}
+export async function loadContract() { return loadJson(CONTRACT_PATH); }
+export async function loadFixtureManifest() { return loadJson("fixtures/v1/manifest.json"); }
+async function filesUnder(relativeDir, suffix) {
+  const dir = path.join(ROOT, relativeDir);
+  const names = await readdir(dir, { recursive: true });
+  return names
+    .filter((name) => name.endsWith(suffix))
+    .map((name) => name.split(path.sep).join("/"))
+    .sort()
+    .map((name) => path.posix.join(relativeDir, name));
+}
+export async function compilePublicSchemas() {
+  const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: true });
+  addFormats(ajv);
+  const paths = await filesUnder("schemas/v1", ".schema.json");
+  const schemas = await Promise.all(paths.map(loadJson));
+  for (const schema of schemas) ajv.addSchema(schema);
+  for (const schema of schemas) ajv.getSchema(schema.$id);
+  return { ajv, schemaCount: schemas.length, paths };
+}
+function scopesEqual(left, right) {
+  if (!left || !right || left.kind !== right.kind) return false;
+  return left.id === right.id;
+}
+function semanticError(keyword, instancePath) {
+  return { instancePath, keyword, schemaPath: `#/semantic/${keyword}` };
+}
+export function isExpectedVersionSuccessor(expectedVersion, memoryVersion) {
+  return Number.isSafeInteger(expectedVersion)
+    && expectedVersion >= 1
+    && expectedVersion < Number.MAX_SAFE_INTEGER
+    && Number.isSafeInteger(memoryVersion)
+    && memoryVersion === Number(BigInt(expectedVersion) + 1n);
+}
+function memoryReceiptErrors(value, basePath = "") {
+  if (!value?.receipt) return [];
+  const checks = [
+    ["receiptMemoryId", `${basePath}/receipt/memory_id`, value.id === value.receipt.memory_id],
+    ["receiptVersion", `${basePath}/receipt/memory_version`, value.version === value.receipt.memory_version],
+    ["receiptKey", `${basePath}/receipt/key`, value.key === value.receipt.key],
+    ["receiptKind", `${basePath}/receipt/kind`, value.kind === value.receipt.kind],
+    ["receiptScope", `${basePath}/receipt/scope`, scopesEqual(value.scope, value.receipt.scope)],
+    ["receiptLifecycle", `${basePath}/receipt/lifecycle`, value.status === value.receipt.lifecycle]
+  ];
+  return checks.filter(([, , valid]) => !valid).map(([keyword, instancePath]) => semanticError(keyword, instancePath));
+}
+function proposalStatusErrors(value) {
+  if (value.status !== "approved" || !value.result) return [];
+  const errors = [];
+  if (value.operation === "create" && value.result.memory_version !== 1) {
+    errors.push(semanticError("proposalResultVersion", "/result/memory_version"));
+  }
+  if (value.operation === "replace") {
+    if (value.result.memory_id !== value.requested.memory_id) {
+      errors.push(semanticError("proposalResultMemoryId", "/result/memory_id"));
+    }
+    if (!isExpectedVersionSuccessor(value.requested.expected_version, value.result.memory_version)) {
+      errors.push(semanticError("proposalResultVersion", "/result/memory_version"));
+    }
+  }
+  return errors;
+}
+function semanticErrors(schemaId, value) {
+  if (schemaId === `${SCHEMA_BASE}memory.schema.json`) return memoryReceiptErrors(value);
+  if (schemaId === `${SCHEMA_BASE}proposal-status.schema.json`) return proposalStatusErrors(value);
+  if (schemaId === `${SCHEMA_BASE}recall-response.schema.json`) {
+    return (value.results ?? []).flatMap((memory, index) => [
+      ...memoryReceiptErrors(memory, `/results/${index}`),
+      ...(scopesEqual(value.scope, memory.scope)
+        ? []
+        : [semanticError("recallScope", `/results/${index}/scope`)])
+    ]);
+  }
+  if (schemaId !== `${SCHEMA_BASE}replace-transition.schema.json`) return [];
+  const errors = [...memoryReceiptErrors(value.current, "/current")];
+  if (value.current.id !== value.proposal.memory_id) errors.push(semanticError("stableMemoryId", "/proposal/memory_id"));
+  if (value.current.version !== value.proposal.expected_version) errors.push(semanticError("expectedVersion", "/proposal/expected_version"));
+  if (value.current.key !== value.proposal.key) errors.push(semanticError("stableKey", "/proposal/key"));
+  if (!scopesEqual(value.current.scope, value.proposal.scope)) errors.push(semanticError("stableScope", "/proposal/scope"));
+  return errors;
+}
+export async function validateFixture(registry, fixture) {
+  const value = await loadJson(fixture.file);
+  const validate = registry.ajv.getSchema(fixture.schema);
+  assert.ok(validate, `unknown fixture schema: ${fixture.schema}`);
+  const structural = validate(value);
+  const errors = [
+    ...(validate.errors ?? []).map(({ instancePath, keyword, params, schemaPath }) => ({ instancePath, keyword, params, schemaPath })),
+    ...semanticErrors(fixture.schema, value)
+  ];
+  return {
+    valid: Boolean(structural) && errors.length === 0,
+    keywords: errors.map(({ keyword }) => keyword),
+    errors,
+    message: JSON.stringify(errors)
+  };
+}
+export async function verifyFrozenContract(contract) {
+  contract ??= await loadContract();
+  assert.equal(contract.contract_version, EXPECTED_CONTRACT_VERSION);
+  assert.equal(contract.public_schema_version, EXPECTED_SCHEMA_VERSION);
+  assert.deepEqual(contract.public_permissions, ["memory:read", "memory:propose"]);
+  assert.deepEqual(contract.mcp_tools, ["memory_recall", "memory_propose", "memory_proposal_status"]);
+  assert.equal(contract.identity.account_source, "server-derived");
+  assert.equal(contract.identity.tenant_source, "server-derived");
+  assert.equal(contract.identity.client_may_supply_account, false);
+  assert.equal(contract.identity.client_may_supply_tenant, false);
+  assert.equal(contract.identity.maximum_active_per_conflict_identity, 1);
+  assert.equal(contract.create.may_replace_active, false);
+  assert.equal(contract.create.approved_memory_version, 1);
+  assert.equal(contract.replace.retains_memory_id, true);
+  assert.equal(contract.replace.expected_version_maximum, Number.MAX_SAFE_INTEGER - 1);
+  assert.equal(contract.replace.maximum_memory_version, Number.MAX_SAFE_INTEGER);
+  assert.equal(contract.replace.new_version_rule, "expected_version + 1");
+  assert.equal(contract.proposal.payload_immutable_after_acceptance, true);
+  assert.equal(contract.proposal.proposal_supersession_distinct_from_memory_version_supersession, true);
+  assert.equal(contract.recall.canonical_active_state_rejoin_required, true);
+  assert.equal(contract.recall.asynchronous_index_is_not_authority, true);
+  assert.equal(contract.receipts.version_specific, true);
+  assert.equal(contract.receipts.authority_types.length, 1);
+  assert.equal(contract.receipts.authority_types[0], "human_approved");
+  assert.equal(contract.forgetting.physical_deletion_everywhere_promised, false);
+  assert.ok(contract.rule_non_authorities.includes("approval authority"));
+  assert.ok(contract.forbidden_public_permissions.includes("memory:write"));
+  assert.ok(contract.forbidden_mcp_capabilities.includes("memory_resolve"));
+  return true;
+}
+function digest(buffer) { return createHash("sha256").update(buffer).digest("hex"); }
+export async function currentHashes() {
+  const schemaPaths = await filesUnder("schemas/v1", ".schema.json");
+  const contractBytes = await readFile(path.join(ROOT, CONTRACT_PATH));
+  const schemas = {};
+  for (const schemaPath of schemaPaths) schemas[schemaPath] = digest(await readFile(path.join(ROOT, schemaPath)));
+  return { algorithm: "sha256", contract: { path: CONTRACT_PATH, sha256: digest(contractBytes) }, schemas };
+}
+export async function verifyHashes() {
+  const expected = await loadJson("contracts/hashes.json");
+  const actual = await currentHashes();
+  const valid = JSON.stringify(expected) === JSON.stringify(actual);
+  return { valid, message: valid ? "hashes verified" : `hash mismatch\nexpected=${JSON.stringify(expected)}\nactual=${JSON.stringify(actual)}` };
+}
+export { ROOT };

package/src/client/canonical-validation.mjs

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { MalformedResponseError } from './errors.mjs';
+
+const schemaPath = fileURLToPath(new URL('../../schemas/canonical-recall/response.schema.json', import.meta.url));
+const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+addFormats(ajv);
+const validate = ajv.compile(schema);
+
+function matchesScope(left, right) { return left?.kind === right?.kind && left?.id === right?.id; }
+
+export function canonicalRecallOutputSchema() { return structuredClone(schema); }
+
+export function validateCanonicalRecallResponse(value, request) {
+  if (!validate(value)) {
+    const details = validate.errors?.map(({ instancePath, keyword, schemaPath: path }) => ({ instancePath, keyword, schemaPath: path }));
+    throw new MalformedResponseError('Canonical recall response violates the strict canonical schema.', { details });
+  }
+  if (!request || !matchesScope(value.scope, request.scope)) throw new MalformedResponseError('Canonical recall response scope does not match the request.');
+  if (value.results.length > (request.limit ?? 3)) throw new MalformedResponseError('Canonical recall response exceeds the requested limit.');
+  for (const result of value.results) {
+    if (!matchesScope(result.scope, value.scope) || !matchesScope(result.scope, request.scope)
+      || result.provenance.record_id !== result.record_id) {
+      throw new MalformedResponseError('Canonical recall response violates scope or provenance record binding.');
+    }
+    if (request.keys && (result.key === null || !request.keys.includes(result.key))) {
+      throw new MalformedResponseError('Canonical recall response violates the requested key filter.');
+    }
+    if (request.kinds && !request.kinds.includes(result.kind)) {
+      throw new MalformedResponseError('Canonical recall response violates the requested kind filter.');
+    }
+  }
+  return value;
+}

package/src/client/client.mjs

@@ -0,0 +1,151 @@
+import {
+  AgentMemoryError, AuthenticationFailureError, AuthorizationFailureError, InternalLucyError, InvalidScopeError,
+  LifecycleConflictError, MalformedResponseError, MemoryNotFoundError, ProposalNotFoundError, RateLimitError,
+  TimeoutError, UpstreamUnavailableError, ValidationFailureError, VersionConflictError,
+  InsufficientCreditsError, BillingUnavailableError,
+} from './errors.mjs';
+import { parseRequestJson, stableSerialize } from './serialization.mjs';
+import {
+  toProposalRequestDto, toProposalStatusRequestDto, toRecallRequestDto, validateErrorResponse,
+  validateProposalResponse, validateRecallResponse,
+} from './validation.mjs';
+import { validateCanonicalRecallResponse } from './canonical-validation.mjs';
+
+const REQUEST_LIMITS = Object.freeze({ recall: 8192, 'canonical-recall': 8192, propose: 12288 });
+// Match the existing canonical recall request_id limit without changing the public error schema.
+const MAX_PUBLIC_ERROR_REQUEST_ID_LENGTH = 256;
+const PUBLIC_ERROR_REQUEST_ID = /^req_[A-Za-z0-9_-]+$/;
+const MAPPED_ERROR_REQUEST_IDS = new WeakMap();
+
+export function safePublicErrorRequestId(value) {
+  return typeof value === 'string'
+    && value.length <= MAX_PUBLIC_ERROR_REQUEST_ID_LENGTH
+    && PUBLIC_ERROR_REQUEST_ID.exec(value)?.[0] === value
+    ? value
+    : null;
+}
+
+export function mappedErrorRequestId(error) {
+  return safePublicErrorRequestId(MAPPED_ERROR_REQUEST_IDS.get(error));
+}
+
+function permissions(value) {
+  if (!Array.isArray(value) || value.some((item) => !['memory:read', 'memory:propose'].includes(item))) {
+    throw new ValidationFailureError('permissions may contain only memory:read and memory:propose.');
+  }
+  return new Set(value);
+}
+function responseMetadata(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)
+    || !Number.isInteger(value.status) || value.status < 100 || value.status > 599
+    || !Number.isSafeInteger(value.byteLength) || value.byteLength < 0 || !('body' in value)
+    || (value.retryAfterMs !== undefined && (!Number.isSafeInteger(value.retryAfterMs) || value.retryAfterMs < 0))) {
+    throw new MalformedResponseError('Transport returned invalid response metadata.');
+  }
+  let canonicalBytes;
+  try { canonicalBytes = Buffer.byteLength(stableSerialize(value.body)); }
+  catch { throw new MalformedResponseError('Transport returned a non-serializable response body.'); }
+  if (value.byteLength < canonicalBytes) throw new MalformedResponseError('Transport response byte length is inconsistent.');
+  return value;
+}
+function mapError(response, operation) {
+  validateErrorResponse(response.body);
+  const { code } = response.body.error;
+  const requestId = safePublicErrorRequestId(response.body.request_id);
+  const options = {
+    status: response.status,
+    details: requestId === null ? { lucyCode: code } : { lucyCode: code, request_id: requestId },
+  };
+  const correlate = (error) => {
+    if (requestId !== null) MAPPED_ERROR_REQUEST_IDS.set(error, requestId);
+    return error;
+  };
+  if (response.status === 401 || code === 'unauthenticated') return correlate(new AuthenticationFailureError(undefined, options));
+  if (response.status === 403 || code === 'forbidden') return correlate(new AuthorizationFailureError(undefined, options));
+  if (code === 'insufficient_credits' || response.status === 402) return correlate(new InsufficientCreditsError(undefined, options));
+  if (code === 'billing_unavailable') return correlate(new BillingUnavailableError(undefined, options));
+  if (code === 'invalid_scope') return correlate(new InvalidScopeError(undefined, options));
+  if (code === 'version_conflict') return correlate(new VersionConflictError(undefined, options));
+  if (code === 'conflict') return correlate(new LifecycleConflictError(undefined, options));
+  if (response.status === 404 || code === 'not_found_or_not_visible') {
+    return correlate(operation === 'proposal-status'
+      ? new ProposalNotFoundError(undefined, options)
+      : new MemoryNotFoundError(undefined, options));
+  }
+  if (response.status === 429 || code === 'rate_limited') return correlate(new RateLimitError(undefined, { ...options, retryAfterMs: response.retryAfterMs ?? null }));
+  if ([502, 503, 504].includes(response.status) || code === 'service_unavailable') return correlate(new UpstreamUnavailableError(undefined, options));
+  if (response.status >= 500) return correlate(new InternalLucyError(undefined, options));
+  return correlate(new ValidationFailureError(undefined, options));
+}
+
+export class AgentMemoryClient {
+  #permissions;
+  #timeoutMs;
+  #token;
+  #transport;
+
+  constructor({ transport, token, permissions: configuredPermissions, timeoutMs = 10_000 } = {}) {
+    if (typeof transport !== 'function') throw new ValidationFailureError('transport must be a function.');
+    if (typeof token !== 'string' || token.length === 0 || /[\r\n\0]/.test(token)) throw new AuthenticationFailureError('token must be a non-empty string without line breaks or NUL bytes.');
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) throw new ValidationFailureError('timeoutMs must be an integer between 1 and 300000.');
+    this.#transport = transport;
+    this.#token = token;
+    this.#permissions = permissions(configuredPermissions);
+    this.#timeoutMs = timeoutMs;
+    Object.freeze(this);
+  }
+
+  async recall(requestJson) {
+    this.#require('memory:read');
+    const request = toRecallRequestDto(parseRequestJson(requestJson, 'recall request', 8192));
+    return this.#invoke('recall', request, validateRecallResponse);
+  }
+  async recallCanonical(requestJson) {
+    this.#require('memory:read');
+    const request = toRecallRequestDto(parseRequestJson(requestJson, 'canonical recall request', 8192));
+    return this.#invoke('canonical-recall', request, validateCanonicalRecallResponse);
+  }
+  async propose(requestJson) {
+    this.#require('memory:propose');
+    const request = toProposalRequestDto(parseRequestJson(requestJson, 'proposal request', 12288));
+    return this.#invoke('propose', request, validateProposalResponse);
+  }
+  async proposalStatus(requestJson) {
+    this.#require('memory:read');
+    const request = toProposalStatusRequestDto(parseRequestJson(requestJson, 'proposal status request', 8192));
+    return this.#invoke('proposal-status', request, validateProposalResponse);
+  }
+  #require(permission) {
+    if (!this.#permissions.has(permission)) throw new AuthorizationFailureError(`The client configuration is missing ${permission}.`, { details: { permission } });
+  }
+  async #invoke(operation, request, validate) {
+    const payload = stableSerialize(request);
+    const limit = REQUEST_LIMITS[operation];
+    if (limit && Buffer.byteLength(payload) > limit) throw new ValidationFailureError(`${operation} request exceeds ${limit} UTF-8 bytes.`);
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new TimeoutError(`Lucy request exceeded ${this.#timeoutMs}ms.`)); }, this.#timeoutMs);
+    });
+    let raw;
+    try {
+      raw = await Promise.race([
+        Promise.resolve().then(() => this.#transport(Object.freeze({ operation, payload, accessToken: this.#token, signal: controller.signal }))),
+        timeout,
+      ]);
+    } catch (error) {
+      if (error instanceof AgentMemoryError) throw error;
+      if (controller.signal.aborted || error?.name === 'TimeoutError') throw new TimeoutError(`Lucy request exceeded ${this.#timeoutMs}ms.`);
+      throw new UpstreamUnavailableError('Lucy transport failed.');
+    } finally { clearTimeout(timer); }
+    const response = responseMetadata(raw);
+    if ((operation === 'recall' || operation === 'canonical-recall') && response.byteLength > 65536) throw new MalformedResponseError('Recall response exceeds 65536 UTF-8 bytes.', { status: response.status });
+    if (response.status < 200 || response.status >= 300) throw mapError(response, operation);
+    const validated = validate(response.body, request);
+    const headerValue = response.memoryOperationId;
+    if (typeof headerValue === 'string' && /^memory-[a-f0-9]{32}$/i.test(headerValue)) {
+      return { ...validated, operation_id: headerValue };
+    }
+    return validated;
+  }
+}

package/src/client/errors.mjs

@@ -0,0 +1,101 @@
+export class AgentMemoryError extends Error {
+  constructor(message, { code = 'agent_memory_error', status = null, retryable = false, details = null } = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+    this.details = details;
+  }
+}
+export class AuthenticationFailureError extends AgentMemoryError {
+  constructor(message = 'Lucy authentication failed.', options = {}) {
+    super(message, { code: 'authentication_failure', ...options, retryable: false });
+  }
+}
+export class AuthorizationFailureError extends AgentMemoryError {
+  constructor(message = 'Lucy authorization failed.', options = {}) {
+    super(message, { code: 'authorization_failure', ...options, retryable: false });
+  }
+}
+export class InvalidScopeError extends AgentMemoryError {
+  constructor(message = 'The memory scope is invalid.', options = {}) {
+    super(message, { code: 'invalid_scope', ...options, retryable: false });
+  }
+}
+export class InvalidKeyError extends AgentMemoryError {
+  constructor(message = 'The memory key is invalid.', options = {}) {
+    super(message, { code: 'invalid_key', ...options, retryable: false });
+  }
+}
+export class InvalidKindError extends AgentMemoryError {
+  constructor(message = 'The memory kind is invalid.', options = {}) {
+    super(message, { code: 'invalid_kind', ...options, retryable: false });
+  }
+}
+export class ValidationFailureError extends AgentMemoryError {
+  constructor(message = 'The memory request is invalid.', options = {}) {
+    super(message, { code: 'validation_failure', ...options, retryable: false });
+  }
+}
+export class ProposalNotFoundError extends AgentMemoryError {
+  constructor(message = 'The proposal was not found or is not visible.', options = {}) {
+    super(message, { code: 'proposal_not_found', ...options, retryable: false });
+  }
+}
+export class MemoryNotFoundError extends AgentMemoryError {
+  constructor(message = 'The memory was not found or is not visible.', options = {}) {
+    super(message, { code: 'memory_not_found', ...options, retryable: false });
+  }
+}
+export class VersionConflictError extends AgentMemoryError {
+  constructor(message = 'The expected memory version does not match.', options = {}) {
+    super(message, { code: 'version_conflict', ...options, retryable: false });
+  }
+}
+export class LifecycleConflictError extends AgentMemoryError {
+  constructor(message = 'The memory lifecycle does not permit this operation.', options = {}) {
+    super(message, { code: 'lifecycle_conflict', ...options, retryable: false });
+  }
+}
+export class RateLimitError extends AgentMemoryError {
+  constructor(message = 'Lucy rate limited the request.', { retryAfterMs = null, ...options } = {}) {
+    super(message, { code: 'rate_limit', ...options, retryable: true });
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+export class UpstreamUnavailableError extends AgentMemoryError {
+  constructor(message = 'Lucy is temporarily unavailable.', options = {}) {
+    super(message, { code: 'upstream_unavailable', ...options, retryable: true });
+  }
+}
+export class TimeoutError extends AgentMemoryError {
+  constructor(message = 'The Lucy request timed out.', options = {}) {
+    super(message, { code: 'timeout', ...options, retryable: true });
+  }
+}
+export class MalformedResponseError extends AgentMemoryError {
+  constructor(message = 'Lucy returned a malformed response.', options = {}) {
+    super(message, { code: 'malformed_response', ...options, retryable: false });
+  }
+}
+export class ProposalContractIncompatibilityError extends MalformedResponseError {
+  constructor(message = 'Lucy returned a proposal response incompatible with the frozen AM-01 schema.', options = {}) {
+    super(message, { code: 'proposal_contract_incompatible', ...options, retryable: false });
+  }
+}
+export class InternalLucyError extends AgentMemoryError {
+  constructor(message = 'Lucy returned an internal error.', options = {}) {
+    super(message, { code: 'internal_lucy_error', ...options, retryable: false });
+  }
+}
+export class InsufficientCreditsError extends AgentMemoryError {
+  constructor(message = 'The workspace does not have enough Lucy credits for this Agent Memory operation.', options = {}) {
+    super(message, { code: 'insufficient_credits', ...options, retryable: false });
+  }
+}
+export class BillingUnavailableError extends AgentMemoryError {
+  constructor(message = 'Lucy billing is temporarily unavailable.', options = {}) {
+    super(message, { code: 'billing_unavailable', ...options, retryable: true });
+  }
+}

package/src/client/http-transport.d.ts

@@ -0,0 +1,12 @@
+import type { AgentMemoryTransport } from './index.js';
+
+export interface LucyHttpTransportOptions {
+  baseUrl: string;
+  /** Development-only opt-in for cleartext HTTP to literal loopback/localhost endpoints. */
+  allowInsecureLoopback?: boolean;
+  fetchImpl?: typeof fetch;
+  maxRetries?: number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+export function createLucyHttpTransport(options: LucyHttpTransportOptions): AgentMemoryTransport;