Symbol

Symbol uses a consistent shorthand syntax for referencing capsules, types, and projects. These references work inside capsule content, AI conversations, and MCP tool calls.

Capsules

Capsules are referenced using the format @type-slug/refId, where type-slug is the URL-friendly version of the type name and refId is the capsule's sequential number within that type.

Format: @type-slug/refId

Examples:

@docker/3 - capsule #3 in the Docker type
@decisions/12 - capsule #12 in the Decisions type
@code-snippets/7 - capsule #7 in the Code Snippets type

When you are working within a specific type in the editor, the # typeahead helps you find a capsule in that same type — type a number to match its ref id (e.g. #3), or type text to search the type's capsule titles:

#3 - capsule 3 in the current type context

Whichever way you find it, the editor inserts the canonical @type-slug/3 form when you accept a suggestion, so a # token is never stored in capsule content or parsed as a reference on its own — it is purely an editor search-and-insert convenience, and the stored capsule reference is always the numeric @type-slug/refId.

Where to use it: The # typeahead is for the editor only. To link capsules inside stored content, use the canonical @type-slug/refId form, which is also what MCP tool calls expect via the ref parameter of get_capsule_by_ref. In AI chat and MCP, a text #slug (e.g. #wifi-project) means a Project instead — see below.

Cross-Referencing

You can reference one capsule from another's content. This lets you build connected knowledge without duplicating information:

"I solved a similar problem in @docker/1, but this case was different because..."

Types

Types are referenced using the format @type:slug, a plain slug, or a plain name. All three resolve to the same type.

Formats:

@type:code-snippets
code-snippets
Code Snippets

The slug is auto-generated from the type name: lowercased, with spaces and special characters replaced by hyphens.

Where to use it: In MCP tool calls via the type_name parameter (e.g. list_capsules, create_capsule).

Projects

Projects are referenced using the format @project:slug, the text form #slug, or a plain name.

Formats:

@project:wifi-project
#wifi-project
WiFi Project

The slug follows the same rules as type slugs: lowercased, spaces and special characters replaced by hyphens.

Where to use it: In MCP tool calls via the project_name parameter (e.g. get_project_context, create_capsule, update_capsule). The text form #slug is an AI-chat / MCP convention: when you write #wifi-project in a conversation, the assistant loads that project's context via get_project_context.

Note: In AI chat and MCP, the text form #slug (e.g. #wifi-project) is a project reference. Do not confuse it with the numeric form #N (e.g. #3), which the model treats as an editor-only current-type capsule shorthand (the editor rewrites it to @type-slug/N on insert), not a project. In that AI-chat / MCP context the two are disambiguated by shape: a number after # is the capsule shorthand; text after # is a project. (In the editor itself, the # typeahead also accepts title text to search for a capsule, but it always inserts the canonical @type-slug/N — it never produces a stored #slug token.)

Note: First-class parsing and resolution of the #slug → project form (alongside @type: and @project:) from message text is tracked in issue #599. Today the #slug project form is honored by the AI chat / MCP layer per the assistant's reference-syntax contract, rather than by the web content parser.

Organizations

Organizations cannot be referenced directly in conversations or tool calls. They are an organizational layer that controls who has access to capsules and projects. Context is always loaded through capsules and projects, not through organization membership.

Summary

Resource	Token	Shape	Context	Resolves to
Capsule (cross-type)	`@type-slug/refId`	—	content, chat, MCP	capsule `refId` in that type
Capsule (current-type)	`#N` (editor typeahead)	number or title search	editor only	finds capsule `N` in the current type and inserts `@type-slug/N`; never stored or parsed as a `#` token
Project	`#slug`	text only	AI chat / MCP	a project → `get_project_context`
Type	`@type:slug`; plain slug; plain name	—	chat, MCP	the type
Project	`@project:slug`; plain name	—	chat, MCP	the project

How Slugs Are Generated

Slugs are derived automatically from names using the following rules:

Convert to lowercase
Replace any sequence of non-alphanumeric characters with a hyphen
Strip leading and trailing hyphens

For example: "My Docker Setup" becomes my-docker-setup.

You can also set a custom slug when creating a type or project.

Referencing Resources