Start here

Documentation

Contextely is the layer between your systems of record and every AI that reads from them. If you want the shortest path to a working retrieval, start with the quickstart; this page is the concepts behind it.

Quickstart →MCP server reference →REST API reference →CLI reference →Partner API →Self-hosting →

Concepts

A workspace is your company. A member is an asker, either a person or the identity an agent's API key speaks as, carrying a role and a set of entitlement scopes. A source is a system of record Contextely reads from and re-reads when memory goes stale. A memory object is one condensed, source-cited fact-set with its own freshness contract and entitlement requirement.

1. Connect a source

Two connectors ship today, and adding a system of record means answering their questions rather than waiting for code. Both are asked for the same two things: how to list records once, and how to re-read one later. What connects today is the honest list of what has been run end to end.

Postgres, Supabase or Neon

A read-only connection string and two queries. Contextely refuses anything that is not a single SELECT or WITH, and opens the session read-only.

list:  select id as ref, name as title, notes as content
       from accounts where active

fetch: select id as ref, name as title, notes as content
       from accounts where id::text = $1

Saving runs both: it lists one row, re-reads that same row through the fetch query, and checks it got the same record back. A fetch query that ignores its parameter would otherwise give every memory object from this source the same content on the first refresh.

Any MCP server

Give Contextely the Streamable HTTP endpoint, the name of a tool that lists records and the name of a tool that fetches one, plus the argument names each expects and which fields of the returned record hold the identifier, the title and the text. Contextely connects as an MCP client. Servers disagree about all of those, so they are configuration rather than a convention every server is assumed to follow.

The argument that names the record is the one worth getting right. A fetch tool called with the wrong argument name usually ignores it and answers with its first record, so the connection test asks the server which arguments it accepts and then re-reads a real record to check it comes back.

2. Set the freshness contract

Each source has a TTL. Every memory object it produces inherits it. When a retrieval selects an object older than its TTL, Contextely re-reads that record from the source, re-condenses it and answers with what is true now. If the raw payload is unchanged the clock simply resets and no LLM call is made.

If the refresh fails, the result comes back labelled stale_refresh_failed with the reason. There is no path where an out-of-date answer is served as though it were current.

3. What a memory object holds

One record in, one memory object out. It carries three things, and the third is the one people are surprised by.

The condensed fact.A few hundred words of what is currently true, written from the record by the condenser, plus the entities, topics and keywords it is about. This is what goes into your agent's prompt.

Links to related memory. Two objects that share entities or topics are related, and how strongly is a number you can see. Call context_related (or open a memory in the dashboard) to walk from one to its neighbours, instead of guessing at a second search query. A neighbour outside your scopes is never named or counted.

The address of the original.The source, the record's stable reference in it, and a citation URL. Contextely does not store your documents, so when the summary is not enough, call context_expand: it goes back over the same connector and returns the whole current record, with no model in the way. That costs one source round-trip and is metered against your monthly refresh allowance, which is why it is a separate call rather than something every search pays for.

4. Set entitlement scopes

A source can require scopes; every object from it inherits them. A member holds grants. A grant of finance:* satisfies a requirement of finance:payroll. Requirements are a conjunction, so all of them must be satisfied. Owners and admins hold *.

Use Ask as on the dashboard to run a query as another member and see exactly what they can and cannot retrieve, through the identical code path an agent would hit.

5. Call it

REST

curl -s https://www.contextely.com/api/v1/search \
  -H "Authorization: Bearer ctx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"acme renewal","limit":5}'

CLI

curl -fsSL https://www.contextely.com/cli.mjs -o contextely && chmod +x contextely

./contextely config set-key ctx_sk_...
./contextely search "acme renewal"
./contextely related <memory-id>   # walk to what it relates to
./contextely expand <memory-id>    # read the whole record from the source

The same call over MCP, with the full reference for HTTP and the CLI.