The Kemory
API reference.

Base URL, auth and conventions

Every endpoint below is served by the Kemory API. Paths are given exactly as the service exposes them; prepend your deployment's origin.

Three ways to authenticate

This table describes the hosted deployment. A deployment running the single-user identity provider instead — the default in the community compose file — accepts a single static API key — sent either way, since a non-JWT credential arriving in the Authorization header is still treated as a key — and rejects real JWTs.

20 of the operations below need no credential, each marked no auth in the tables. They are not only probes and public documents, so the categories are worth reading rather than assuming:

• Health — five probes.
• OAuth discovery — three .well-known documents, plus the dynamic client registration shim, which echoes a fixed pre-registered public PKCE client rather than creating one.
• Artifact streams — three, carrying their own signature in the URL precisely so a binary can be fetched without a bearer.
• Code-claiming endpoints — the pair claim, and the join claim and validate. The code is the credential, so these are unauthenticated by design and are the security-interesting members of this list: a pair claim self-registers an agent.
• Telemetry ingest and the public plan catalogue.

The full list is generated from the same document as the endpoint tables, so it cannot fall behind the code:

A credential is not the whole access boundary. Some Analytics and Consolidation operations additionally require an internal-staff identity and are not reachable with an API key or an agent token, however valid.

Scoping

Most tenant-scoped ORM reads have WHERE org_id = <caller's org> injected by a SQLAlchemy do_orm_execute listener, acting as a safety net over the filters handlers also apply. It is a net, not a universal guarantee: it covers registered models, SELECTs, and statements that expose a mapped entity — raw SQL and unmapped statements are the handler's own responsibility.

Memories default to owner-private, but for two of the four visibilities visibility is access control, not a label: a memory written org-public is readable by every user in the organisation, and one written team by every member of that team. So "scoped to their owner" is the default, not an invariant.

agent-private is the opposite trap — it is only a label. The tenancy filter treats it exactly like user-private, and no read path narrows it to the writing agent, so it does not hide a memory from the same user's other agents. Do not use it as an isolation boundary.

shared is the default namespace name, not an access tier — it gets no special handling in the gatekeeper or the tenancy filter. Agents authenticate as their user, so any namespace the user can reach is reachable by that user's agents; whether a given agent actually reads it is then decided by its own gatekeeper rules.

Compaction — the tier ladder

A memory is not stored once and left alone. It is served back at several levels, each a cheaper reading of the same content.

Only three of the rows below are states an individual memory occupies: L1, L2 and L3.1. Those are reported on the memory's own compression_tier response field — the supported surface, in preference to the internal metadata._compression_tier key — and the same three values work as a search filter. L1 is the default: nothing writes it, the key is simply absent until the pipeline promotes the memory. The remaining rows are not per-memory states at all, and live elsewhere entirely.

Read a namespace at a chosen level with GET /api/v1/namespaces/{namespace}/compressed: mode takes raw (L1), aaak (L2), concept (L3.1) or cognition (L4), and merge_mode selects the latest state or the full history. L3 narrative is not a /compressed mode — it is read through the namespace and session summary endpoints.

Below five memories, L3 is not prose

All three L3 flavours require at least 5 source memories to call a model. Below that they emit a deterministic, LLM-free bullet list of the source memories instead — so no summary tier guarantees prose.

Only the namespace flavour says so in its tier. The namespace summary tags the fallback L3-extractive. The session and cumulative rollups do not: they report the literal L3 whether the text is prose or a bullet list. A client that switches on the tier to decide how to render will get this wrong on session summaries — do not treat L3 on a session rollup as a promise of prose.

Tier strings a caller may encounter include L3, L3-extractive, L3.1, L3.1-raw, L3.1-chat, and on session digests L2.1 and L2.1-extractive. Some read paths also synthesise a value when the stored column is empty. Treat the set as open. Match on the exact base before the first hyphen, and on the -extractive / -raw suffix to detect a degraded variant — rather than switching on an exhaustive list. Do not match a bare L3 prefix: it also catches L3.1, which is concept synthesis, not narrative prose.

L3.1-raw is the degraded marker: a cluster formed but synthesis did not produce usable output — whether the backend was unreachable or simply returned nothing useful — so the stored text is unsynthesised source material rather than prose.

L5 deliberately excludes siblings

L5 compares this namespace's summary against the same user's other namespace summaries, and deliberately skips same-prefix siblings: project:alpha and project:beta are structurally distinct by design, not accidental duplicates, so they are never proposed for merge however similar their prose. A pair is flagged only above a cosine threshold and within a content-date window, and the result is advisory — nothing merges on its own.

