Architecture

AtomicMemorySDK is a layered dispatcher. Application code talks to a single class; under the hood, policy, routing, and backend calls are separate concerns that compose cleanly.

The layers

Solid arrows are the request path; dotted arrows are peer subsystems the SDK composes. Four responsibilities are kept separate on purpose:

Layer	Responsibility	Source of truth
AtomicMemorySDK	Public surface. Config validation, lifecycle, facade for all operations.	src/core/sdk.ts
ContextManager	Policy enforcement — capture gating and injection gating before any backend call.	src/core/context-manager.ts
MemoryService	Provider routing. Picks the right provider per operation, runs any op-level pipeline.	src/memory/memory-service.ts
MemoryProvider	Backend I/O. HTTP calls, mapping to/from wire format, declaring capabilities.	src/memory/provider.ts and per-provider directories

Peer subsystems — storage adapters, embedding generation, user accounts, the web SDK helpers — are composed by AtomicMemorySDK but do not sit on the request path. They run alongside.

Ingest, end to end

The gate comes first. If the user has disabled capture from the originating platform, the operation returns undefined and nothing reaches the backend — the SDK emits a captureBlocked event so instrumentation can observe the decision.

Search follows the same shape with a different gate (injection). See Consent and gating for the full search sequence.

Why layered

The separation matters for three reasons:

1. Swappable backends. MemoryService does not know the wire format. MemoryProvider does not know the user's capture preferences. Each layer can change independently, which is what makes backend-agnosticism real and not aspirational.
2. Clear policy boundary. Every gate lives in ContextManager. There is exactly one place to audit capture and injection decisions, and exactly one place to extend them.
3. Testable in isolation. Providers are tested against the MemoryProvider contract alone. Policy is tested against ContextManager with stub providers. The top-level SDK has a thin integration layer and is tested mostly for lifecycle.

Where to go next

• Provider model — the MemoryProvider interface and the extension system
• Consent and gating — what ContextManager actually enforces
• Scopes and identity — how UserAccountsManager resolves who the caller is