Entities
An entity is a tracked ticker or company stored as a markdown file in entities/. It is the agent's durable memory for everything it has learned about that name.
Every ticker or company the desk is actively researching lives as a plain markdown file in entities/ — a persistent, human-readable record that the agent reads before acting on any issue related to that name.
Why files for research memory
An AI agent has no memory between sessions. Entity files solve this: before the agent works an issue that involves a ticker, it reads the entity file and loads everything the desk already knows — prior thesis, key risks, price levels, notes from past trades.
Because the file is plain markdown, you can read it, edit it, and diff it in any editor. The agent's updates are visible in the workspace version history alongside your own edits.
The thesis body is free-form markdown. You write what is useful to you and the agent: fundamental notes, technicals, catalyst calendar, position rationale. The agent appends or updates sections as it completes research tasks.
Entity file format
---
symbol: AAPL
name: Apple Inc.
tags: [tech, large-cap, consumer]
sector: Technology
updated: 2026-07-05
---
## Thesis
Apple's services segment now contributes ~40 % of gross profit with
margins above 70 %. Hardware refresh cycles remain the key demand
variable; the installed base of ~2.2 B active devices provides a
large recurring-revenue floor.
## Key risks
- Regulatory pressure on App Store economics (EU DMA compliance).
- China revenue (~17 % of total) exposed to trade-policy shifts.
- Premium valuation leaves little margin for earnings misses.
## Price levels
| Level | Note |
|-------|------|
| 180 | Prior breakdown, now support |
| 215 | 52-week high resistance |
## Recent notes
2026-06-30: Q3 earnings beat on EPS; revenue inline. Services up 14 % YoY.
Agent added catalyst: WWDC product reveal scheduled 2026-09-10.Frontmatter fields
The YAML frontmatter block is the structured part of the entity. Qoc reads symbol to match entities to orders, issues, and inbox items. tags and sector are used when the agent searches for related entities across the workspace.
updated is written automatically whenever the agent modifies the file, so you can sort by recency. You can add any extra frontmatter fields you find useful — Qoc ignores unknown keys.
Standard frontmatter fields
| Field | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Primary ticker symbol, e.g. AAPL. Used to link the entity to orders and issues. |
name | string | Recommended | Human-readable company or instrument name. |
tags | string[] | No | Free-form labels for grouping and filtering. |
sector | string | No | Broad sector classification. |
updated | date (ISO 8601) | Auto | Last-modified date, written by the agent on each update. |
How the agent uses entity files
- 1
Issue is opened for a ticker
You or the agent creates an issue referencing a symbol (e.g.
symbol: AAPLin the issue frontmatter). - 2
Agent loads the entity
Before starting work, the agent reads
entities/AAPL.mdin full. This primes it with the existing thesis, risks, and price levels — no separate context injection required. - 3
Agent works the issue
Research, data queries, and reasoning happen as part of the issue run. The agent may call the Data Hub for fresh quotes or fundamentals.
- 4
Agent updates the entity
Findings are written back to
entities/AAPL.md— new sections appended, stale notes revised,updatedbumped. The change is recorded in version history.
Create entities manually
You do not need an agent to create an entity. Copy the frontmatter template, fill in symbol and name, and save it to entities/<SYMBOL>.md. The agent will pick it up on the next run.
Running qoc run 'research NVDA' will create the entity file automatically if it does not already exist.
One file per instrument
Keep one entity file per primary symbol. For related instruments (options, ETFs) add cross-reference notes in the thesis rather than creating separate files, unless the instrument has its own distinct research body.