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

omicOS capabilities are built from three extensible systems: Agents, Skills, and Memory (long-term memory). Most of these are managed centrally by the cloud-side omicos-admin and synced down to your machine, but users on the lab tier and above can add their own 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, represented internally by a rank value:

Unknown or empty tier names always map to 0 (community). rank ≥ 3 (lab) is the dividing line for whether you can use "workspace-local extensions."

Subscription state is carried by a plan token (a subscription JWT stored at ~/.omicos/plan_token.jwt). The background scheduler renews the token automatically once less than 25% of its validity remains. If renewal fails and the token expires, you are downgraded to the community tier, paid features are locked, and they stay locked until you sign 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: 课题组定制的 QC agent
tier: lab
toolsets:
  - python_interpreter
  - file_manager
  - omicverse_lookup
skills:
  - qc_basic
---

You are a QC specialist...
（以下是完整的 system prompt 正文）

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

The three loading sources for an agent

When omicos loads agents, it merges three sources in priority order:

1. Workspace-local overrides in <workspace>/agents/ (lab+ only)
2. Cloud cache in ~/.omicos/cloud-agents/agents/ (synced from omicos-admin)
3. The fallback inside the workspace's .omicos

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 lab users who want to iterate on a prompt temporarily without touching admin).
• For community / plus / pro users, even a file that exists is silently ignored—admin-curated content is the only source.
• After editing a file you must restart omicos serve / omicos cli for it to take effect; the web client's "refresh agents" only refreshes the cloud manifest and does not re-read local files.

Skill allowlist semantics for an agent

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

• Empty / omitted = all skills visible (backward compatible—it 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 omicos discovers skills, in priority order:

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+)

Cloud sync comes from the omicos-admin manifest, performing hash comparison and garbage collection, and carries the plan token for tier filtering. OMICOS_SKILLS_OFFLINE disables sync and uses the local cache only.

13.4 Memory (long-term memory)

Memory lets an assistant remember things across conversations. It is stored as plain .md files under ~/.omicos/memory/ (no frontmatter; the title is taken from the first non-empty line) and synced to the server by process_token.

• 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 disables cloud sync.

13.5 Sync interval

The catalog sync interval for agents / skills / models is controlled by OMICOS_CATALOG_SYNC_SECS, defaulting to 600 seconds. Values below 30 seconds are not clamped to 30—they are discarded and fall back to the 600-second default.

13.6 Workspace-extension gating, in summary

If you are a community/plus/pro user and find that a local agent you dropped in isn't taking effect, that's expected—upgrade to lab to use workspace-local extensions.