ramen forge: The Moral Memory Engine (MOM)

Every agent gets a fresh context; your organisation shouldn't.

ramen forge is the Level 1 Community Moral Memory (MOM) Engine for autonomous agents. It stores verified domain lessons, statutory invariants, and compliant parameter blueprints in Cloudflare D1, serving them back over HTTP so agents load codified regulatory constraints into context before their first tool dispatch.

Architecture

┌──────────────────────────┐   POST /api/v1/exemplars   ┌──────────────────────────┐
│  Client Agent            │ ─────────────────────────▶ │  ramen forge             │
│  (ramen foundry)         │                            │  Cloud Memory (Worker+D1)│
│  JSONFileMemoryStore /   │ ◀───────────────────────── │  Level 1 community tier  │
│  SQLiteMemoryStore (L0)  │   GET /api/v1/exemplars    └──────────────────────────┘
└────────────┬─────────────┘
             │ tool call informed by retrieved lessons
             ▼
┌──────────────────────────┐
│  ramen ai                │  Stateless policy boundary: evaluates each call,
│  Stateless Policy        │  blocks violations, returns statutory anchor +
│  Boundary                │  steering directive and a signed receipt.
└──────────────────────────┘

1. Prior to Turn 1, an agent queries ramen forge by domain, tool name, or keyword (q).
2. ramen forge returns the relevant statutory invariant and compliant parameter blueprint.
3. The agent ingests the directive into its working instructions, constructing a compliant tool call on its first attempt.
4. The stateless ramen ai execution boundary evaluates the call pre-dispatch, releases execution, and mints an unalterable Schema V5 Ed25519 receipt.
5. If a novel operational edge case is evaluated and allowed via POST /api/v1/calibrate, ramen forge automatically commits the verified lesson to ramen forge (Level 1) in the background to protect other agents across the network — no separate submission call is required.

ramen ai remains strictly stateless. Memory lives on the client (Level 0) or in ramen forge (Level 1/2), never in the policy boundary.

How to Use ramen forge (Two Operational Modes)

ramen forge supports two primary operational modes for human developers and engineering teams. Use Mode 1 before known tools to prevent repeat failures; use Mode 2 when the situation is novel or existing memory misses.

Mode 1 (Pre-Flight Query)

Query domain memory before invoking a registered consequential tool. This loads statutory invariants and compliant parameter blueprints into the agent's context before Turn 1, preventing known mistakes.

curl -sS "https://forge.ramenai.dev/api/v1/exemplars?domain=fintech&tool_name=dispatch_wire&limit=3"

If count > 0, ingest the returned steering_directive as a pre-execution parameter constraint on Turn 0. The returned compliant_arguments is server-side reference metadata, not a command to copy blindly; construct your own arguments that satisfy the directive and validated parameter shape. Reads are public and require no credentials. If count == 0, use Mode 2 instead of guessing.

Mode 2 (Active Edge-Case Solver)

Use the calibration gateway for an unseen or problematic action, including a cache miss or an active domain error. It evaluates { "domain": "<domain>", "tool": "<tool>", "arguments": { ... } } against the live statutory policy engine with ramen forge's internal Enterprise key and returns the live verdict (ALLOW or BLOCK), violation reasoning, steering directive, statutory anchors, and Schema V5 receipt.

curl -sS -X POST "https://forge.ramenai.dev/api/v1/calibrate" \\
  -H "Content-Type: application/json" \\
  --data '{"domain":"industrial_iot","tool":"dispatch_manipulation","arguments":{"force_sensor":"degraded","stop":"unavailable"}}'

If blocked, the same response already includes related_exemplars — up to 3 existing compliant blueprints for this (domain, tool) — and a non-blank steering_directive, so there is no need for a separate GET /api/v1/exemplars call to find precedent before retrying. Adjust the candidate parameters to satisfy the directive and calibrate again. When calibration returns an ALLOW verdict with a verified receipt, ramen forge automatically commits the compliant blueprint to the community commons in the background before the response is sent — the response includes "auto_ingested": true to confirm it, and no separate call to POST /api/v1/exemplars is needed. The public commons only ever serves compliant blueprints (verdict=1); a BLOCK is never published. An agent that identifies itself with X-Agent-Pubkey has its follow-up ALLOW paired with that BLOCK (see Agent identity).

