Memory Core API

@nuzo/memory-core is the library-level integration package. Most users should install @nuzo/memory and use the CLI, MCP server, or host plugins instead.

This page freezes the root entrypoint surface for the 0.9.0 contract pass. Symbols listed here remain exported from @nuzo/memory-core until a documented SemVer-compatible replacement or a pre-1.0.0 breaking cleanup.

Stability Classes

Class	Meaning
Stable public	Intended for ordinary library integrations. Changes require SemVer treatment.
Advanced public	Supported, but for host/runtime/storage integrations that accept lower-level ownership.
Experimental public	Supported as opt-in pre-1.0.0 surface. Compatibility can still tighten before 1.0.0.

Nuzo does not currently mark any root export as deprecated. If a symbol becomes deprecated before 1.0.0, this page and package README must name the migration path.

The historical wildcard root export exposed the internal invariant helper. The 0.9.0 contract pass removes it from the root API before the stable 1.0.0 commitment. Library callers should throw or handle NuzoMemoryError directly instead of depending on internal assertion helpers.

Stable Public Runtime Exports

Symbol	Purpose
NuzoMemoryError	Structured domain error with stable code, message, and optional details.
createMemoryService	Construct the host-neutral memory service from explicit dependencies.
DefaultPolicyEngine	Default validation, secret scanning, and scope authorization policy.
RegexSecretScanner	Built-in local secret scanner used by the default policy.
SystemClock	Default wall-clock implementation.
RandomIdGenerator	Default memory, relation, and event ID generator.
memoryConfidenceStates	Stable human-readable confidence state values.
memoryChallengeOutcomes	Stable challenge/review outcome values.
memoryKinds	Stable memory kind values.
memoryProvenanceKinds	Stable structured provenance kind values.
memoryRelationTypes	Stable explicit memory relation values.
memoryEventTypes	Stable audit event type values.
memoryLimits	Public validation limits used across CLI and MCP contracts.
memoryScopePattern	Scope validation pattern.
memoryTagPattern	Tag validation pattern.
projectScopeFromPath	Stable project-scope derivation helper.
getDefaultStorePath	Default user-level SQLite store path helper.
resolveAutomaticScope	Resolves project:auto for library callers.
resolveNuzoRuntimeConfig	Shared runtime resolver for CLI, MCP, and host integrations.
formatMemoryExportMarkdown	Markdown rendering for versioned memory exports.
escapeUntrustedControlCharacters	Escape terminal controls, bidirectional formatting, and row/column separators in a value that already carries its own escaping, such as compact JSON or a filesystem path.
renderUntrustedInlineText	Render untrusted stored text for one line of human-readable output, without control characters, row breaks, or forged columns.
renderUntrustedMarkdownBlock	Render untrusted stored text as an inert fenced Markdown block.
stringifyUntrustedJson	Serialize lossless JSON while escaping terminal-active and direction-changing code points that native JSON.stringify leaves raw.

Integrations that print memory content, tags, sources, relation reasons, or audit actors to a terminal or a Markdown document should render those values through these helpers. They change presentation only; stored values and parsed JSON responses keep the original content. See Memory Trust Boundary.

Stable Public Type Exports

