Limits and behaviour

What is asynchronous, how fast retrieval actually is, what the vectors are, and what is not enforced yet.

This page is the one that saves you an afternoon. It documents what GitLoom actually does today, including the parts that are not finished. Where a number is measured, it says so and against what. Where something is not enforced yet, it says that too, rather than describing an intention as a behaviour.

Writes are asynchronous

POST /v1/memories returns 202 Accepted. The memory does not exist yet.

{"id":"3f2b9e01-7c44-4d1a-9f6e-0a1b2c3d4e5f","namespace":"user-8213","status":"accepted"}

202 rather than 200 because extraction is several model calls against a conversation. Claiming 200 would make the next read look broken.

What happens between the 202 and the memory existing:

1. The request is validated — credential, namespace exists, at least one message — and enqueued. This is where a rejection happens, while you are still listening.
2. A worker picks it up, fetches the namespace's repository, and runs extraction, cue-writing, relation-linking, and reconciliation.
3. New and rewritten memories are committed to git, embedded, packed, and pushed back to object storage with a compare-and-swap.
4. The namespace's recorded head advances. From that instant, retrieval returns the new memories.

How long that takes

There is no published SLA, and you should not build a UI that depends on a specific figure. What is measurable:

• A single extraction call against a one-line conversation completed in 1.3s through the Bedrock adapter.
• A realistic session runs four prompt stages, some of which fan out across the extracted facts. Expect seconds for a short conversation, tens of seconds for a long one.
• The worker's hard timeout is 15 minutes. Anything approaching that is a bug, not a slow day.

There is no way to poll for completion

This is the sharpest edge in the current API, so it is worth stating plainly:

• The id in the 202 is the queue message id. It is not a memory id, and there is no endpoint that accepts it.
• There is no GET /v1/memories/{id}, no job status route, and no webhook.
• The only observable signal that ingestion landed is that GET /v1/retrieve starts returning the new material.

What to do instead. Do not write-then-immediately-read in the same user turn and expect the memory back. Write at the end of a turn and retrieve at the start of the next one; by then, ingestion has almost always finished. If you genuinely need to confirm, poll /v1/retrieve with a query you know the new content should match, with a backoff, and give up gracefully — retrieval is cheap, but it is not free.

Ordering and duplicate suppression

• Writes to one namespace are serialised. The queue's message group is the account/namespace pair, so one write to a given memory runs at a time. That is required for correctness: reconciliation decides whether a new fact rewrites an existing file, so two concurrent writers rebuilding the same repository would discard one another's work wholesale rather than merge it.
• Different namespaces run in parallel, bounded by worker concurrency (below).
• Identical bodies within a five-minute window are deduplicated. The queue is content-addressed for deduplication, so resending the exact same request body twice in quick succession returns 202 both times and ingests once. This absorbs an at-least-once caller; it also means a genuine retry of an identical payload is silently a no-op. Vary session_id if you mean two distinct writes.
• Failed messages are retried up to three times, then moved to a dead-letter queue where they are held for 14 days and alarmed on. A message reaching the DLQ is a lost write, and it is treated as a correctness alarm rather than a backlog one.

A partial failure that is not visible to you

If extraction succeeds but embedding fails, the memories are committed to git anyway and the failure is logged. Those memories are retrievable immediately by the lexical and graph arms, but not by semantic search, until the next successful write to that namespace fills the missing vectors in. Failing the whole job instead would re-run — and re-charge for — extraction that already worked.

The practical symptom: a memory that a keyword query finds but a paraphrased question does not, which starts working after the user's next session is ingested.

Write size

One POST /v1/memories carries at most 200 turns and 200,000 characters of conversation, in a body of at most 256 KiB. On the Free plan a write is capped at 20,000 characters; a longer one is refused with 413 write_too_large before it is queued or counted. Split a long conversation into several writes.

Retrieval latency

A plain retrieval (the default: mode=raw, no rank=jev) makes no model call except the query embedding, which Titan computes in ap-south-1.

Measured against the deployed stack over 200 authenticated requests:

Read that table carefully, because the two rows mean different things:

• 109 / 145 ms is server-side: the time inside the retrieval function. It is the number the internal p99 alarm watches, against a 200 ms budget.
• 211 / 383 ms is what a client actually waits. The difference is network. If you are further from ap-south-1 than India is, your number is larger, and no amount of work on our side changes that. GitLoom's API runs in one region today.

Roughly 100 ms of the server-side figure is the query embedding — a network round trip to Bedrock, not search. For comparison, before an embedder was wired the same measurement was p50 7.4 ms / p99 19.6 ms. So:

• Search itself costs single-digit milliseconds.
• The p99 budget is now spent almost entirely on one round trip, and the margin is 1.4x rather than the tenfold it used to be.
• The lexical and semantic arms run concurrently, so the embedding is not additive with lexical time — it dominates it.

vector_ms, lexical_ms and graph_ms are returned on every response so you can see this yourself rather than take our word for it.

Cold starts and cache behaviour

• cold_start: true marks the first request served by a fresh container. A cold start has been observed at 167 ms of function duration versus a 9 ms warm p50, plus the cost of fetching the namespace. That fetch is now the raw index alone — one object, no decompression — rather than the whole packed repository; on a 1,000-memory namespace that is 22 ms of local work instead of 243 ms. The archive is fetched only when no index for the namespace's current commit is published.
• A container keeps up to four namespaces warm on local disk, evicting the least recently used. A fifth namespace on the same container pays a fetch.
• Freshness is not a guess: every request does a metadata read and compares the warm copy's commit against the namespace's recorded head. A stale copy is discarded. So once ingestion records a write, the next read sees it — there is no propagation window to design around, and a deletion cannot linger in a warm cache.