L5 is not the top of the ladder. Despite the number it is a background duplicate-namespace detector, not a richer read. The cross-namespace "who is this user" paragraph is GET /api/v1/user/context?depth=l4.

"L4" labels two different reads. In this table it means concepts plus graph entities for one namespace. On user context, depth=l4 means a synthesis pass across namespace summaries. They share a name and a number and fail in different ways — read the one you are actually calling.

AAAK is a storage, transport and diagnostic dialect — not context compression. It saves bytes against compact JSON while often costing prompt tokens against readable text, and off-the-shelf gzip beats it losslessly by a wide margin. Reaching for aaak to shrink a prompt is a misreading of the tier. Semantic compaction is what reduces what a model must read: L3/L3.1, and L2.1 for a live session.

Why a namespace may not have summarised

Several gates guard L3, and they are the usual answer to "why has this namespace not summarised yet". Two are similarity checks, and they are genuinely different tests, often conflated:

• Novelty — is the new memory a near-duplicate of a memory already in the namespace? Above a high cosine bar the run is skipped.
• Coverage — is the new memory already represented in the existing summary, compared against the summary's own embedding at a lower bar?

Either can skip a run on its own, and neither means anything is broken: a namespace whose new material restates what is already summarised is correctly left alone rather than paying for a model call to say it again.

Note also that the sub-five-memory bullet-list fallback runs before any model call, and on a session rollup it is still tiered L3. On a session rollup, an L3 tier is therefore not evidence that a model produced the text. (The namespace flavour does distinguish the two — it tags the fallback L3-extractive.)

Not every empty summary is a gate doing its job. L3 also depends on the deployment's model configuration, and the write path is not the only route that produces summaries — some are generated by background and warm-up paths with different preconditions. If a namespace has no summary and the similarity gates above do not explain it, treat it as a threshold or configuration question — a namespace below the minimum memory count simply has nothing to summarise — and check docs/memory-management.md in the repository rather than inferring the cause from the tier alone.

L2.1 — the rolling session digest

This is the service most often described as "the last few messages plus a summary", and the one to reach for when the problem is prompt-window pressure during a live session rather than recall across the vault.

Kemory keeps the latest few exchanges verbatim — three by default — and compacts everything older into a single readable, token-budgeted digest covering the current objective, decisions, constraints and open loops. The raw tail is a per-call parameter clamped to 1–10 exchanges; 3 is the default, so the digest first appears once a session runs past its raw tail. It is deliberately prose rather than AAAK, because it is prompt-facing — the tier that exists to be read by a model is the one that must not be encoded for bytes. If no model backend is reachable, or the call fails or returns nothing, a deterministic extractive fallback runs instead.

Nothing is lost, only deferred

The digest carries retrieval hooks and the source ids behind its sections and facts, so an agent needing the exact wording of an older exchange can drill back to it on demand rather than being told a compressed approximation is all that survives. That is the difference between this and truncating a transcript.

MCP-only. There is no REST endpoint for the session digest — it is reached through the two tools above over POST /mcp/v1. A REST client wanting session context has to go through MCP. It is also not searchable: the digest is retrieved by session, not found by query.

Search summary — the service behind enhance

Not a separate service, which is why it is hard to find: it is POST /api/v1/search/unified with the summary opted in.

The call returns top ranked hits across memories, chats and text-native files and, when asked, a short narrative summary written over those hits.

As of writing, the Kora browser extension's enhance is built on it (extension behaviour described here lives in a separate repository, so treat it as how the client uses the endpoint today rather than part of the API contract): it searches on the user's draft plus recent conversation turns, takes the top handful, and appends them to the prompt as a delimited, provenance-tagged context block alongside the summary. Nothing rewrites the draft — the model is given context and left to decide.

The invariant that matters

The summary is written only over hits that were returned, and its sources array lists the ids it drew on. Treat that as a property of how the summary is produced rather than a guarantee about the response in your hand — see the caching caveat below, which is the case where it does not hold. This is what stops the summary asserting something the user cannot click through and verify — so a client that filters results after the fact must drop the summary too, or it outlives the hit it was describing. Note this is a contract the caller must honour, not something enforced for you: the constraint is applied when the summary is written, not re-checked afterwards.

The summary is opt-in because it costs a model call, and a caller that only needs a count or a list should not pay for prose.

Summaries are briefly cached per user and query — and the cache key is only the user and the query text. It does not include the result filters. So the same query issued with a narrower type filter or a smaller limit can be served a cached summary whose sources reference hits that are not in the response you are holding. If you rely on the sources-are-a-subset property, request without narrowing, or ignore the summary when you do narrow.

Degrading honestly

If the summary cannot be produced, the response carries results with no summary rather than failing. Treat it as decoration over the results, never as the result itself. A client may also fall back to a plain memory search when the unified endpoint is unavailable — in which case there is no summary at all, and the context block is hits only.

