Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
103 lines (84 loc) · 5.36 KB

ARCHITECTURE.md

File metadata and controls

103 lines (84 loc) · 5.36 KB
Raw

Architecture and trust boundaries

OME MemoryGuard architecture

The rendered diagram is optimized for a 3:2 Devpost gallery image. Its editable Mermaid source is available in assets/architecture.mmd.

Runtime topology

flowchart LR
    A["AI agent or browser"] -->|"Cognito JWT"| B["API Gateway HTTP API"]
    B -->|"JWT authorizer"| C["AWS Lambda<br/>FastAPI + Mangum"]
    C --> D["Deterministic policy gate"]
    D -->|"allowed or review"| E["Amazon Bedrock<br/>Titan Embeddings V2"]
    E --> F["CockroachDB Cloud<br/>memory + audit transaction<br/>VECTOR(1024)"]
    D -->|"denied metadata only"| F
    C -->|"audit metadata export"| G["Amazon S3<br/>AES-256 + checksum"]
    H["AWS Secrets Manager"] -->|"database URL at cold start"| C

    subgraph Local["Local deterministic demo"]
      I["InMemoryRepository"]
      J["Deterministic embeddings"]
    end
    D -.->|"local mode"| J
    J --> I
Loading

Local mode replaces CockroachDB with InMemoryRepository and Bedrock with reproducible deterministic vectors. The health endpoint reports which mode is active without returning configuration values. The Lambda and Bedrock inference Regions are configured independently: the runtime calls the exact approved BEDROCK_REGION, while CockroachDB and the rest of the dev stack remain in Frankfurt.

Write path

  1. The client submits content, provenance, purpose, tenant, namespace, sensitivity, and optional expiry.
  2. MemoryPolicy rejects expired/naive timestamps, likely secrets, oversized content, and empty content; suspicious or sensitive content can be held for review.
  3. A denied proposal never enters memory_items. The audit event stores a content fingerprint and policy metadata, not raw content.
  4. Active/pending content is embedded.
  5. CockroachRepository.save_with_event() inserts the memory and audit event under one engine.begin() transaction.
  6. Approval uses a conditional UPDATE ... WHERE status = 'pending_review' and appends its event in the same transaction.

Retrieval path

The SQL query requires exact tenant and namespace values, status = 'active', a non-null embedding, valid expiry, and a caller-provided sensitivity ceiling before ordering by cosine distance (<=>). The vector index uses (tenant_id, namespace) as prefix columns, so both must be constrained for the index to be eligible.

The local repository applies the same filters and ranks by dot product over normalized vectors. Deterministic local vectors are for reproducibility, not semantic quality.

Evidence export

POST /v1/evidence/export serializes tenant-scoped audit events without memory content. The S3 key uses a truncated SHA-256 tenant partition; the object uses S3 server-side encryption and a SHA-256 checksum. S3 write and the subsequent evidence_exported database event cannot be one distributed transaction. If the database event fails after S3 succeeds, reconciliation is required.

Trust boundaries

  • API Gateway validates Cognito issuer/audience/signature before protected /v1/* routes reach the application. The app fails closed if the verified claims are absent in AUTH_MODE=cognito.
  • The browser demo uses Cognito Authorization Code + PKCE. It receives only public OAuth settings from /auth/config, keeps its short-lived ID token in sessionStorage, and sends it only to same-origin /v1/* routes.
  • Tenant and actor come from custom:tenant_id and sub; clearance is clamped to the verified claim. Approval/export require dedicated Cognito groups.
  • The policy engine is before persistent memory writes, not after retrieval.
  • The application never logs a database URL and fails closed on malformed Secrets Manager values.
  • IAM in template.yaml is limited to one secret, one S3 object prefix, and one Bedrock foundation model ARN.
  • No CORS configuration is enabled; the bundled UI is same-origin.
  • The S3 bucket is private, encrypted, versioned, ownership-enforced, and retained on stack deletion.

Known MVP limitations

  • Cognito JWT authentication, PKCE browser sign-in, and coarse group authorization are present, but lifecycle automation, account recovery policy, access-token claim customization, and fine-grained scopes are not.
  • Policy pattern matching is a guardrail, not full DLP, malware scanning, or prompt-injection proof.
  • There is no revoke endpoint, retention worker, checkpoint API, rate-limiter in local mode, or audit signature chain.
  • schema.sql and the AWS stack are not applied automatically by the source tree. They were applied only to the separately approved, synthetic ome-memoryguard-dev environment; production remains undeployed.
  • Vector-index feature availability and Bedrock model availability must be verified in the chosen CockroachDB version and AWS Region.

Failure behavior

  • Policy denial: no raw memory row; metadata-only denial event.
  • Bedrock failure: fail before persistence; no active unsearchable record.
  • Database transaction failure: memory and paired event roll back together.
  • S3 failure: export returns an error and no evidence_exported event is appended.
  • Malformed secret: cold start fails with a neutral message that excludes the secret value.
  • Unknown embedding provider: service construction fails with a neutral configuration error; local deterministic vectors are never selected for an unrecognized value.