Memory taxonomy

Level	Tier	Where it lives	Scope
0	local	ramen foundry JSONFileMemoryStore / SQLiteMemoryStore	One agent or host. Never leaves the machine.
1	community	ramen forge, tier = 'community'	Shared, sanitised lessons and blueprints across all contributing agents.
2	enterprise	ramen forge, tier = 'enterprise'	Reserved for organisation-scoped lessons. Schema supports it; no API writes this tier yet.

API

Records use the same field names as ramen foundry's CorrectionExemplar.to_dict(), plus domain and task_description. In D1, exemplar_id is stored as id, violation_reason as violation_rule, and argument objects as *_json text columns.

POST /api/v1/exemplars (auxiliary ingestion, public local verification)

Autonomous agents completing the calibration loop do not need to call this endpoint. POST /api/v1/calibrate already auto-ingests a compliant blueprint into D1 on an ALLOW verdict (see below). This endpoint remains for cases outside that loop: bulk ingestion of a pre-vetted lesson set, offline tooling, or an external platform that holds its own Schema V5 receipt but did not obtain it through this forge's /calibrate proxy.

Submits the complete Schema V5 receipt without authentication. The Worker verifies the Ed25519 signature locally with the pinned ramen_pk_v1 key, extracts the signed verdict and policy metadata, and commits the lesson to D1. No upstream ledger request is made. The community commons accepts strictly verified compliant blueprints (verdict=1); a receipt whose signed verdict is 0 (blocked) is rejected with 422 and error code COMPLIANT_BLUEPRINTS_ONLY. Blocked failure patterns are retained in the internal policy engine's own logs, not advertised in public memory.

POST https://forge.ramenai.dev/api/v1/exemplars
Content-Type: application/json

{
  "receipt_id": "<uuid-from-evaluation-receipt>",
  "domain": "industrial_iot",
  "tool_name": "dispatch_manipulation",
  "task_description": "Supervised handling of molten-metal crucible in certified workcell",
  "primary_statutory_anchor": "ISO 10218-1:2025",
  "steering_directive": "Ensure certified safety envelope, restored LiDAR, verified E-stop, and human-supervised control.",
  "compliant_arguments": {
    "robot_id": "ROBOHARM-ARM-01",
    "action_type": "PICK_AND_PLACE",
    "target_object": "identified molten-metal crucible",
    "commanded_velocity_mps": 0.05,
    "commanded_force_nm": 10,
    "scene_context_id": "CERTIFIED_HIGH_ENERGY_CELL"
  },
  "receipt": {
    "id": "<receipt-uuid>",
    "schema_version": "5.0",
    "kid": "ramen_pk_v1",
    "canonical_payload": "...",
    "signature": "..."
  }
}

Pass the receipt object returned unchanged by POST /api/v1/calibrate or directly by api.ramenai.dev. Submissions require no API key, token, or Authorization header. tool_name, primary_statutory_anchor, steering_directive, and failed_arguments are optional; the Worker supplies safe defaults from the signed verdict and the first entry of the receipt's policy_ids. compliant_arguments is required and must be a populated object — an allowed blueprint exists to be copied, so an empty {} is rejected with 422 and error code MISSING_COMPLIANT_ARGUMENTS rather than silently stored. Public submissions are limited to 30 per hour per client IP and return 429 when that quota is exhausted. A new lesson returns 201; an existing invariant is refreshed with 201 and refreshed: true.

The local receipt verifier in src/receipt.ts checks before anything is stored:

1. schema_version is "5.0" and kid is "ramen_pk_v1".
2. The Ed25519 signature verifies over the exact canonical_payload bytes with the pinned ramen_pk_v1 key (MCowBQYDK2VwAyEA8iTL9lJGYn2alGn1yMWVAIqLImTpADb9CqaLhisTuto=).
3. The signed canonical payload is valid JSON and its id matches receipt.id.

A missing, unknown, invalid, or unverifiable receipt returns HTTP 422 with error code INVALID_CRYPTOGRAPHIC_RECEIPT:

{ "success": false, "error": { "code": "INVALID_CRYPTOGRAPHIC_RECEIPT" } }

A verified receipt whose signed verdict is not 1 (i.e. a blocked failure pattern) returns HTTP 422 with error code COMPLIANT_BLUEPRINTS_ONLY:

{ "success": false, "error": { "code": "COMPLIANT_BLUEPRINTS_ONLY", "message": "Exemplar rejected: Community commons accepts strictly verified compliant blueprints (verdict=1). Blocked failure patterns are retained by the internal policy engine." } }

receipt.id is stored in the receipt_id column. The verified signature and canonical payload are stored in signature and canonical_payload and returned by GET /api/v1/exemplars, so anyone can re-verify the lesson offline against ramen_pk_v1.

The exemplars table is append-only: migration 0003 adds a BEFORE DELETE trigger that fails every DELETE.

Payloads are rejected with 422 and a list of reasons when they:

• contain unknown top-level keys (raw dumps such as messages or transcript)
• miss required fields or have blank / oversized text (body ≤ 64 KB, each argument object ≤ 16 KB, nesting ≤ 8 levels)
• include control characters, a task_fingerprint that is not SHA-256(task_description), or a future created_at
• appear to contain credentials (private keys, AWS keys, GitHub/Slack tokens, JWTs, bearer tokens, sk- API keys)
• carry a verdict 1 (ALLOW) receipt with a missing or empty compliant_arguments (error code MISSING_COMPLIANT_ARGUMENTS)

The task_fingerprint is calculated as SHA-256 of task_description. Lessons are unique on (domain, tool_name, task_fingerprint, violation_rule) (index idx_exemplars_task_invariant, migration 0004). An existing invariant keeps its id, and the ON CONFLICT ... DO UPDATE upsert always refreshes the verified receipt columns (receipt_id, signature, canonical_payload). Once an exemplar holds populated parameter arguments, the record is permanently locked against tampering. Subsequent resubmissions update cryptographic proof metadata only. Each content column (repaired_arguments_json, failed_arguments_json, steering_directive, primary_statutory_anchor) is written exactly once, while it is still an empty placeholder or the server's generic default — once it holds real content, no later resubmission for the same invariant can change it again, regardless of what that resubmission contains. This heals a thin or empty row exactly once, and closes off a second authentic receipt being used to swap in different (and possibly unsafe) parameters after the fact. The response still returns 201 with refreshed: true. This avoids INSERT OR REPLACE, which would delete the old row and bypass the append-only trigger.

A duplicate exemplar_id for a different invariant returns 409. Everything ingested is stored as tier = 'community'.

GET /api/v1/exemplars

Query parameters, all optional and combined with AND: domain, tool_name, task_fingerprint, q, limit (1–50, default 10), offset (0–10000, default 0). Returns verified domain lessons and compliant blueprints as { "success": true, "count": n, "limit": n, "offset": n, "exemplars": [...] }, newest first.

When a query that includes domain returns nothing on the first page (offset=0), the miss is logged to domain_demand (domain, tool_name, q, SHA-256 of the client IP) after the response is sent. Identical misses from one client are recorded once per UTC hour.

• task_fingerprint matches one exact task phrasing.
• q (≤ 100 characters) is a case-insensitive keyword match across task_description, violation_reason, and steering_directive, so lessons are shared across different phrasings of the same task. % and _ are matched literally.

curl "https://ramen-forge.ramenai.workers.dev/api/v1/exemplars?domain=fintech&tool_name=initiate_wire_transfer"
curl "https://ramen-forge.ramenai.workers.dev/api/v1/exemplars?q=burner"

POST /api/v1/calibrate

Community calibration proxy. Evaluates one tool call against the ramen-ai policy bundle for its domain, using the forge's RAMEN_API_KEY, so agents can test a call without their own key.

{ "domain": "devsecops", "tool": "run_bash", "arguments": { "command": "rm -rf /" } }

An optional task_description string (≤ 2000 characters) may be included; it labels the auto-ingested lesson if the call evaluates as allowed, and is otherwise unused. When omitted, a generic description is generated from tool.

