Knowledge Graph

client.graph provides access to the knowledge graph automatically built from your memories. Entities — people, organizations, places, and things — are extracted from memories and linked by their relationships. You can search for entities, traverse their connections, or ask natural language questions answered from the graph.

---

graph.search

Searches for entities in the knowledge graph by text. Returns entities ranked by relevance.

Signature

client.graph.search(params: GraphSearchInput): Promise<Entity[]>

Parameter	Type	Required	Description
query	string	Yes	Text query to search for entities
userId	string	No	Restrict search to entities linked to a specific user
type	EntityType	No	Filter by entity type: PERSON, ORGANIZATION, PLACE, or THING
limit	number	No	Maximum results to return (default 10)

Example

const entities = await client.graph.search({
  query: 'backend engineers TypeScript',
  userId: 'user_123',
  type: 'PERSON',
  limit: 5,
});

for (const entity of entities) {
  console.log(entity.id);           // "ent-uuid-here"
  console.log(entity.name);         // "João Silva"
  console.log(entity.type);         // "PERSON"
  console.log(entity.description);  // "Senior backend engineer, specializes in TypeScript"
}

Example — searching for organizations

const orgs = await client.graph.search({
  query: 'cloud infrastructure companies',
  type: 'ORGANIZATION',
  limit: 10,
});

orgs.forEach((org) => {
  console.log(org.name, org.type);
  // "AWS"    "ORGANIZATION"
  // "Vercel" "ORGANIZATION"
});

---

graph.traverse

Traverses relationships outward from a known entity. Returns the paths connecting the entity to others within the specified number of hops.

Use graph.search first if you need to find the entityId for an entity.

Signature

client.graph.traverse(params: GraphTraverseInput): Promise<TraversalResult>

Parameter	Type	Required	Description
entityId	string	Yes	ID of the entity to start traversal from
direction	string	No	outgoing, incoming, or both (default both)
hops	number	No	Depth of traversal: 1, 2, or 3 (default 2)

Example

// First, find the entity
const [person] = await client.graph.search({
  query: 'João Silva',
  type: 'PERSON',
  limit: 1,
});

// Then traverse their relationships
const traversal = await client.graph.traverse({
  entityId: person.id,
  direction: 'outgoing',
  hops: 2,
});

console.log(traversal.startEntity.name);  // "João Silva"

for (const path of traversal.paths) {
  console.log(path.entity.name);      // "Acme Corp", "TypeScript", "Project X"
  console.log(path.relationship);     // "WORKS_AT", "USES", "CONTRIBUTES_TO"
  console.log(path.depth);            // 1, 2
}

Example — finding who else works at the same company

const traversal = await client.graph.traverse({
  entityId: 'org-acme-corp-uuid',
  direction: 'incoming',
  hops: 1,
});

// All entities pointing inward to Acme Corp
for (const path of traversal.paths) {
  if (path.relationship === 'WORKS_AT') {
    console.log(path.entity.name, 'works at Acme Corp');
  }
}

---

graph.query

Answers a natural language question using the knowledge graph. The question is interpreted, relevant entities and relationships are retrieved, and a natural language answer is generated with a confidence score.

Signature

client.graph.query(params: { question: string }): Promise<GraphQueryResult>

Parameter	Type	Required	Description
question	string	Yes	Natural language question about the knowledge graph

Example

const result = await client.graph.query({
  question: 'What projects is João Silva currently working on?',
});

console.log(result.answer);
// "João Silva is currently contributing to Project X and the internal
//  API redesign at Acme Corp. He leads the backend team on Project X."

console.log(result.confidence);  // 0.87 — 0.0 to 1.0

for (const entity of result.entitiesUsed) {
  console.log(entity.name, entity.type);
  // "João Silva"  "PERSON"
  // "Project X"   "THING"
  // "Acme Corp"   "ORGANIZATION"
}

Example — relational questions

const result = await client.graph.query({
  question: 'Who on the team has experience with Rust?',
});

console.log(result.answer);
// "Based on stored memories, Maria Costa and Pedro Alves have experience
//  with Rust. Maria used it for systems programming at her previous company,
//  and Pedro built a WebAssembly module with it for Project Y."

console.log(result.confidence);  // 0.76

A low confidence score (below 0.5) means the graph does not have enough information to answer reliably. In that case, try searching memories directly with client.memories.search.

---

When to use each method

Question	Recommended method
"Who is João Silva?"	graph.search with type: 'PERSON'
"What is João connected to?"	graph.traverse from João's entity ID
"What projects is João working on?"	graph.query with a natural language question
"Who works at Acme Corp?"	graph.traverse from Acme's entity ID, direction: 'incoming'
"What tools does the team use?"	graph.search with type: 'THING'

---

Related

• Memories — create memories that populate the graph
• Knowledge — structured knowledge derived from memories
• Type Reference — Entity, TraversalResult, GraphQueryResult, and related types