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
| Package | Path | Contains |
|---|---|---|
@mastra/core |
node_modules/@mastra/core/dist/docs/ |
Agents, Workflows, Tools, Mastra instance |
@mastra/memory |
node_modules/@mastra/memory/dist/docs/ |
Memory systems, conversation history |
@mastra/rag |
node_modules/@mastra/rag/dist/docs/ |
RAG features, vector stores |
@mastra/pg |
node_modules/@mastra/pg/dist/docs/ |
PostgreSQL storage |
@mastra/libsql |
node_modules/@mastra/libsql/dist/docs/ |
LibSQL/SQLite storage |
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:
- Recommend installation: Suggest installing packages to access embedded docs
- Fall back to remote docs: See
references/remote-docs.md
Best Practices
- Check topic docs for conceptual understanding and patterns
- Search source code if docs don't answer the question
- Verify imports match what's exported in the type definitions