Symbol	Purpose
MemoryService	Main service interface.
MemoryServiceDependencies	Explicit dependency bag for createMemoryService.
MemoryRecord	Canonical memory record.
MemoryEvent	Canonical audit event.
MemoryConfidenceState	Human-readable confidence state union.
MemoryChallengeOutcome	Challenge/review outcome union.
MemoryRelationRecord	Canonical explicit relation between two memories.
MemoryRelationType	Explicit relation type union.
MemoryKind	Memory kind union.
MemoryProvenance	Structured provenance metadata.
MemoryProvenanceKind	Structured provenance kind union.
MemoryScope	Scope string type.
MemoryEventType	Audit event type union.
RememberMemoryInput	Explicit memory write input.
RecallMemoriesInput	Recall input.
RecallMemoriesResponse	Detailed recall response.
RecallMemoryResult	Individual recall result.
RecallDiagnostics	Retrieval-mode diagnostics.
ListMemoriesInput	List/filter input.
InspectMemoryInput	Detail inspection input.
MemoryInspection	Detail inspection result.
ChallengeMemoryInput	Challenge/review input.
ChallengeMemoryResult	Challenge/review result.
RelateMemoriesInput	Explicit memory relation write input.
ListMemoryRelationsBatchInput	Bounded authorized relation hydration input for up to 200 primary memories.
ListMemoryRelationsInput	Relation list input.
ReviewMemoryRelationsInput	Explicit-scope, lifecycle-filtered input for the bounded read-only relation governance report.
RelationGovernanceReview	Content-free read-only governance report and bound/write diagnostics.
RelationGovernanceCandidate	One authorized candidate pair with IDs, revisions, scopes, lifecycle, reason codes, and explicit relation state.
RelationGovernanceExistingRelation	Existing relation ID, type, and direction for a candidate pair.
RelationGovernanceLifecycleState	Content-free active, archived, expired, or review-due state.
RelationGovernanceReasonCode	Stable content-free evidence-code union for relation review.
ForgetMemoryRelationInput	Relation removal input.
MemoryHistoryInput	Per-memory audit history pagination input.
UpdateMemoryInput	Update input.
ForgetMemoryInput	Single-memory archive/delete input.
ForgetMemoriesInput	Bulk archive/delete input.
ForgetMemoriesResult	Bulk archive/delete result.
AuditEventFilter	Audit query filter.
ExportMemoriesInput	Export input.
ImportMemoriesInput	Import input.
ImportMemoriesResult	Import result.
MemoryExportDocument	Versioned JSON export document.
MemoryExportItem	Exported memory item.
MemoryExportRelationItem	Exported relation item.
SuggestCaptureInput	Capture suggestion input.
ConfirmCaptureDecision	Confirmed capture decision union.
ConfirmCaptureInput	Confirmed capture input.
ConfirmCaptureResult	Confirmed capture result.
CaptureSuggestionDraft	Normalized capture draft.
CaptureSuggestionResult	Capture suggestion result.
CaptureRelationshipMode	Capture relationship mode union.
CaptureRelationship	Capture relationship classification.
CaptureRelationshipCandidate	Bounded relationship candidate.
CaptureRelationshipEvidence	Bounded relationship evidence.
RetrievalMode	Recall retrieval mode union.
SemanticFallbackMode	Semantic fallback mode union.
NuzoAuthorizationMode	Effective administrator or restricted runtime mode.
NuzoAuthorizationConfig	Trusted user authorization config shape.
NuzoConfig	Versioned runtime config shape.
NuzoRuntimeConfig	Effective runtime config.
NuzoRuntimeConfigOptions	Runtime resolver options.
NuzoRuntimeConfigProvenance	Non-sensitive source metadata for effective runtime fields.
NuzoRuntimeAdjustment	Safe runtime adjustments caused by authorization constraints.

MemoryRecord, RememberMemoryInput, UpdateMemoryInput, CaptureSuggestionDraft, and MemoryExportItem include nullable review lifecycle metadata: reviewAfter / review_after and expiresAt / expires_at. These fields are optional for inputs and export imports, and null means no review or expiry timestamp is set.

MemoryService.relationsBatch(...) returns one map entry per unique requested memory ID. It preserves the same endpoint authorization, reverse-relation semantics, newest-first ordering, and visible per-memory limit as MemoryService.relations(...). The batch is limited to 200 primary memories; unauthorized primary memories still fail closed, while relations with an unauthorized endpoint are omitted before the visible limit is applied.

MemoryService.reviewRelations(...) reuses the bounded capture classifier and authorized storage ports to inspect at most 200 primary memories and return at most 200 content-free candidate pairs. It never writes memory, relation, lifecycle, or audit state. See Relation Governance Review.

Advanced Public Exports

These exports are public for integrations that own storage, policy, dependency injection, or runtime packaging.

