Core concepts

The first Epismo concept is the difference between reusable information and active work. Reusable information is stored as packs. Active work is stored as tracks. This split keeps agent context easy to retrieve and keeps execution state easy for people and automation to update.

Packs vs tracks

If you ask "will this be useful again later?" and the answer is yes, create a pack. If you ask "does this move toward completion?" and the answer is yes, create a track.

Packs

Packs are reusable artifacts. Epismo supports two pack types.

A workflow pack describes how to do something. Examples include a release review process, bug triage flow, or skill creation checklist. Each step can have title, content, dueDate, dependsOn, parentId, and assignee. Workflow step assignees are human or agent IDs. Workspace user IDs are not valid workflow-step assignees.

A context pack describes what someone or an agent should know. Examples include monorepo layout, authentication background, or a customer research summary. For large context packs, read the outline first and then fetch only the blocks the agent needs.

Tracks

Tracks represent active work. Epismo supports two track types.

Tasks are concrete units of work. They can have assignees, due dates, dependencies, parent tasks, and linked goals. Goals represent outcomes. progress is an integer from 0 to 100.

For planning many tasks at once, use bulk apply. Non-UUID draft IDs create new records and can be referenced by other drafts in the same request through dependsOn, parentId, and goalId. The server resolves those labels to real UUIDs.

Aliases

Aliases are human-readable references to packs.

Aliases point to packs only. Tracks are referenced by UUID or by a URL containing a UUID. Use aliases in prompts, runbooks, and CI scripts when a stable human-readable reference is easier than a raw UUID.

Workspace, projects, and personal space

A workspace is the organization boundary. Without a workspace, data lives in personal space. Projects are containers inside a workspace and are commonly used as private sharing scopes.

The CLI resolves execution context in this order:

1. If EPISMO_TOKEN embeds a workspace, use that workspace.
2. Otherwise use the saved default from epismo workspace use <workspace-id>.
3. If no workspace is selected, use personal space.

The API accepts a workspaceId query parameter on supported endpoints. MCP derives workspace context from the bearer token.

Scope and sharing

Private records live in personal space or workspace projects. Create and update calls use scope.

{ "scope": { "type": "personal" } }

{ "scope": { "type": "projects", "ids": ["project-id"] } }

Search calls use scopes, because a search can include multiple private locations.

{
	"scopes": [{ "type": "personal" }, { "type": "projects", "ids": ["project-id"] }]
}

Use sharedWith when a private record should also be visible to specific user IDs or emails. On update, omitting scope or sharedWith preserves the current access settings.

Visibility and credits

Packs have visibility. private follows scope and sharing settings; public makes the pack discoverable. category can be empty or one of productivity, learning, programming, design, marketing, operations, or life.

Credits are quota for valuable agent-context retrieval and processing. Agent usage, pack search, track search, and pack reads consume credits. Fetch full or selected pack content only when detail is needed; checking search results or outlines first keeps later agent context smaller. Credit-gated operations may return 402 Payment Required when balance is insufficient.

Common choices