1# Embedded Docs Reference
2 
3Look up API signatures from embedded docs in `node_modules/@mastra/*/dist/docs/` - these match the installed version.
4 
5**Use this FIRST** when Mastra packages are installed locally. Embedded docs are always accurate for the installed version.
6 
7## Why use embedded docs
8 
9- **Version accuracy**: Embedded docs match the exact installed version
10- **No network required**: All docs are local in `node_modules/`
11- **Mastra evolves quickly**: APIs change rapidly, embedded docs stay in sync
12- **TypeScript definitions**: Includes JSDoc, type signatures, and examples
13- **Training data may be outdated**: Claude's knowledge cutoff may not reflect latest APIs
14 
15## Documentation structure
16 
17```
18node_modules/@mastra/core/dist/docs/
19├── SKILL.md # Package overview, exports
20├── assets/
21│   └── SOURCE_MAP.json # Export -> file mappings
22└── references/ # Individual topic docs
23```
24 
25## Lookup process
26 
27### 1. Check if packages are installed
28 
29```bash
30ls node_modules/@mastra/
31```
32 
33If you see packages like `core`, `memory`, `rag`, etc., proceed with embedded docs lookup.
34 
35### 2. Look through topic docs
36 
37Use `grep` to find relevant docs in `references/`:
38 
39```bash
40grep -r "Agent" node_modules/@mastra/core/dist/docs/references
41```
42 
43### Naming convention
44 
45Documents are typically formatted as `<category>-<topic>.md` where category is one of: `"docs", "reference", "guides", "models"`.
46 
47### Optional: Check source code for type definitions / additional details
48 
49Look at the `SOURCE_MAP.json` to find the file path for the export:
50 
51```bash
52cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
53```
54 
55Returns: `{ "Agent": { "types": "dist/agent/agent.d.ts", ... } }`
56 
57Read the type definition for exact constructor parameters, types, and JSDoc:
58 
59```bash
60cat node_modules/@mastra/core/dist/agent/agent.d.ts
61```
62 
63## Common packages
64 
65| Package          | Path                                     | Contains                                  |
66| ---------------- | ---------------------------------------- | ----------------------------------------- |
67| `@mastra/core`   | `node_modules/@mastra/core/dist/docs/`   | Agents, Workflows, Tools, Mastra instance  |
68| `@mastra/memory` | `node_modules/@mastra/memory/dist/docs/` | Memory systems, conversation history      |
69| `@mastra/rag`    | `node_modules/@mastra/rag/dist/docs/`    | RAG features, vector stores               |
70| `@mastra/pg`     | `node_modules/@mastra/pg/dist/docs/`     | PostgreSQL storage                        |
71| `@mastra/libsql` | `node_modules/@mastra/libsql/dist/docs/` | LibSQL/SQLite storage                     |
72 
73## Quick commands reference
74 
75```bash
76# List installed @mastra packages
77ls node_modules/@mastra/
78 
79# List available topic documentation
80ls node_modules/@mastra/core/dist/docs/references/
81 
82# Find specific export in SOURCE_MAP
83cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ExportName"'
84 
85# Read type definition from path
86cat node_modules/@mastra/core/dist/[path-from-source-map]
87 
88# View package overview
89cat node_modules/@mastra/core/dist/docs/SKILL.md
90```
91 
92## When embedded docs are not available
93 
94If packages aren't installed or `dist/docs/` doesn't exist:
95 
961. **Recommend installation**: Suggest installing packages to access embedded docs
972. **Fall back to remote docs**: See `references/remote-docs.md`
98 
99## Best Practices
100 
1011. **Check topic docs** for conceptual understanding and patterns
1022. **Search source code** if docs don't answer the question
1033. **Verify imports** match what's exported in the type definitions
104