Retrieval defaults

Embeddings

Why Titan and not Cohere, which would batch better: Cohere on Bedrock is a Marketplace model requiring an account-level subscription accepted in the console — IAM permissions alone do not unlock it. Titan is Amazon-owned and works with nothing but bedrock:InvokeModel. Both produce 1024 dimensions, so the stored vector width does not change if that decision is revisited.

Two consequences worth knowing:

• Your text is sent to Amazon Bedrock. Embeddings run in ap-south-1. Extraction uses Claude Haiku 4.5 through a global cross-region inference profile, so Bedrock may process it in another AWS region. See What touches your data; if your data must not be processed outside ap-south-1, the hosted service is not the right deployment.
• Semantic search scans linearly in the number of stored vectors. The published latency figures were measured on a 240-memory fixture, and they do not extrapolate to a very large namespace on their own. One namespace per end user keeps each index small, which is a large part of why the model is shaped that way.

Quotas

Per-account quotas are enforced. Every account has a plan — free if nothing was ever chosen — and every write, retrieval, playground chat, and stored-memory count is metered against that plan's monthly limits. See Plans and pricing for the numbers themselves; this section is about the mechanics.

• The check is atomic, a single conditional UpdateItem rather than read-then-write — two concurrent requests both reading "199 of 200 used" cannot both believe they are within budget.
• Refused before anything downstream runs. A write that will be refused is refused before it is queued; the caller never holds a 202 for something that never happens.
• Free and pay-as-you-go stop at the limit. Exceeding a meter returns 429 quota_exceeded for the rest of the month.
• Subscribed plans (Starter and above) overflow into the wallet instead of stopping — see Overage. An empty wallet on overage is 402 balance_exhausted.
• Every plan also has a per-minute rate limit, independent of the monthly allowance — see Rate limits. A throttled request is 429 rate_limited and costs nothing; it clears within the minute rather than at the next calendar month, and its Retry-After header gives the seconds left.
• Read your own standing with GET /v1/usage, and the wallet/plan/rate card with GET /v1/billing — see API reference.

{"error":{"code":"quota_exceeded","message":"monthly limit reached: 500 writes on the free plan; it resets on 2026-11-01 at 00:00 UTC, or upgrade at https://app.gitloom.cloud"}}
{"error":{"code":"balance_exhausted","message":"the wallet is empty; recharge from the dashboard's billing page"}}
{"error":{"code":"rate_limited","message":"rate limited: the free plan allows 60 reads per minute; retry in 12s"}}

A notification fires internally when a meter crosses 80% of its limit, so an account approaching a ceiling is not surprised by it.

Infrastructure ceilings, shared across every account

Separate from per-account quotas, these are platform-wide limits — they exist so no single account's traffic can starve every other account's, and they are not sized per plan:

Revocation takes up to 30 seconds. Authorization results are cached for 30 seconds so that an agent calling with the same key every turn does not pay a lookup each time. A revoked key therefore keeps working for up to half a minute. Treat revocation as "stops within a minute", not "stops instantly", and rotate anything genuinely compromised with that in mind.

Errors

Every error a handler returns has one shape:

{"error":{"code":"namespace_not_found","message":"create namespace \"user-8213\" before writing to it"}}

Branch on code and on the HTTP status. The message text is prose and may be reworded; the codes are stable. The exceptions are a missing or refused credential, which API Gateway answers before any handler runs, with a body of only {"message":"Unauthorized"} or {"message":"Forbidden"}. The SDKs report both as code unauthorized.

A refused credential is deliberately uninformative. Distinguishing "no such key" from "wrong secret" tells an attacker which half of a guess was right, so both fail identically, with the same 403 — and in constant time.

Environments: live and test are not isolated

A key carries an environment in its prefix, gl_live_ or gl_test_, and GET /v1/whoami reports it. The environment is not currently a data boundary. A gl_test_ key reads and writes exactly the same namespaces as a gl_live_ key on the same account.

The prefix is useful today for two real things: a production credential pasted into a test config is obvious on sight, and secret scanners can match it. It is not a sandbox. If you need one, use a separate namespace — that is a hard boundary — or a separate account.

Browsers

A browser can call the API only from the dashboard's own origins: the CORS policy allows them GET, POST, PATCH, DELETE and OPTIONS. From any other web origin the browser refuses the call, so call GitLoom from your server.

That is a limitation, but the security advice would be identical without it: an account-wide API key reads and writes every namespace, so it belongs on a server. Call GitLoom from your backend, and let your backend decide what a browser may ask for.

What GitLoom does not do yet

Listed so you can plan around them rather than discover them:

• No ingestion status. Every write returns 202; the only signal that it landed is that reads start returning it.
• No pagination, except the request log (GET /v1/logs, by cursor). Other listings are capped and truncated silently.
• One storage region. ap-south-1, with no data-residency option. The Claude calls may be processed in other AWS regions; see What touches your data.
• No webhooks or events.

Reproducing these numbers

The latency figures come from the deployed stack, driven over 200–250 authenticated requests against a 240-memory fixture, and read back from the same Gitloom/Retrieval metrics the production p99 alarm watches. Ingestion timings come from the worker's own logs. Nothing on this page is an estimate presented as a measurement; where a figure is a range rather than a number, it is written as one.