add()

Add an entity to your knowledge graph with automatic embedding generation.

Signature

brain.add(entity: AddOptions): Promise<string>

Parameters

Property Type Required Description
data string Yes The content to store and embed
metadata object No Key-value pairs for filtering
nounType NounType No Entity type (default: Concept)
id string No Custom ID (auto-generated if not provided)
embedding number[] No Pre-computed embedding (auto-generated if not provided)

Returns

A Promise that resolves to the entity's ID (string).

Examples

Basic Usage

basic.js
// Simple add - embeddings generated automatically
const id = await brain.add({
  data: "JavaScript is a programming language"
})

console.log(id) // "a1b2c3d4..."

With Metadata

metadata.js
// Add with metadata for filtering
const id = await brain.add({
  data: "TypeScript adds static types to JavaScript",
  metadata: {
    type: "language",
    year: 2012,
    creator: "Microsoft",
    tags: ["typed", "compiled"]
  }
})

// Now you can filter by metadata
const results = await brain.find({
  query: "programming",
  where: { year: { greaterThanOrEqual: 2010 } }
})

With Noun Type

nountype.js
import { Brainy, NounType } from '@soulcraft/brainy'

// Specify entity type for better organization
await brain.add({
  data: "Elon Musk",
  nounType: NounType.Person,
  metadata: { company: "Tesla" }
})

await brain.add({
  data: "San Francisco, California",
  nounType: NounType.Place,
  metadata: { country: "USA" }
})

await brain.add({
  data: "Machine Learning fundamentals",
  nounType: NounType.Concept
})

With Custom ID

custom-id.js
// Use your own IDs
await brain.add({
  id: "user-123",
  data: "User profile information",
  metadata: { role: "admin" }
})

// Reference by your ID later
const user = await brain.get("user-123")

Bulk Add

bulk.js
// Add multiple entities efficiently
const entities = [
  { data: "JavaScript", metadata: { year: 1995 } },
  { data: "TypeScript", metadata: { year: 2012 } },
  { data: "Python", metadata: { year: 1991 } }
]

const ids = await Promise.all(
  entities.map(e => brain.add(e))
)

console.log('Added:', ids.length, 'entities')

Notes

See Also

Next: find() →