Skip to main content
@cognee/cognee-ts provides Node.js bindings for the cognee-rs AI-memory SDK, built with Neon. It is published on npm as @cognee/cognee-ts.
Cognee transforms raw text, files, and URLs into a persistent, queryable knowledge graph. The high-level API is remember (ingest + extract in one call) → recall (source-aware retrieval). These wrap the lower-level add → cognify → search stages, which remain available when you need finer control.

​
Installation

npm install @cognee/cognee-ts

​
Quick start

import { init, Cognee } from '@cognee/cognee-ts';

// Boot the Rust async runtime (call once at process start).
init();

const c = new Cognee({
  llmModel:   "gpt-4o-mini",
  llmApiKey:  process.env.OPENAI_TOKEN,
});

// Warm up engines (builds embedding model, resolves default user).
await c.warm();

// Ingest content and extract a knowledge graph in one call.
await c.remember({ type: "text", text: "The quick brown fox jumps over the lazy dog." }, "demo");

// Recall an answer with source-aware routing.
const recall = await c.recall("What does the fox do?");
console.log(recall.searchResponse?.result?.data);

​
Constructor

const c = new Cognee(settings?)
settings is an optional object (or JSON string) that overrides env-derived defaults. Keys are the canonical Settings field names (llmModel, embeddingProvider, vectorDbProvider, etc.). Absent keys keep their env-variable or compiled-in default.

​
Config

Use c.config to change settings after construction. Granular setters are synchronous and take effect immediately (the engines are lazily rebuilt on the next pipeline call). 
c.config.setLlmModel("gpt-4o");
c.config.setLlmApiKey(process.env.OPENAI_TOKEN!);
c.config.setEmbeddingProvider("openai");
c.config.setEmbeddingModel("text-embedding-3-small");

// Bulk setters (throw on unknown key or type mismatch) — one per subsystem:
c.config.setLlmConfig({ model: "gpt-4o", temperature: 0.2 });
c.config.setEmbeddingConfig({ provider: "openai", model: "text-embedding-3-small" });
c.config.setVectorDbConfig({ provider: "brute-force" });
c.config.setGraphDbConfig({ provider: "kuzu" });

// Generic key-value setter:
c.config.set("llmModel", "gpt-4o-mini");

// Read back the current config (secret fields are redacted):
const cfg = c.config.get();
console.log(cfg);

​
Core Memory API

Use these operations first. They are the high-level memory API in the TypeScript SDK.

​
remember

Store content as permanent graph memory, or as session memory when you pass sessionId. 
// Permanent graph memory: ingest, extract, and enrich in one call.
await c.remember({ type: "text", text: "…" }, "my-dataset", {
  selfImprovement: true,
});

// Session memory: fast short-term memory for a conversation or agent run.
await c.remember({ type: "text", text: "…" }, "my-dataset", {
  sessionId: "session-id",
  selfImprovement: true,
});

​
recall

Retrieve from session and graph memory. With scope: "auto", session memory is checked before graph memory. 
const result = await c.recall("What did we discuss?", {
  sessionId: "session-uuid",
  scope: "auto",   // "graph" | "session" | "trace" | "graph_context" | "all"
});

​
improve

Run the session-to-graph bridge and graph enrichment pipeline. 
await c.improve({
  datasetName: "my-dataset",
  sessionIds: ["session-uuid"],
});

​
forget

Remove permanent memory by item, dataset, or everything. 
// Forget a single item
await c.forget({ kind: "item", dataId: "uuid", dataset: { name: "my-dataset" } });

// Forget an entire dataset
await c.forget({ kind: "dataset", dataset: { name: "my-dataset" } });

// Forget everything
await c.forget({ kind: "all" });

​
rememberEntry

Store a typed memory entry ("qa", "trace", or "feedback") in a session. 
const result = await c.rememberEntry(
  { type: "qa", question: "…", answer: "…" },
  "my-dataset",
  "session-uuid",
  { tenant: "tenant-id" }, // optional
);

​
Resource managers

​
Datasets

