---
title: Knowledge
description: Write sourced episodes into a Knowledge space and recall permission-trimmed facts with episode citations.
type: tutorial
product: knowledge
summary: Create a space, write an episode, and recall it with citations.
updated: 2026-10-13
order: 0
---

Knowledge is one graph per environment that your people, apps and agents
write as they work. You write **episodes** (what someone said or did, with its
source) into **spaces**; Knowledge keeps them as primary records and answers
**recall** with the facts the caller may read, each citing the episodes it
came from. Nothing needs to be set up first: the graph exists as soon as you
create its first space.

<Prerequisites
	items={[
		'An account, and a project with an environment — see the platform start page',
		'An Access key with the knowledge:write scope (knowledge:read to recall)',
	]}
/>

Everything is under
`https://api.sylphx.com/v1/orgs/{org}/projects/{project}/envs/{env}/`, and an
environment outside the key's scope answers `404`.

## 1. Create a space

```bash
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces?space_id=support" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"kind":"workspace"}}'
```

A space is the unit of permission. Its creator may read and write it; grant
others through the space's members. A `sensitive` space is read only by keys
it names directly.

## 2. Write an episode

```bash
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/support/episodes" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"note","text":"Ada moved to London in March.","provenance":{"references":[{"uri":"urn:support:ticket:4812"}]}}'
```

Every episode names its source in `provenance.references`; Knowledge records
who wrote it from your key. The episode is stored at once, indexed for recall
shortly after, and its facts are extracted in the background.

## 3. Recall with citations

```ts
const { context } = await sylphx.knowledge.entities.recall({
  parent: 'orgs/acme/projects/shop/envs/production',
  query: 'Where does Ada live?',
  spaces: ['orgs/acme/projects/shop/envs/production/spaces/support'],
})
```

Recall searches only the spaces you name and the caller may read, expands up
to two hops through the graph, and returns facts with the episodes that
support them. A claim whose source changed since it was pinned is marked
stale and must be re-read before use.

## Erase

Deleting an episode erases it and everything derived only from it; it is
never answered again, even from a replayed request.