Skills & MCP Server Registry

MemoryLayer ships two workspace-scoped registries alongside its memory store:

Skills (/v1/skills) — Anthropic-style “skill packs” (a folder containing SKILL.md plus arbitrary files) that an LLM agent can list, fetch, and execute against.
MCP Servers (/v1/mcp-servers) — declarative entries describing local or remote MCP servers an agent should connect to (the same shape as .mcp.json / Claude Code’s ~/.claude.json).

Both registries share a common design: they are stored server-side, exposed through MCP tools (skills_* and mcp_servers_*) so an LLM can discover and use them, surfaced via a CLI (memorylayer skills, memorylayer mcp), and resolved through a 4-tier scope precedence so the same name can mean different things in different contexts.

Why a Server-Side Registry?

Putting skills and MCP servers behind the MemoryLayer API gives you:

Persistence — the agent’s set of available skills and MCP servers travels with the workspace, not the local filesystem.
Scoping — the same skill name (code-review) can resolve to a user-private version, a project-shared version, a personal cross-project version, or a global plugin-provided version depending on who is asking and from where.
Two-way sync with disk — memorylayer skills sync / memorylayer mcp sync mirror server records to a local directory or .mcp.json file, with source_mode tracking whether a record came from server (created via API), mirrored (pushed from disk), or filesystem (loaded ambient from disk on startup).
Shadowing — precedence is deterministic; higher-priority tiers shadow lower-priority ones unless you opt into include_shadowed.

The 4-Tier Scope Model

Both registries use a 4-tier precedence model, but with slightly different semantics that match how the two concepts are actually used.

Skills: `user > workspace > tenant > global`

Tier	When it wins	Where it lives
user	A skill is bound to `user_id` and the requesting user matches	`(workspace_id=<current>, user_id=<caller>)`
workspace	A skill is bound to the current workspace, no user pin	`(workspace_id=<current>, user_id=null)`
tenant	A skill lives in another workspace under the same tenant (visible only when enterprise RBAC explicitly exposes it)	`(workspace_id=<other>, user_id=null)`
global	A skill ships from a plugin or platform-wide source	`(workspace_id="_global", user_id=null)`

In OSS, the tenant tier is effectively unused (every caller sees their own workspace plus _global). In Enterprise, the resolution service can be subclassed to inject cross-workspace visibility through RBAC without changing the precedence logic.

MCP Servers: `local > project > user > global`

Tier	When it wins	Where it lives
LOCAL	User-private, current workspace	`(workspace_id=<current>, user_id=<caller>)`
PROJECT	Shared across the workspace (the equivalent of a committed `.mcp.json`)	`(workspace_id=<current>, user_id=null)`
USER	User-private, cross-workspace (the equivalent of a personal `~/.claude.json`)	`(workspace_id="_global_user", user_id=<caller>)`
GLOBAL	Tenant / plugin-wide entry shared with everyone	`(workspace_id="_global", user_id=null)`

The MCP-server tier names mirror the way Claude Code, Cursor, and similar tools think about MCP config (project file vs. user config), so memorylayer mcp migrate-from-local can ingest an existing .mcp.json into the LOCAL or PROJECT tier without surprises.

Tie-Breaking: source_mode

Within a tier, two records with the same name are tie-broken by source_mode, then by updated_at (most recent wins):

`source_mode`	Origin
`server` (highest)	Created via the REST API directly
`mirrored`	Pushed up from a local directory or file via `sync` / `push`
`filesystem` (lowest)	Discovered ambient on disk at startup; not persisted to the DB

This means a deliberately curated server-side record always beats a filesystem-mirrored copy of the same name — so an operator can override a wayward local file by POSTing a replacement.

Walkthrough: Resolving a Skill Named `code-review`

Suppose the workspace ws-platform has three skills called code-review:

Record	workspace_id	user_id	source_mode	updated_at
A	`_global`	`null`	`mirrored`	yesterday
B	`ws-platform`	`null`	`mirrored`	last week
C	`ws-platform`	`alice`	`server`	this morning

When Alice calls skills_get("code-review") from ws-platform:

The resolver lists scopes in precedence order: (ws-platform, alice), (ws-platform), (_global).
Candidate set: C (matches scope 0), B (scope 1), A (scope 2).
Tier rank picks the lowest — C wins (user tier).
If C did not exist, B would win (workspace). If B did not exist either, A would win (global).
If multiple records lived in the same winning tier, source_mode would break the tie (server > mirrored > filesystem), then updated_at desc.

