Read time: ~6 minutes · Series: Analyst advanced · Previous: Statistical analysis tools · Next: Memory division of labor
When you need a Reference
Column mapping tables, status-code dictionaries, join notes, external code lookups—this kind of content tends to be long and rarely edited as a whole, yet you have to look it up repeatedly during analysis.
| Wrong place | Problem |
|---|---|
| Dumping the whole thing into Plan / Report | Pollutes the delivery flow; the Execute state machine and review focus get diluted |
| Dumping the whole thing into Project Knowledge | The injection budget is limited; the Agent passively carries the full text every time |
| Only in a folder, with no index | The Agent doesn't know it exists, nor when it should read it |
Reference docs are the project's "mapping handbook": the body lives in a Reference file, and the Agent looks it up on demand through a short index in Project Knowledge.
What it looks like in the product
- Under Projects in the sidebar, Plan / Report and Reference docs are in separate subtrees—never mixed together
- A Reference file is plain Markdown (
ref_N.md; the olderNN_reference.mdis still supported) - Update Intro writes one
[Ref: file_name] Purpose: … When to read: …line intoproject_knowledge.md - The Agent loads the full text only when a task matches When to read; you can also name it in the conversation—"look up the mapping table"
- If the content was produced by this project conversation or analysis, explicitly ask the Agent to save it as a Project Reference. It creates the body, name, and required Intro atomically rather than pretending it came from an imported file.
For step-by-step operations, see USER_GUIDE §11.3.1.
Two paths for Update Intro
| Method | Good for |
|---|---|
| Create by agent | You already have a mapping draft; ask the Agent to propose Purpose / When to read → Apply on the approval card |
| Enter manually | You already know the index wording; fill it in directly, no approval card |
After you save a Reference for the first time, the toolbar guides you to create an Intro (you can choose "later"). A Reference with no Intro means the Agent won't proactively know when to read it.
Division of labor with Plan, Memory, and SQL
| Content | Where it goes |
|---|---|
| This analysis's time window, checkpoints | Plan |
| Stable, approvable business rules | Project / User Knowledge (see Memory division of labor) |
| Large mapping tables, full dictionaries | Reference file + [Ref: …] index |
| Runnable JOIN / WHERE | SQL tabs (see SQL-first) |
Principle: a Reference stores the lookup content itself; Knowledge stores a one-line index of when to look and what to look up.
Export, archive, Compare
- Project / Workspace export carries the Reference files and the
[Ref: …]entries in Knowledge - After you archive a Reference, the Agent won't read it proactively by default, unless you explicitly ask
- Compare view can open a Reference read-only (no annotation panel)
Hands-on (~10 minutes)
- In a test project, right-click Reference docs → New Reference
- Paste a small snippet of column mapping (5–10 lines is enough) and save
- Click Update Intro → Enter manually, and fill in Purpose and When to read (e.g., "before writing funnel SQL")
- Focus the project, ask the Agent a question that will use that mapping, and confirm it looks up the table before writing the Plan