const datasets   = await c.datasets.list();
const items      = await c.datasets.listData(datasetId);
const hasContent = await c.datasets.has(datasetId);
const statuses   = await c.datasets.status([id1, id2]);

await c.datasets.empty(datasetId);
await c.datasets.deleteData(datasetId, dataId);
await c.datasets.deleteAll();

​
Sessions

const entries = await c.sessions.get("session-uuid", { lastN: 10 });

await c.sessions.addFeedback("session-uuid", "qa-uuid", "Great answer!", 5);
await c.sessions.deleteFeedback("session-uuid", "qa-uuid");

const ctx = await c.sessions.getGraphContext("session-uuid");
await c.sessions.setGraphContext("session-uuid", "new context");

​
Notebooks

// List all notebooks for the current user.
const notebooks = await c.notebooks.list();

// Create a new notebook with optional cells and deletability flag.
const nb = await c.notebooks.create("My Notes", [], true);

// Partially update a notebook (name, cells, or both).
const updated = await c.notebooks.update(nb.id, { name: "Renamed Notes" });

// Delete a notebook — returns true if a row was removed.
const removed = await c.notebooks.delete(nb.id);

​
Users and pipeline-run admin

// Resolve (or lazily create) the default user for this handle.
const user = await c.users.getOrCreateDefault();

// Unblock a dataset stuck in "running" state so it can be re-cognified.
await c.users.resetPipelineRunStatus(datasetId, "cognify_pipeline");

// Reset all pipeline-run statuses for a dataset at once.
await c.users.resetDatasetPipelineRunStatus(datasetId);

​
Maintenance operations

// Replace a data item (delete → re-add → re-cognify)
await c.update("old-data-uuid", { type: "text", text: "updated content" }, "my-dataset");

// Remove all files from storage (metadata DB untouched)
await c.pruneData();

// Wipe graph, vector, metadata, and/or cache backends
await c.pruneSystem({ pruneGraph: true, pruneVector: true });

​
Legacy pipeline operations

Use these lower-level operations when you need explicit staged control over the pipeline. For most applications, prefer remember() and recall().

​
add

Ingest one or more data items into a named dataset. 
// Text
await c.add({ type: "text", text: "…" }, "my-dataset");

// File
await c.add({ type: "file", path: "/abs/path/to/doc.txt" }, "my-dataset");

// URL
await c.add({ type: "url", url: "https://example.com/article" }, "my-dataset");

// Binary (name is required for MIME detection)
await c.add({ type: "binary", bytes: buffer, name: "report.pdf" }, "my-dataset");

// Multiple items at once
await c.add([
  { type: "text", text: "First document" },
  { type: "file", path: "/abs/path/two.txt" },
], "my-dataset");

​
cognify

Extract entities and relationships into the knowledge graph. 
await c.cognify("my-dataset");

// With options
await c.cognify("my-dataset", {
  chunkSize: 512,
  summarization: true,
  triplet: true,       // also index triplet embeddings (enables TRIPLET_COMPLETION search)
});

​
addAndCognify

Ingest and extract in a single call. 
const { add, cognify } = await c.addAndCognify(
  { type: "text", text: "…" },
  "my-dataset"
);
Query the knowledge graph directly. Defaults to GRAPH_COMPLETION. 
const result = await c.search("What is the capital of France?");

// With options
const result = await c.search("summarise recent events", {
  searchType: "SUMMARIES",
  topK: 5,
  datasets: ["news"],
});
All 15 search types are supported (SCREAMING_SNAKE_CASE): GRAPH_COMPLETION, SUMMARIES, CHUNKS, RAG_COMPLETION, TRIPLET_COMPLETION, GRAPH_SUMMARY_COMPLETION, CYPHER, NATURAL_LANGUAGE, GRAPH_COMPLETION_COT, GRAPH_COMPLETION_CONTEXT_EXTENSION, FEELING_LUCKY, FEEDBACK, TEMPORAL, CODING_RULES, CHUNKS_LEXICAL.

​
memify

Index triplet embeddings from the existing knowledge graph. Enables TRIPLET_COMPLETION search. Idempotent. 
await c.memify();

​
Cloud: serve / disconnect

