Entities & Tracking

As Alice researches, she accumulates things worth keeping an eye on — a ticker she's watching, a theme that ties several names together. Entities are how she records them: a small, durable, cross-workspace index she curates herself, surfaced to you in the Tracked tab.

It's the read counterpart to the Inbox. The Inbox is "here's a finished thing"; Tracked is "here's the running list of what I'm following, and every note that touches it."

What an entity is

A single global store (data/entities/entities.jsonl) shared across all workspaces. Each entity is deliberately minimal:

Field	Meaning
`name`	Short, kebab-case, no spaces. The case-insensitive key and the `[[name]]` link target
`type`	`asset` (a tradable instrument) or `topic` (a theme that groups assets)
`description`	One line that disambiguates the short name
`createdAt`	Stamped once, preserved across updates

Self-describing names

A bare ticker like ccj means nothing to a non-trader (or to the model weeks later), so an asset name is kind-prefixed:

stock-vst · stock-ccj — equities
crypto-btc — cryptocurrencies
etf-smh — ETFs

A topic is just a short phrase: ai-data-center-power. The name is exactly what appears in [[links]] and the Tracked sidebar, so it's built to read on its own.

The two tools

Entities are managed through two identity-bound tools — reached from inside a workspace via the alice-workspace track CLI (track add / track search), and exposed to external MCP clients as entity_upsert / entity_search at /mcp/:wsId. The tool names are used below:

entity_upsert({ name, type, description }) — create or update. Idempotent on name (case-insensitive), so re-tracking something updates it rather than duplicating. Returns the ready-to-paste link, e.g. { link: "[[stock-vst]]" }.
entity_search({ query? }) — substring search over names + descriptions (omit query to list all). Read fresh on every call, so a long-running workspace sees entities other sessions just created.

The intended loop: search first to reuse an existing name, then upsert, then link. That keeps the index from fragmenting into [[vst]] and [[stock-vst]] for the same thing.

[[name]] backlinks

Once an entity exists, Alice references it in her notes with a [[name]] wikilink:

Vistra ([[stock-vst]]) is the cleanest read on [[ai-data-center-power]] —
PJM capacity auction cleared 9× higher, and its nuclear fleet is uncontracted
upside into 2026.

OpenAlice scans every workspace's markdown for these links (skipping the CLAUDE.md / AGENTS.md / README.md scaffold files so injected persona text can't manufacture phantom links). The result is a backlink index: open [[stock-vst]] a week later and the Tracked tab gathers every note across every workspace that mentions it — the whole story, without re-reading the files.

Issues share the [[name]] namespace too. A [[name]] resolves across both kinds of node — tracked entities and issue titles — so a note can link an issue exactly like it links a stock or topic. When a link matches more than one target, a small disambiguation picker lets you choose. Because an issue title is a global object, the same title claimed by two workspaces is flagged as a duplicate-name clash on the Issue Board — a warning only; nothing is rejected, and access stays workspace-precise.

The Tracked tab

A surface in the Web UI, peer to the Inbox:

Sidebar — every tracked entity, newest first, with a type icon and a backlink count.
Detail — the entity's description plus each backlink (workspace + file). Click a backlink to jump straight into the workspace note that mentions it.

Backed by GET /api/entities and GET /api/entities/:name; the page polls so newly tracked names appear without a reload.

Adoption is taught, not forced. The chat workspace template's instruction file tells the agent how and when to track — when it surfaces something you'll want to follow over time — and to entity_search before creating, so the habit is organic rather than a hard schema rule.

Next Steps

Workspaces — See how workspace files become durable research context.
Issues — Link tracked entities to self-describing work.
Inbox — Follow pushed reports that mention tracked names.
Equity Research — Track names that emerge from research.