When Bob (different user) makes the same call from ws-platform, he never sees C (it’s pinned to Alice). He gets B.

The same logic applies to MCP servers with the LOCAL > PROJECT > USER > GLOBAL ordering.

CLI: `memorylayer skills`

The CLI mirrors the registry shape with familiar push/pull/sync semantics:

# List skills visible to the caller (with shadowing applied)
memorylayer skills list --workspace ws-platform

# Show shadowed variants too
memorylayer skills list --workspace ws-platform --show-shadowed

# Upload a local skill directory
memorylayer skills push ./skills/code-review --workspace ws-platform --scope workspace

# Pull one back to disk
memorylayer skills pull code-review --workspace ws-platform --out ./local/code-review

# Materialize the entire workspace skill set to a directory
memorylayer skills materialize ./local/skills --workspace ws-platform

# Two-way sync between a local directory and the workspace
memorylayer skills sync ./local/skills --workspace ws-platform --auto-push --auto-pull

# Watch a directory and auto-push on change
memorylayer skills watch ./local/skills --workspace ws-platform

# Bulk-import skills from ~/.claude/skills/ or a project skills dir
memorylayer skills migrate-from-local ~/.claude/skills --scope user --workspace ws-platform

The --scope flag controls which tier a push lands in:

user — LOCAL (binds to the caller’s user_id)
workspace — PROJECT (workspace-shared, no user pin)
global — GLOBAL (writes into the _global workspace; typically restricted)

CLI: `memorylayer mcp`

The MCP-server CLI mirrors the same pattern:

# List MCP server entries (winners only)
memorylayer mcp list --workspace ws-platform

# Push a single .mcp.json (one or many server entries inside)
memorylayer mcp push ./.mcp.json --workspace ws-platform

# Pull the workspace's entries back out
memorylayer mcp pull --workspace ws-platform --output ./.mcp.json

# Include decrypted env values in the pull
memorylayer mcp pull --workspace ws-platform --reveal-secrets --output ./.mcp.json

# Two-way sync
memorylayer mcp sync ./.mcp.json --workspace ws-platform

# Materialize to a target directory (writes .mcp.json and/or Claude Code config)
memorylayer mcp materialize ./output --workspace ws-platform --write-claude

# Watch and auto-push
memorylayer mcp watch ./.mcp.json --workspace ws-platform

# Migrate an existing local Claude Code MCP config into the workspace
memorylayer mcp migrate-from-local --workspace ws-platform --scope project

mcp materialize --write-claude renders the resolved (precedence-winning) entries into Claude Code’s expected ~/.claude.json shape, which makes it easy to keep agent tooling in sync with the server.

MCP Tools an LLM Sees

When an LLM is connected to MemoryLayer through the MCP server, the same registries are reachable as tools (default cc profile):

Tool	Purpose
`skills_list`	List skills visible in the current workspace
`skills_get`	Get a single skill’s metadata (precedence-resolved)
`skills_get_file`	Fetch one file from a skill bundle
`skills_search`	Semantic search across skill names + descriptions

The full profile adds:

Tool	Purpose
`skills_save`	Create or update a skill record from the LLM side
`mcp_servers_list`	List MCP server registry entries
`mcp_servers_get`	Get a single entry
`mcp_servers_save`	Create or update an entry
`mcp_servers_delete`	Remove an entry
`mcp_servers_import`	Import a JSON blob (Claude Code or `.mcp.json` shape)

See MCP Server for the full tool reference.

Authentication & Authorization

In the OSS server, default authentication treats every caller as a single open user; both registries are effectively flat by workspace_id. In Enterprise:

Each request carries an authenticated user_id and tenant_id, which is what makes the LOCAL / user-pinned tiers meaningful.
visible_scopes_for(ctx) can be overridden to filter cross-workspace tenant visibility through RBAC.
Encrypted args on MCP server records use the platform key-management service rather than the OSS default.

The precedence + resolution logic is identical across editions; Enterprise plugs in the identity and visibility surface.

CLI Reference — complete memorylayer skills and memorylayer mcp subcommand reference
MCP Server — MCP tool catalog for skills + MCP-server registry
Workspaces — workspace isolation model

Skills & MCP Server Registry

Why a Server-Side Registry?

The 4-Tier Scope Model

Skills: user > workspace > tenant > global

MCP Servers: local > project > user > global

Tie-Breaking: source_mode

Walkthrough: Resolving a Skill Named code-review

CLI: memorylayer skills

CLI: memorylayer mcp