User context — what the vault knows about someone

GET /api/v1/user/context returns a cross-namespace summary for the authenticated user, assembled from the compressed tiers rather than by reading every memory. It is the fast "catch me up" read that agents call at the start of a session, and it takes a depth so a caller can ask for a cheaper or richer answer.

At depth=l4 it runs one synthesis pass across the per-namespace summaries. That pass is not stored — it is computed per request — and it degrades gracefully: if the model call fails, the response comes back without the synthesised layer rather than erroring. Treat the summary as an optional enrichment over the namespace data, not a guaranteed field.

There is also an entitlement gate ahead of the model call. It keys on the caller's resolved entitlement feature, not on a plan name: where that feature resolves to the basic tier, the request is downgraded to depth=l3 and answered with a degraded block, so the synthesis never runs. If entitlements fail to resolve at all the gate does not fire and the full pass runs. Both directions surprise people debugging a missing — or unexpectedly present — synthesis layer.

GET /api/v1/user/profile is the narrower, persisted view: static preferences plus a dynamic part maintained as memories accumulate.

Memories 24

Create, read, search and version memories. The core surface — everything else is either feeding this or reading from it.

Unified Search 1

One ranked search across memories, chats and text-native files, with an optional narrative summary. This is what the Kora extension's enhance uses.

User Context 11

Cross-namespace summaries of who the caller is and what the vault knows, plus the account-level privacy controls (consent, encryption opt-in, crypto-shred).

Consolidation 6

Namespace consolidation policy and the stats behind it — the tier machinery described above, exposed for inspection and manual runs.

Enrichment 3

Post-write enrichment of individual memories (entities, structure).

Relations 4

Explicit relations between memories, detected conflicts, and the forgetting log.

Projects 2

Explicit and implicit project aliases over namespaces.

AI Chats 13

Captured conversations from ChatGPT, Claude, Gemini, Perplexity and Manus — upsert, list, classify and move.

AI Chats — Merge 6

Merging chats into a shared namespace, splitting them out again, and the full assignment audit trail.

AI Chats — Mappings 4

User overrides that pin a chat to a namespace.

artifacts 8

Binary attachments on chat turns — files, audio, video, images.

Agents 10

Registered clients that hold credentials against the vault: MCP clients, CLI installs, the browser extension.

Extension Keys 4

Credentials issued specifically to the Kora browser extension.

Pair 4

The quick-connect flow: a short-lived code exchanged for an API key.

MCP Server 5

The Model Context Protocol transport. POST /mcp/v1 is the live endpoint; the per-verb paths are deprecated.

MCP 6

Connected MCP client status.

OAuth discovery 4

RFC 9728 protected-resource and authorization-server metadata, plus the dynamic client registration shim.

Cells directory 1

Unauthenticated residency-cell directory — which cells exist and their public hosts, so clients route to the right region without a hardcoded list.

Identity 2

Who the bearer token belongs to.

Permissions 5

Per-agent, per-namespace permission grants.

Gatekeeper 3

Ordered rules evaluated on every access decision — lower priority number first, first match wins.

Teams 5

Kemory's own teams and membership. Independent of Core_Backend's teams; there is no sync between them.

Graph 2

The access graph — who can reach what.

Audit & Governance 4

Audit trail over reads and writes.

Dashboard 6

Aggregates backing the dashboard home.

Analytics 21

Storage, usage and quality analytics.

Usage 1

Plan usage summary.

Telemetry 1

Opt-in CLI beacon.

Health 6

Liveness, readiness and deep dependency health.

billing 7

Kemory plans and checkout. Proxies Core_Backend.

These endpoints forward to Core_Backend. Kemory serves the route; the behaviour behind it is owned elsewhere.

referral 2

Referral codes. Proxies Core_Backend.

These endpoints forward to Core_Backend. Kemory serves the route; the behaviour behind it is owned elsewhere.

residency 3

Data-residency region selection. Proxies Core_Backend.

These endpoints forward to Core_Backend. Kemory serves the route; the behaviour behind it is owned elsewhere.

join 2

Waitlist-bypass claim.

Ask 1

Kora 1

Notifications 6

OpenAI plugin verification 1

Keeping this page honest

The endpoint tables on this page are generated from the running service's own OpenAPI document by scripts/generate_api_reference.py in the Kemory repository. They are not maintained by hand, because a reference covering this many operations drifts the moment someone adds a route — and a docs page that is quietly wrong is worse than no page at all, since it is trusted.

Regenerate after any route change. The narrative sections above are hand-written and describe behaviour a schema cannot express; they need a human when the behaviour changes.