Knowledge Twins
A living, permission-aware model of what a person, team or organisation knows — the asset your agents work from.
A Knowledge Twin is a structured, always-current representation of how someone works and what they know — used by agents under that person's permissions. It is not a document store and not a chat log; it is the compiled truth, kept correct over time, that an agent can reason over on their behalf.
Where a raw memory is the infrastructure (the graph, the connectors, the Projects), a Knowledge Twin is the asset built on top of it: the part people actually point an agent at.
Four kinds of twin
A twin can be scoped to one person or widened to a whole organisation. The mechanics are the same; only the membership and the sources change.
| Twin | Who it models | Typical use |
|---|---|---|
| User twin | One app user (the builder's User Graph) | Give each user's agent a memory you control, per object |
| Expert twin | One specialist | Let an agent answer the way that expert would |
| Team twin | A team or department | One shared memory every teammate's agent works from |
| Company twin | The whole organisation | What the company knows, current and access-aware |
The User Graph is the builder version of a Knowledge Twin — a twin of each app user. The same model scales up to experts, teams and the whole company; the growth path is one twin → a team's twins → the whole organisation's twins, in your own cloud or fully air-gapped.
What makes it a twin, not a pile of text
A Knowledge Twin is only useful if it stays true and stays safe. It is built on the same guarantees the rest of the platform provides:
- A typed knowledge graph — entities, typed relationships and facts, so the twin can answer relationship questions, not just surface similar text. See Knowledge graph.
- Kept current and correct — contradiction detection, entity coherence, bi-temporal truth (what was true when) and a memory health grade keep the twin from going stale or contradicting itself. See Knowledge quality.
- Permission-aware — every query runs under the caller's rights. A twin returns only what that person (or their agent) is allowed to see.
- Governed and scoped — a twin is organised into Projects with server-side scoping, audit and DLP masking, so the reasoning an agent sees never leaks outside its perimeter.
How an agent uses a twin
- Build it — connect sources (connectors, file uploads, the ingest endpoint, or captured conversations). Extraction turns them into graph facts.
- Keep it true — the maintenance engines run continuously: dedupe entities, catch contradictions, expire superseded facts, mask secrets.
- Ask it — point any agent at the twin over MCP, or call search / ask directly. The answer is scoped to the caller's permissions and cited back to its sources.
- Write back — what the agent learns or decides can be captured into the twin, so the reasoning behind a decision survives the session that produced it.
API objects behind a twin
A Knowledge Twin is not a single endpoint — it is the memory graph plus the scoping and maintenance around it. In the API it is made of familiar objects:
- a memory (the graph + vector store) — see Memories
- one or more Projects for scoping (represented in the API as
spaceobjects: endpoints under/spaces, idspace_id) - the search / ask and conversation-capture endpoints that read and write the twin — see the Memory API reference
Naming note: in the product UI these scoped containers are called Projects. For backward compatibility the API still represents them as
spaceobjects (/spaces,space_id); the two refer to the same thing.