Mastra 为智能体推出 Knowledge 共享知识库

Give your agents a knowledge base to search, read, and update.

Nov 4, 2026

5 min read

You can now give your agents company-wide context using Knowledge, a shared store of documents, policies, or decisions organized as pages. Knowledge works directly with signals, Mastra's context engineering primitive. Signals bring the right knowledge into an agent's context and keep it current while the agent runs. Agents can also search, read, and write Knowledge with tools, in the scopes they have access to.

LLMs know a lot, but they don't know everything. When agents are asked questions, they fall back on training data — which is often wrong. The real answers are usually spread across multiple systems, or in one person's head: why a feature was built a certain way, which policy applies, or what the team has already tried. Giving agents a knowledge base to read and learn from makes them more capable of understanding and answering questions that are specific to you, your business, or product.

You could already give agents context using instructions, RAG, skills, or tools that query APIs and databases, but they're usually read-only, and when information changes, each would need manual intervention to update. With Knowledge, an agent can not only read information but update it too, allowing it to learn and self-improve over time.

You can seed Knowledge with your existing documents or by using Mastra Connect on Mastra platform. Knowledge importers are coming in the next release, letting you connect data sources like Notion, Confluence, Linear, Zendesk, and Fireflies more easily.

Get started

Knowledge stores information as named markdown documents your agents can read, called pages. Each page lives in a scope, which decides which orgs, users, or conversations have read/write access.

npm install @mastra/core@latest @mastra/server@latest @mastra/libsql@latest

Create a Knowledge instance and declare its scopes with knowledgeMemoryScopes(), which sets up three scopes:

• org: shared with everyone in an org.
• resource: visible to one user.
• thread: limited to one conversation.

Setting tools: true gives agents five Knowledge tools:

• knowledge_search finds pages and notes that match a query.
• knowledge_list lists the pages in a scope.
• knowledge_read reads a page.
• knowledge_page creates or edits a page.
• knowledge_note adds a note to a page.

import { Knowledge, knowledgeMemoryScopes } from "@mastra/core/knowledge";
 
export const companyKnowledge = new Knowledge({
  id: "company-knowledge",
  scopes: { ...knowledgeMemoryScopes() },
  tools: true
});

Give the Knowledge instance to an agent using the knowledge option:

import { Agent } from "@mastra/core/agent";
import { companyKnowledge } from "../knowledge/company-knowledge";
 
export const companyAgent = new Agent({
  id: "company-agent",
  name: "Company Agent",
  instructions: /* ... */,
  model: /* ... */,
  knowledge: companyKnowledge
});

Register the agent and Knowledge on your Mastra instance. Knowledge is stored in your configured storage provider, which adds its own mastra_knowledge_* tables the first time Knowledge is used:

• mastra_knowledge_pages holds each page's name, description, and markdown body.
• mastra_knowledge_notes holds the notes added to pages.
• mastra_knowledge_mentions records the links between pages.
• mastra_knowledge_pins holds pinned pages.
• Further tables track scopes, access, and recent activity.

import { Mastra } from "@mastra/core/mastra";
import { LibSQLStore } from "@mastra/libsql";
import { KNOWLEDGE_ROUTES } from "@mastra/server/server-adapter";
 
import { companyAgent } from "./agents/company-agent";
import { companyKnowledge } from "./knowledge/company-knowledge";
 
export const mastra = new Mastra({
  agents: { companyAgent },
  knowledge: { companyKnowledge },
  storage: new LibSQLStore({ id: "mastra-storage", url: "file:./mastra.db" }),
  server: { apiRoutes: [...KNOWLEDGE_ROUTES] }
});

KNOWLEDGE_ROUTES turns on the Knowledge page in Studio, which shows every scope and page as a tree beside a graph of how the pages link. See Knowledge in Studio.

Usage

Each call passes its scopes: an org, a user (resource:), and a thread.

For a question, the agent searches and reads pages across all three scopes:

await companyAgent.generate("What's our refund window?", {
  scopes: [`org:${user.orgId}`, `resource:${user.id}`, `thread:${threadId}`]
});

For updates, the agent writes the page to the scope that matches the request. "Save that for the team" writes to org:

await companyAgent.generate("Our refund window is 30 days. Save that for the team.", {
  scopes: [`org:${user.orgId}`, `resource:${user.id}`, `thread:${threadId}`]
});

Seeding Knowledge

Agents can only answer from what's in Knowledge, so you'll usually want content in place before they start. There are a number of ways to seed Knowledge with your existing content, covered in Load your content.

For more information and full configuration options, see:

• Knowledge overview
• Scopes and access
• Agents and tools
• Load your content
• Knowledge in Studio
• Knowledge class reference

Knowledge is in alpha. Its API may change between releases.

Paul Scanlon sits between Developer Education and Product Marketing at Mastra. Previously, he was a Technical Product Marketing Manager at Neon and worked in Developer Relations at Gatsby, where he created educational content and developer experiences.

More on Memory