Symbol	Class	Purpose
SQLiteMemoryDatabase	Advanced public	SQLite adapter implementing store, search, audit, and transactions.
SQLiteMemoryDatabaseOptions	Advanced public	SQLite adapter options.
inspectSQLiteMemoryStore	Advanced public	Inspect a SQLite memory store for schema, integrity, count, and FTS consistency diagnostics.
planSQLiteFtsRepair	Advanced public	Produce a content-free, non-mutating FTS drift and repairability plan.
repairSQLiteFtsIndex	Advanced public	Create and validate a recovery backup, then transactionally rebuild derived FTS rows after explicit confirmation.
planSQLiteProjectScopeRehome	Advanced public	Produce a content-free, non-mutating plan and collision count for two explicit project scopes.
rehomeSQLiteProjectScope	Advanced public	Lock, back up, validate, and atomically rehome canonical project memory and FTS scope after confirmation.
inspectRuntimeFileSafety	Advanced public	Inspect known Nuzo runtime paths for unsafe modes, ownership, symlinks, stale artifacts, and unexpected files without changing them.
InspectRuntimeFileSafetyInput	Advanced public	Store, project, and home roots selected for file-safety inspection.
RuntimeFileSafetyFinding	Advanced public	Content-free unsafe-path finding.
RuntimeFileSafetyReport	Advanced public	Content-free file-safety summary shared by CLI and MCP diagnostics.
backupSQLiteMemoryStore	Advanced public	Create a WAL-safe SQLite online backup and validate the resulting snapshot.
restoreSQLiteMemoryStore	Advanced public	Validate and restore a WAL-safe SQLite snapshot into a target store path.
SQLiteIntegrityReport	Advanced public	Content-free SQLite store integrity report.
SQLiteFtsRepairPlan	Advanced public	FTS drift plan with canonical and FTS precondition diagnostics.
SQLiteFtsRepairResult	Advanced public	FTS repair result with before, backup, and after integrity reports.
SQLiteProjectScopeRehomePlan	Advanced public	Versioned rehome plan, hash, counts, collision state, and integrity evidence.
SQLiteProjectScopeRehomeResult	Advanced public	Applied rehome result with preserved-revision, backup, audit-event, and post-integrity evidence.
SQLiteBackupResult	Advanced public	SQLite backup result with snapshot integrity diagnostics.
SQLiteRestoreResult	Advanced public	SQLite restore result with target integrity diagnostics.
schemaVersion	Advanced public	Current SQLite schema version.
migrate	Advanced public	Apply SQLite migrations to a database handle.
MemoryStore	Advanced public	Storage port.
CaptureCandidateLookupInput	Advanced public	Optional storage-prefilter request for deterministic duplicate lookup and bounded relationship candidates; excludeMemoryId supports self-exclusion when reviewing stored memory.
CaptureCandidateLookupResult	Advanced public	Duplicate, bounded candidates, and explicit search-completeness result returned by a storage prefilter.
SearchIndex	Advanced public	Search port.
AuditLog	Advanced public	Audit-log port.
AuditLogQuery	Advanced public	Storage-facing audit filter for bounded page traversal. Results are newest-first and its cursor is exclusive.
AuditLogCursor	Advanced public	Structured event timestamp and ID cursor used by AuditLogQuery.
TransactionManager	Advanced public	Transaction port.
Clock	Advanced public	Clock port.
IdGenerator	Advanced public	ID-generator port.
SecretScanner	Advanced public	Secret-scanner port.
SecretScanResult	Advanced public	Secret-scan result.
SecretFinding	Advanced public	Secret finding.
PolicyEngine	Advanced public	Policy port.
RelationEndpointReference	Advanced public	Stable ID and event-time scope used to authorize relation audit metadata after an endpoint is deleted.
DefaultPolicyEngineOptions	Advanced public	Default policy options.
EmbeddingProvider	Experimental public	Optional embedding provider port.
EmbeddingProviderDescriptor	Experimental public	Embedding provider identity/fingerprint input.
semanticIndexPathFor	Experimental public	Derived semantic sidecar path helper.
embeddingProviderFingerprint	Experimental public	Provider fingerprint helper.
rebuildSemanticIndex	Experimental public	Rebuild the derived semantic sidecar.
clearSemanticIndex	Experimental public	Remove the derived semantic sidecar.
inspectSemanticIndex	Experimental public	Inspect semantic index state without recall.
createSemanticSearch	Experimental public	Create semantic search against a sidecar.
createHybridSearchIndex	Experimental public	Combine FTS and semantic search.
SemanticIndexState	Experimental public	Semantic index state union.
SemanticIndexStatus	Experimental public	Semantic index status.
RebuildSemanticIndexInput	Experimental public	Rebuild input.
RebuildSemanticIndexResult	Experimental public	Rebuild result.
SemanticSearchOptions	Experimental public	Semantic search options.
SemanticSearch	Experimental public	Semantic search interface.
HybridSearchIndexOptions	Experimental public	Hybrid search options.
localTransformersModel	Experimental public	Pinned local Transformers model metadata.
localTransformersModelFiles	Experimental public	Pinned model file manifest.
defaultLocalTransformersModelPath	Experimental public	Default local model path helper.
localTransformersProviderDescriptor	Experimental public	Local provider descriptor.
inspectLocalTransformersModel	Experimental public	Inspect local model state.
provisionLocalTransformersModel	Experimental public	Explicit model provisioning helper.
createLocalTransformersEmbeddingProvider	Experimental public	Create the optional local embedding provider.
LocalTransformersModelManifest	Experimental public	Local model manifest type.
LocalTransformersModelStatus	Experimental public	Local model status type.
ProvisionLocalTransformersModelInput	Experimental public	Model provisioning input.
ProvisionLocalTransformersModelResult	Experimental public	Model provisioning result.
LocalTransformersProviderOptions	Experimental public	Local provider options.