serve and disconnect are module-level functions (not instance methods) because they operate on global cloud state. 
import { serve, disconnect } from '@cognee/cognee-ts';

// Direct mode (no Auth0 flow; headless-friendly)
const { serviceUrl } = await serve({ url: "http://localhost:8000", apiKey: "key" });
console.log("Connected to", serviceUrl);

// Cloud mode (Auth0 device-code flow — requires a TTY)
await serve();

// Tear down
await disconnect();
await disconnect({ wipeCredentials: true }); // also removes the local credential cache

​
Visualisation

// Get the HTML string
const html = await c.visualize();

// Write to a file (returns the absolute path)
const path = await c.visualizeToFile({ destinationPath: "/tmp/graph.html" });
Requires the visualization feature compiled into the native addon.

​
Initialisation and observability

import {
  init,
  initWithThreads,
  shutdown,
  setupLogging,
  setupTelemetry,
  setupTelemetryAnalytics,
} from '@cognee/cognee-ts';

// Boot the Rust tokio runtime (required before any async op).
init();

// Alternatively boot with a fixed worker-thread count.
initWithThreads(4);

// Optional: add file logging (reads COGNEE_LOG_*, LOG_FILE_NAME, LOG_LEVEL).
setupLogging();

// Optional: enable OTLP trace export (reads OTEL_* env vars).
setupTelemetry();

// Optional: enable product-analytics emission (returns true if armed).
const armed = setupTelemetryAnalytics();

// Tear the runtime down (e.g. before process exit).
shutdown();
Each handle also exposes await c.ownerId(), returning the owner UUID used for deterministic, per-tenant ID generation. Set COGNEE_BINDING_SUPPRESS_LOGS=1 before requireing the module to skip the auto-installed stderr subscriber if your host manages the logging pipeline.

​
Environment variables

VariablePurpose
OPENAI_URLLLM API base URL (OpenAI-compatible endpoint).
OPENAI_TOKENLLM API key.
OPENAI_MODELLLM model name (default: gpt-4o-mini).
EMBEDDING_PROVIDEREmbedding provider: openai, ollama, onnx, mock.
EMBEDDING_MODELEmbedding model name.
EMBEDDING_DIMENSIONSEmbedding vector dimensions.
EMBEDDING_ENDPOINTEmbedding API base URL (falls back to OPENAI_URL).
EMBEDDING_API_KEYEmbedding API key (falls back to OPENAI_TOKEN).
MOCK_EMBEDDINGSet true to use zero-vector mock embeddings (no model download).
COGNEE_BINDING_SUPPRESS_LOGSSuppress the auto-installed stderr fmt subscriber.
COGNEE_HOST_SDKSuppress binding-armed analytics when the host is an embedding SDK.
TELEMETRY_DISABLED, ENVStandard analytics opt-outs for setupTelemetryAnalytics().
RUST_LOG, LOG_LEVELtracing-subscriber env-filter level overrides.
COGNEE_LOG_*, LOG_FILE_NAMEConsumed by setupLogging().
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_*Consumed by setupTelemetry().

​
Low-level pipeline API

The original pipeline engine API is available under the pipeline namespace: 
import { pipeline, init } from '@cognee/cognee-ts';

init();

const task = pipeline.createTask((input: pipeline.CogneeValue, ctx: pipeline.TaskContext) => {
  // process input …
  return input;
});

const p = new pipeline.Pipeline("my pipeline");
p.addTask(new pipeline.TaskInfo(task));

const [result] = await p.execute([pipeline.CogneeValue.fromString("hello")], ctx);
All pipeline symbols are also available as flat re-exports at the top level of @cognee/cognee-ts: 
import {
  Pipeline,
  TaskInfo,
  createTask,
  CogneeValue,
  TaskContext,
  RunHandle,
  CancellationHandle,
  CancellationToken,
  createCancellationPair,
  ProgressToken,
  Watcher,
  createWatcher,
  createNoopWatcher,
} from '@cognee/cognee-ts';

​
Next Steps

@cognee/cognee-ts on npm

Package page, versions, and the full README with runnable examples.

Rust SDK

The underlying cognee-rs engine and its CLI.