13. Advanced (2): Agents / Skills / Memory

omicOS's capabilities are built from three extensible systems: Agents, Skills, and Memory (long-term memory). These are primarily managed centrally in the cloud and synced down to your machine, but users on lab tier and above can also add to or override them inside their own workspace. This chapter covers how that machinery works.

13.1 Subscription Tiers

omicOS layers its features by subscription tier, compared internally with a rank value:

Unknown or empty tier names always map to 0 (community). Two common thresholds:

• rank ≥ 2 (pro): can open the Agent2Agent endpoint (see Chapter 9).
• rank ≥ 3 (lab): can use "workspace-local extensions" — the local overrides covered in 13.2 / 13.3 below.

Subscription state is carried by a subscription token (a JWT, stored at ~/.omicos/plan_token.jwt). A background scheduler renews it automatically once less than 25% of its validity remains. If renewal fails and the token expires, you're downgraded to community, and paid features stay locked until you log in again.

13.2 Agent Templates

An Agent is an assistant with a specific role, toolset, and system prompt. The template format is YAML frontmatter + a Markdown body:

---
id: my_lab_qc
name: My Lab QC
description: Lab-specific QC agent
tier: lab
toolsets:
  - python_interpreter
  - file_manager
  - omicverse_lookup
skills:
  - qc_basic
---

You are a QC specialist...
(the rest of this is the full system prompt body)

Common fields: id, name, description, toolsets, instructions, tier, skills, category, use_when, example_prompts.

Where Agents Are Loaded From

The base roster is taken from the first usable directory, in this priority order:

1. The directory specified by OMICOS_TEMPLATES_DIR
2. <workspace>/config/agents/ (if it exists)
3. The cloud cache ~/.omicos/cloud-agents/agents/ — this is the path real users go through
4. The fallback <workspace>/.omicos/ (usually empty — in that case it degrades to a placeholder default agent, so a configuration problem is exposed rather than silently swallowed)

On top of that, lab tier and above users can layer a workspace override: <workspace>/agents/ (or the legacy location <workspace>/.omicos/agents/).

Rules for How Local Overrides Take Effect

• New id → appended to the end of the roster (adds a new agent).
• Same id → the local .md overrides the cloud version, handy for iterating on a prompt temporarily.
• For community / plus / pro users, even a file that exists is silently ignored — the cloud catalog is the only source.
• After editing a file, you must restart omicos serve / omicos cli for it to take effect; the web app's "refresh" only re-pulls cloud content, it doesn't re-read local files.

An Agent's Skill Allowlist Semantics

An agent's skills field controls which skills it can see:

• Empty / omitted = all skills visible (backward compatible — this does not hide everything).
• ["*"] = explicit wildcard, all visible.
• A named list = only the listed skills are visible.
• Workspace-local skills always bypass the allowlist and are always visible.

13.3 Skills

A Skill is a reusable unit of capability. The root directories where skills are discovered, in priority order (earlier wins on a name collision):

1. The directories listed in OMICOS_SKILL_ROOTS (colon- / semicolon-separated)
2. The cloud cache ~/.omicos/cloud-skills/skills/
3. <workspace>/skills/ (lab+)
4. <workspace>/.omicos/skills/ (lab+, legacy location)

Directories that don't exist are silently skipped.

Two sources that used to exist have since been removed: the skill directory bundled with the kernel environment's omicverse_skills Python package, and the cross-project user-level ~/.omicos/skills/. Skills now come from exactly two sources — the cloud catalog, or the workspace. ~/.omicos only holds the cloud cache now.

Cloud sync does hash comparison and cleanup, and carries the subscription token for tier filtering. OMICOS_SKILLS_OFFLINE=1 disables sync and uses the local cache only.

13.4 Memory (Long-Term Memory)

Memory lets an agent remember things across conversations. It's just a set of plain .md files under ~/.omicos/memory/ (no frontmatter needed; the title is taken from the first non-empty line), synced to the cloud by process token.

ls ~/.omicos/memory

Expected output:

project-conventions.md    rnaseq-pipeline-notes.md

• Tools: memory__list / memory__view / memory__create / memory__edit / memory__delete.
• Slug naming rules: [a-zA-Z0-9_-], length 1–64; body capped at 64 KiB.
• Write policy: local write first, cloud sync best-effort. OMICOS_MEMORY_OFFLINE=1 disables cloud sync.
• The storage location can be changed with OMICOS_MEMORY_CACHE_DIR — note that's where the memory files themselves live, not a separate copy.

13.5 Sync Cadence

Cloud content changes push proactively, so editing an agent / skill in the admin panel doesn't require restarting a running omicos to pick it up.

13.6 Workspace-Extension Gating, Summarized

If you're on community / plus / pro and find that a local agent you dropped in doesn't take effect, that's expected — workspace-local extensions require lab tier.