AuditLog.query implementations must order results by createdAt DESC, id DESC and treat AuditLogQuery.cursor as an exclusive upper bound. The core service uses this contract to continue past unauthorized audit events without returning short pages.

Custom policy adapters may implement PolicyEngine.assertCanListRelationEndpointReference to authorize the stable ID and event-time scope retained after a relation endpoint is deleted. When the method is absent, relation-linked audit events with a missing endpoint are omitted. DefaultPolicyEngine enables this path only when its standard relation-read authorization method has not been overridden.

Error Contract

Library callers should catch NuzoMemoryError for expected domain, validation, policy, authorization, storage-version, and semantic-state failures. Its code is the machine-readable compatibility field. message is human-readable and can be clarified compatibly. details may be absent, especially where including details could reveal unauthorized memory metadata.

Unknown thrown errors are not public domain failures and should be treated as internal failures by CLI, MCP, or host wrappers.

Minimal Library Integration

import {
  createMemoryService,
  DefaultPolicyEngine,
  RandomIdGenerator,
  RegexSecretScanner,
  SQLiteMemoryDatabase,
  SystemClock,
} from "@nuzo/memory-core";

const database = new SQLiteMemoryDatabase({
  path: "/absolute/path/to/memories.sqlite",
});

try {
  const service = createMemoryService({
    store: database,
    searchIndex: database,
    auditLog: database,
    transactions: database,
    clock: new SystemClock(),
    ids: new RandomIdGenerator(),
    policy: new DefaultPolicyEngine(new RegexSecretScanner(), {
      allowedScopes: ["project:nuzo"],
    }),
  });

  await service.remember({
    content: "Run docs validation before release.",
    kind: "instruction",
    scope: "project:nuzo",
    tags: ["release", "docs"],
    source: "example:library",
  });
} finally {
  database.close();
}

The caller owns database lifetime. Close the SQLite adapter when the integration is done. Optional semantic providers can also expose dispose; host runtimes should await disposal during shutdown.

Compatibility Gate

The root entrypoint must remain explicit. Do not add export * to packages/core/src/index.ts.

Changing the root API requires updating this page and the contract gate in tools/core-api-contract.test.mjs in the same PR.