Knowledge Lists

What is a Knowledge List?

A Knowledge List is a typed, persistent table scoped to your workspace. Think of it like a lightweight database table that every workflow can read from and write to. Unlike a one-off CSV attached to a single run, a list lives between runs — a lead scoring workflow can read prospects, score each row, and write the results back with a new status. The next workflow picks up where it left off.

Each list has a stable list key (e.g. investors) that workflows reference. The key never changes even if you rename the list, so workflows don't break when you update metadata.

Creating a List

Three paths to create a list, all ending up with the same schema + rows model:

CSV Upload

Go to Knowledge > Lists in the dashboard and click Import CSV. AgentLed detects column types automatically and maps them to field types. You can review and adjust the schema before committing.

Dashboard

Click New List, give it a name and a key, then define columns manually. Add rows one by one or in bulk from the row editor.

MCP / API

create_knowledge_list({
  key: "investors",
  name: "Investor Contacts",
  fields: [
    { name: "name",   type: "text",   required: true },
    { name: "firm",   type: "text" },
    { name: "email",  type: "email" },
    { name: "stage",  type: "select", options: ["Pre-Seed","Seed","Series A","Growth"] },
    { name: "score",  type: "number" }
  ],
  syncToKg: true
})

create_knowledge_list is idempotent — calling it again with the same key returns the existing list with a warning instead of creating a duplicate.

Field Types

Reading Rows in a Workflow

Use the Read List step (or get_knowledge_rows via MCP) to load rows into a workflow. You can filter by status to process only a subset.

// Read List step config
{
  listKey: "investors",
  status: "pending",    // filter to rows with this status
  limit: 100
}
// Returns: { listEntries: [...rows], count: 87 }

For text blobs (long-form notes, documents, embeddings), use get_knowledge_text with a key to retrieve unstructured content stored alongside the list.

get_knowledge_text({ key: "icp-definition" })
// Returns the raw text blob stored under that key

Writing Rows in a Workflow

Use the Add Rows step to upsert results back into a list. Rows are matched by identity fields; new rows are created, existing rows are updated.

// Add Rows step config
{
  listKey: "prospects",
  rows: "{{steps.score.results}}",
  status: "scored"
}
// Returns: { addedCount: 43, rowIds: [...], listCreated: false }

Up to 500 rows per call. For larger batches, paginate with multiple steps or use the batching pattern.

Row Status

Every row carries a status field that workflows use to checkpoint progress. This lets you build incremental pipelines that pick up only where they left off.

Knowledge Graph Sync

Enable Sync to KG on a list to promote rows to entity nodes in the Knowledge Graph. Once synced, rows become first-class graph nodes that AI steps can search and traverse alongside other entities, scoring edges, and execution history.

Sync is fire-and-forget — the Add Rows step completes immediately and the KG update happens in the background. If the Knowledge Graph is unavailable, rows are still saved; they'll be synced on the next successful connection.

When KG sync is on, you configure an entity config: which field is the display name, and which fields uniquely identify the entity. These are used for deduplication when the same company or contact appears in multiple lists.

Managing Lists

Add or Remove Fields

You can add new fields or remove existing ones from Knowledge > Lists > Edit Schema. Existing rows retain old values; removed fields are dropped from future reads but the underlying data is preserved until you run a cleanup.

Delete a List

Deleting a list removes the schema and all rows permanently. There is no versioning or soft-delete — make sure no live workflow depends on the list before deleting. Workflows that reference a deleted list key will fail at the Read List step.

Limits

• •Up to 500 rows per upsert call. Paginate larger datasets across multiple steps.
• •No hard per-list row limit, but lists above ~10,000 rows should use status filtering to avoid loading the full table in a single step.
• •Field count: no hard limit, but keep schemas focused — wide schemas slow down row reads.

Example Use Cases

Next Steps

• KG API — Query list rows as graph nodes using kg_search and kg_traverse
• Business Memory — Workspace-level shared context (ICP, rubrics) stored alongside lists
• Scoring & Feedback — Write scores back to lists and improve them over time
• Knowledge Graph Overview — How list entities fit into the broader KG architecture