OME MemoryGuard

Governed, persistent memory for AI agents — built for CockroachDB × AWS.

OME MemoryGuard puts a deterministic policy gate between an agent and long-term memory. A proposed memory is classified before it can affect future actions; approved records are tenant-scoped, vector-searchable, and paired with an audit event in the same CockroachDB transaction.

What the MVP proves

• Fail-closed writes: content that looks like a secret is not stored in memory_items; the audit trail keeps only reason codes, length, and a SHA-256 fingerprint.
• Human review: suspicious or sensitive proposals stay hidden until a pending record is approved.
• Scoped retrieval: tenant, namespace, active status, expiry, and sensitivity ceiling are applied before cosine vector ranking.
• Atomic evidence: memory creation/approval and the corresponding audit event share one database transaction.
• AWS integration: Lambda + API Gateway run the FastAPI app, Bedrock Titan V2 creates 1,024- dimensional embeddings, Secrets Manager supplies the database URL, and S3 accepts encrypted audit metadata bundles.
• Safe local demo: the default repository and embedder are fully in-memory/deterministic and need no cloud credentials.

Architecture

Browser / AI agent
        |
        v
FastAPI policy gate (local or API Gateway + Lambda)
        |
        +--> Amazon Bedrock Titan V2 (embedding)
        |
        v
CockroachDB transaction
  memory_items + memory_audit_events
        |
        +--> tenant/namespace-prefixed VECTOR INDEX
        |
        +--> optional audit metadata export --> encrypted Amazon S3 object

See docs/ARCHITECTURE.md for trust boundaries and failure behavior.

Local demo (no cloud, no database)

Python 3.12 is required.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m uvicorn ome_memoryguard.api:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000. Run the safe, review, and denied scenarios; then inspect the decision, risk score, retrieval result, and audit timeline. Local mode does not read .env automatically.

Verify

.\scripts\verify.ps1

Run the full local release gate after installing gitleaks and AWS SAM CLI:

.\scripts\verify.ps1 -WithGitleaks -WithSam

The gitleaks configuration excludes local dependencies, generated artifacts, and .env, while its only source allowlist is the deliberate synthetic credential used by the fail-closed demo/test. The SAM helper builds from an isolated ASCII-only temporary copy so Windows paths containing Unicode characters do not break dependency resolution. The temporary copy is removed after the check.

Or run the checks individually:

python -m unittest discover -s tests -v
python -m compileall -q ome_memoryguard tests

To run only the SAM validation/build gate:

.\scripts\verify.ps1 -WithSam

Before a separately approved live synthetic E2E, the repository provides two fail-fast read-only guards and one bounded runner:

.\scripts\bedrock-quota-preflight.ps1 -Region us-west-2 -Profile <DEPLOY_PROFILE>
.\scripts\aws-cost-preflight.ps1 -BudgetName <USD_5_BUDGET> -Profile <DEPLOY_PROFILE>
.\scripts\live-bedrock-e2e.ps1 -ApiUrl <HTTPS_API_URL> -BudgetName <USD_5_BUDGET> -Profile <DEPLOY_PROFILE>

The live runner accepts only a short-lived synthetic Cognito ID token from the process environment, performs exactly two application actions that require embeddings, prints no token or memory content, and stops before calls when quota or cost checks fail. Preparing the runner does not authorize or perform a live invocation.

CockroachDB integration

schema.sql defines:

• memory_items with VECTOR(1024);
• a cosine vector index prefixed by (tenant_id, namespace);
• memory_audit_events for append-only application events;
• agent_checkpoints for versioned agent state.

The repository accepts postgresql://, postgres://, or cockroachdb:// URLs and normalizes them without logging the value. Set DATABASE_URL in the process environment only when intentionally connecting to a controlled cluster. Applying schema.sql changes a database and is never done by the application automatically.

Current CockroachDB documentation confirms VECTOR, <=> cosine distance, and prefix columns for vector indexes: Vector Indexes.

The project also used the CockroachDB Cloud Managed MCP Server as a separate read-only development and operations inspection path. See docs/COCKROACHDB_TOOLS.md for the exact operations, evidence, and runtime boundary.

AWS SAM

template.yaml includes a Cognito user pool/client/domain, OAuth 2.0 Authorization Code + PKCE for the browser demo, an API Gateway JWT authorizer, explicit public demo/health/auth-config routes, protected /v1/* routes, throttling, a retained encrypted/versioned S3 bucket, exact Secrets Manager access, and a foundation-model-scoped Bedrock permission. No API CORS is enabled; protected requests from the bundled UI are same-origin.

See docs/AWS_DEPLOYMENT.md for validation, parameters, deployment steps, cost/security gates, and rollback notes. No AWS deployment is performed by this repository.

API

Method	Path	Purpose
GET	/healthz	Runtime mode; never returns secrets
GET	/auth/config	Public OAuth client/domain/callback settings; never returns secrets
POST	/v1/memories/propose	Evaluate and optionally persist a proposal
POST	/v1/memories/{id}/approve	Activate a pending memory
POST	/v1/memories/search	Scoped vector retrieval with max_sensitivity
GET	/v1/audit/events	Tenant-scoped audit metadata
POST	/v1/evidence/export	Export audit metadata to configured S3

Security boundary

AWS mode derives tenant, actor, groups, and clearance from API Gateway-verified Cognito JWT claims. The required claims are sub, custom:tenant_id, and optional custom:clearance (defaults to public). Approval requires memoryguard-reviewer or memoryguard-admin; evidence export requires memoryguard-auditor or memoryguard-admin. Client-supplied identity fields remain only for local AUTH_MODE=demo compatibility and are ignored in Cognito mode.

Never commit a real .env, connection string, credential, or customer dataset. See SECURITY.md for the threat model and production gaps.

Hackathon material

• Devpost draft
• 75-second demo script
• Architecture and trust boundaries
• AWS/SAM runbook
• Local verification record
• CockroachDB tool usage and MCP proof

License: MIT.