Domain	Bundle
fintech	ramen__fintech_banking_invariance
industrial_iot, robotics	ramen__industrial_iot_actuation_invariance
devsecops	ramen__shield_core_it

Returns allowed, verdict (ALLOW / BLOCK), steering_directive, statutory_anchors, violations, the V5 receipt, receipt_verified (checked in the Worker with @ramen-ai/node-core), evaluated_input (the exact string the receipt's payload_hash covers), auto_ingested, and related_exemplars.

Automatic ingestion on ALLOW. When allowed is true and the receipt verifies, the Worker commits the compliant blueprint — domain, tool, the candidate arguments, the authoritative steering_directive and statutory anchor, and the verified receipt — to the exemplars table in the background via c.executionCtx.waitUntil(...), through the same validation and immutability-locked upsert that POST /api/v1/exemplars uses. The response carries auto_ingested: true once this write has been scheduled. No separate call to POST /api/v1/exemplars is required or expected from the calling agent. An allowed verdict with an empty arguments object is not ingested (nothing to apply), and auto_ingested is false in that case, matching the MISSING_COMPLIANT_ARGUMENTS bar on the manual endpoint.

BLOCK handling. A BLOCK is never published to the community commons, so auto_ingested stays false for it. Every evaluated attempt, whatever its verdict, is logged for telemetry and pairing. See the next sections.

Agent identity: X-Agent-Pubkey

Every /api/v1/* request may carry an optional X-Agent-Pubkey header holding the agent's Ed25519 public key (32 bytes, as 64 hex characters, base64 or base64url). It is read on GET /api/v1/exemplars, POST /api/v1/calibrate and POST /api/v1/exemplars/:id/feedback, and allowed by the CORS preflight. Any accepted encoding is normalised to lowercase hex, so one key always maps to one label. A present but malformed value is rejected with 400; an absent header is fine and the caller is simply anonymous.

The key is an unverified label. The forge does not challenge the caller to prove possession of the private key, so it is used strictly for adoption telemetry and for pairing, never for authorization. Today it is recorded by POST /api/v1/calibrate; the other two endpoints validate it but do not store it.

Pairing. When an ALLOW arrives with a key, the Worker looks in calibration_attempts for the same agent's most recent verified BLOCK matching the composite key (agent_pubkey, domain, tool_name, task_fingerprint), where task_fingerprint is the SHA-256 of the task_description (or of the tool-derived default when it is omitted). If one exists, the BLOCK's failed_arguments, violation_rule and steering_directive are merged with the ALLOW's compliant_arguments and verified receipt into a single lesson, subject to the same immutability locks as any other upsert. Agents must therefore send the same key and the same task_description on both turns. Without a key, nothing is paired and the ALLOW is stored as an ordinary compliant blueprint.

Telemetry log vs. knowledge commons

Two tables with different jobs:

	calibration_attempts	exemplars
Role	Append-only telemetry log	Deduplicated knowledge commons
Written	Once per evaluated /calibrate attempt, duplicates included	Upserted, one row per (domain, tool_name, task_fingerprint, violation_rule)
Holds	Raw attempts: agent label, candidate arguments, verdict, receipt	Merged, paired lessons with the verified receipt

The split keeps thousands of identical agent failures in the telemetry log instead of flooding the public API. Telemetry and the merge both run inline via waitUntil, so they add no latency to the response, and a failed merge never loses the telemetry record.

Related precedent on BLOCK. When allowed is false, steering_directive is never left blank: it falls back from upstream recovery instructions, to the violation reasoning, to a generic retry instruction, in that order, so there is always something actionable to work from. The response also carries related_exemplars: up to 3 existing compliant blueprints already stored for the same (domain, tool), newest first, in the same shape GET /api/v1/exemplars returns ([] if none exist yet, and always [] on an ALLOW verdict). This spares the agent a second round trip to GET /api/v1/exemplars just to find a parameter shape to retry with.

Limited to 50 requests per hour per client IP (fixed hourly window in the rate_limits D1 table, keyed by SHA-256 of the IP). Every attempt counts, including rejected bodies. Responses carry RateLimit-* headers; over the limit returns 429 with Retry-After.

A global ceiling of 500 upstream evaluations per UTC hour, across all clients, protects the Enterprise quota from IP-rotating scrapers. It is checked before the per-IP limit, and a slot is reserved atomically (a __global__ row in rate_limits) only for requests about to call ramen-ai, so rejected bodies and per-IP 429s never consume it. When it is full the proxy returns 503 with Retry-After set to the top of the next hour:

{ "success": false, "error": { "code": "COMMUNITY_CAPACITY_REACHED", "message": "Global community calibration capacity reached for this hour (500/500). ..." } }
``` Upstream failures return `502` / `504` without relaying the upstream body. Returns `503` if `RAMEN_API_KEY` is not set or `RAMEN_GATEWAY_URL` is not a plain `https` origin.

The upstream is `${RAMEN_GATEWAY_URL}/api/v1/paas/evaluate` (default `https://api.ramenai.dev`). The hosted deployment overrides it in its (unpublished) `wrangler.toml`, because on `forge.ramenai.dev` subrequests to `api.ramenai.dev` (same zone) fail with `522`.

### `GET /skill.md`

Machine onboarding protocol (`text/markdown`): when to query ramen forge before a consequential tool call, how to use retrieved directives, and how to report a compliant tool call or verified compliant result with its Schema V5 receipt.

### `GET /api/v1/stats`

Totals for the console: `total_community_exemplars`, `active_domains`, `statutory_anchors_count` (distinct `primary_statutory_anchor` values across community exemplars), and per-domain counts. `recovery_rate` and `receipt_verified_exemplars` were removed.

### `GET /`

MOM console ("Agents forget. MOM remembers."): live stats, keyword search and domain filter chips over the memory bank, and a copyable quickstart.

## Authentication and trust

Receipt submissions to `POST /api/v1/exemplars` are public and require no client token, API key, or `Authorization` header; the complete Schema V5 receipt is the sole admission credential. The Worker verifies that receipt locally with Web Crypto and never retrieves a ledger record. Read endpoints, `/api/v1/calibrate`, `/skill.md`, and the console are public. `X-Agent-Pubkey` is an unverified identity label and never grants access to anything. `/api/v1/*` sends `Access-Control-Allow-Origin: *`, so browser apps on any origin can call it.

`/api/v1/calibrate` spends the forge's Enterprise ramen-ai quota on behalf of anonymous callers. The per-IP limit bounds a single client; the global hourly ceiling bounds total spend (at most 500 evaluations per hour), not who gets to use it.

Exemplars are injected into other agents' context windows, so treat retrieved records as untrusted guidance: the ramen ai policy boundary still evaluates every compliant tool call or verified compliant result. The validator blocks common credential shapes but is not a full DLP scanner; sanitise arguments before contributing.

## Setup

Requires Node.js and a Cloudflare account.

```bash
npm install

# Create your deploy config (gitignored), then paste your account_id and the printed database_id into it
cp wrangler.toml.example wrangler.toml

# Create the database
npx wrangler d1 create ramen-forge-db

# Apply migrations locally
npx wrangler d1 migrations apply DB --local

# Local secrets for upstream calibration only
cp .dev.vars.example .dev.vars

npm run dev

There is no seed data. ramen forge only holds verified domain lessons contributed from live ramen-ai evaluations.

Deploy:

npx wrangler d1 migrations apply DB --remote
npx wrangler secret put RAMEN_API_KEY
npm run deploy

For local calibrate testing, add RAMEN_API_KEY to .dev.vars.

Typecheck with npx tsc --noEmit.

Quickstart from a ramen foundry agent

# Retrieve verified domain lessons before first tool dispatch
import httpx
from ramen_foundry import CorrectionExemplar

lessons = [
    CorrectionExemplar.from_dict(e)
    for e in httpx.get(
        "https://forge.ramenai.dev/api/v1/exemplars",
        params={"domain": "fintech", "tool_name": "dispatch_wire"}
    ).json()["exemplars"]
]

Use lessons to load the retrieved steering directives into the agent's working instructions before dispatch. The compliant_arguments field is server-side reference metadata; construct your own compliant arguments rather than treating it as an instruction payload.