Embedded Docs Reference

Look up API signatures from embedded docs in node_modules/@mastra/*/dist/docs/ - these match the installed version.

Use this FIRST when Mastra packages are installed locally. Embedded docs are always accurate for the installed version.

Why use embedded docs

• Version accuracy: Embedded docs match the exact installed version
• No network required: All docs are local in node_modules/
• Mastra evolves quickly: APIs change rapidly, embedded docs stay in sync
• TypeScript definitions: Includes JSDoc, type signatures, and examples
• Training data may be outdated: Claude's knowledge cutoff may not reflect latest APIs

Documentation structure

node_modules/@mastra/core/dist/docs/
├── SKILL.md # Package overview, exports
├── assets/
│   └── SOURCE_MAP.json # Export -> file mappings
└── references/ # Individual topic docs

Lookup process

1. Check if packages are installed

ls node_modules/@mastra/

If you see packages like core, memory, rag, etc., proceed with embedded docs lookup.

2. Look through topic docs

Use grep to find relevant docs in references/:

grep -r "Agent" node_modules/@mastra/core/dist/docs/references

Naming convention

Documents are typically formatted as <category>-<topic>.md where category is one of: "docs", "reference", "guides", "models".

Optional: Check source code for type definitions / additional details

Look at the SOURCE_MAP.json to find the file path for the export:

cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'

Returns: { "Agent": { "types": "dist/agent/agent.d.ts", ... } }

Read the type definition for exact constructor parameters, types, and JSDoc:

cat node_modules/@mastra/core/dist/agent/agent.d.ts

Common packages

Quick commands reference

# List installed @mastra packages
ls node_modules/@mastra/

# List available topic documentation
ls node_modules/@mastra/core/dist/docs/references/

# Find specific export in SOURCE_MAP
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ExportName"'

# Read type definition from path
cat node_modules/@mastra/core/dist/[path-from-source-map]

# View package overview
cat node_modules/@mastra/core/dist/docs/SKILL.md

When embedded docs are not available

If packages aren't installed or dist/docs/ doesn't exist:

1. Recommend installation: Suggest installing packages to access embedded docs
2. Fall back to remote docs: See references/remote-docs.md

Best Practices

1. Check topic docs for conceptual understanding and patterns
2. Search source code if docs don't answer the question
3. Verify imports match what's exported in the type definitions