Use workspace memory with skl

skl memory brings your workspace's notes, your private preferences, and learned skills into agent sessions. Codex and Claude Code can load memories when a session starts and read relevant skills through their native skill support.

Sign in with skl login, or use your existing Skillsync desktop login. A Skillsync admin must have enabled memory for the workspace. CLI setup connects your agent to that workspace; it does not enable learning or upload sessions.

Set up your agent

Automatic setup supports macOS and Linux. Install the agent CLI and check its version before continuing:

Refresh your workspace list and choose a workspace with memory enabled:

skl memory refresh
skl memory workspaces

For Codex:

skl memory setup --agent codex --workspace <slug>

Setup installs the Skillsync plugin with native skills and a session-start hook. In Codex, open /hooks, review and trust the Skillsync hook, then start a new session.

For Claude Code:

skl memory setup --agent claude --workspace <slug>

Setup installs and enables the Skillsync plugin. Start a new Claude Code session. Learned skills appear under workspace-qualified names such as /skillsync:my-team-code-review, and Claude can load a relevant skill when needed. claude-code is also accepted as the agent name.

Setup saves a memory default that applies across repositories. You can omit --workspace to reuse that default. With no default, setup selects the only enabled workspace or asks you to choose if there are several. It preserves unrelated agent settings and backs up changed settings. Repeating setup does not add duplicate plugins or hooks.

To preview the changes:

skl memory setup --agent codex --workspace <slug> --dry-run
skl memory setup --agent claude --workspace <slug> --dry-run

The preview refreshes the local cache but leaves agent settings, plugin files, and the default workspace unchanged. Run setup using the installed skl executable, since the plugin saves its path.

Read memories and learned skills

Check the local default and cache status, then preview the context an agent can receive:

skl memory
skl memory load

skl memory status is the explicit form of skl memory. The plain-text load keeps session context small. Read the full notes or skill catalog separately:

skl memory notes --json
skl memory skills --json

Use an ID from skl memory skills to read a learned skill:

skl memory skill <id>
skl memory skill <id> --json
skl memory skill <id> --file scripts/check.sh

Without flags, skill prints the body and supporting-file names. --json returns the entire bundle, including file contents. --file reads one exact path from that bundle and cannot be combined with --json. Reading a skill does not install it or execute its scripts.

The existing skl skills commands still manage separately installed and published skills. Workspace memory commands are not exposed as tools in skl mcp. The native memory plugins do not require an MCP connection.

Other agents can use skl memory load as plain context or --json for structured data. For a custom SessionStart integration, skl memory load --hook returns context in hookSpecificOutput.additionalContext. The agent supplies the SessionStart event and session ID on standard input.

Switch workspaces

Change the memory default for new sessions:

skl memory use <slug>

Override it for one read or agent launch:

skl memory load --workspace <slug>
SKL_MEMORY_WORKSPACE=my-team claude

Manual reads select --workspace first, then SKL_MEMORY_WORKSPACE, then the saved default. Session hooks also remember the workspace chosen for that session. Resume and compaction keep that choice unless you explicitly override it. Memories from different workspaces are never combined, and an unavailable workspace does not cause a fallback to another team.

Codex's native skill catalog is shared across local Codex sessions and contains the selected workspace's skills. Run skl memory use <slug> before starting Codex to switch that catalog. Startup memories still follow each session's workspace. Instructions already loaded into a conversation remain there.

Memory selection is independent of skl remote set-default. It does not change where sessions are shared or write repository files.

Refresh and offline use

Session hooks load cached memories without waiting for the network, then queue a quiet background refresh. They run on startup, resume, clear, and compaction; Claude Code also loads memory on fork. Ordinary cached reads request a background refresh once the cache is five minutes old.

To fetch changes immediately:

skl memory refresh --workspace <slug>

Updated memories load at the next session lifecycle event. Start a new session to pick up newly discovered native skills, especially in Codex, which reads its skill catalog before the startup hook runs. Background refresh does not rewrite an existing conversation. Updating skl also lets background refresh update the managed plugin files; you do not need to repeat setup after every CLI update.

Cached context expires after 24 hours. A missing, expired, or unavailable cache produces no hook context; manual commands report the problem. Previously cached skill bundles can work offline while their workspace snapshot remains valid. A skill that has never been downloaded needs a connection.

Remote changes take effect locally after a successful refresh. Pausing learning keeps existing memories readable. Disabling workspace memory or losing membership clears that workspace's cached content when the change is detected.

Device selections and storage

The CLI shares its memory cache with the Skillsync desktop app on the same machine:

Desktop memory and skill toggles also apply to CLI reads and the native plugins on this device. Disabled items remain browsable in the desktop app and can be switched back on. These choices stay on this device, survive refresh and sign-out, and do not change another device's selections. Already loaded agent instructions remain in existing conversations.

For a separate CLI cache, set SKL_MEMORY_CACHE_DIR to an absolute directory. This does not move the desktop cache. Agent setup honors CODEX_HOME and CLAUDE_CONFIG_DIR when you use custom agent configuration locations.

Disconnect

Remove the integration from one agent:

skl memory disconnect --agent codex
skl memory disconnect --agent claude

Disconnect removes that agent's managed Skillsync plugin and legacy Skillsync memory hooks. Codex also removes the dedicated local marketplace. Your memory cache, device selections, and unrelated plugins remain. Background refresh does not reinstall a disconnected plugin; run setup to reconnect.

Troubleshooting

If memory is missing, check your account and refresh the selected workspace:

skl whoami
skl memory refresh --workspace <slug>
skl memory load --workspace <slug>

• If memory is not recognized, run skl update and check skl memory --help.
• If no workspace is selected, run skl memory use <slug> or pass --workspace to the read command.
• If the workspace is disabled, a Skillsync admin must enable it. setup and refresh cannot enable workspace memory.
• If setup reports an unsupported agent version, update that agent and repeat setup. Claude setup also respects disableAllHooks and disableSkillShellExecution; it does not override those settings.
• If manual reads work but an agent receives nothing, check that its Skillsync plugin is enabled, review the startup hook in Codex's /hooks, and start a new session.
• If a note or skill is missing after refresh, check its device toggle in the desktop app. Restart the agent session after changing the native skill catalog.

Use load without --hook when diagnosing failures. Hook mode stays quiet so unavailable memory does not interrupt the agent.