How to use the CCS Align Memory Seat agent skill

What the ccs-align skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells the agent how to perform a specific task. This one is the CCS Align seat's hourly cycle. Once an hour it confirms the local claude-mem worker is up, searches for recent needle observations (decisions, bugfixes, security alerts and similar types), fetches their details and appends new records to a seat-owned cache file at ~/.claude-mem/ccs-align/<viewerId>/middle.jsonl, skipping duplicates.

The skill can also mark observations as excluded so they are filtered out of the compiled cache, and it can walk your house, project and seat rule layers to report conflicts. Conflict types it names are SHADOW_HOUSE, DENY_ALLOW, DRIFT and CLOCK_HEADER, written to an append-only rules-report.md.

• Checks worker health before doing anything else
• Pulls observations through search, timeline and get_observations
• Writes a deduplicated middle cache with atomic replacement
• Manages exclude marks on cached observations
• Reports rules conflicts in an append-only rules-report.md

What the skill does not do

The skill does not delete history. Exclude marks only filter the compiled middle cache; the diary and SQLite database remain authoritative. It also does not enforce rules, restart the worker or write profile.md. The SKILL.md states that the rules walker only reports conflicts, and that SHADOW_HOUSE leaf patches are off by default.

Install the ccs-align skill

Download the ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder instead.

You can also upload the skill in the Claude apps: open Settings, go to Capabilities, then Skills, and add the ZIP there.

• Personal install: ~/.claude/skills/ccs-align/
• Project install: .claude/skills/ccs-align/ inside your project

Check the requirements before you run it

Every step depends on a local claude-mem worker. The skill talks to that worker on a per-user port, around 37700, and never to the cloud CMEM service. It needs Node.js, which it uses to read the port from your settings file, plus curl. The settings file at ~/.claude-mem/settings.json is optional and holds overrides.

• Local claude-mem worker running
• Node.js installed
• curl available
• Optional: ~/.claude-mem/settings.json overrides

Resolve the worker port and check health

Before any pull, the skill resolves the worker port once and reuses it. The port comes from the CLAUDE_MEM_WORKER_PORT environment variable, then the settings file, then the per-user default. Ports are per-user, so the skill does not hardcode 37777. If the health check fails, the skill aborts with a one-line miss.

Run the hourly breathing cycle

The cycle runs in a fixed order: health check, search for needle observations since the last cursor, timeline around the newest result, get_observations for the collected ids, then grab the middle cache, append new records, filter exclude marks and replace the file atomically. The skill is designed for a weekday house board and has one purpose per run.

• Health: GET /api/health or GET /health
• Search: needle observations since the cursor
• Timeline: anchored on the newest result
• get_observations: fetch full records
• Grab, append, filter exclude-marks, replace

Settings you can override

Defaults live in SettingsDefaultsManager.ts and can be overridden in ~/.claude-mem/settings.json. The master switch is CLAUDE_MEM_CCS_ALIGN_ENABLED, which defaults to true. The viewer ids default to ccs-align, and the trigger types default to decision, bugfix, security_alert and sensitive. The patch gate CLAUDE_MEM_CCS_ALIGN_PATCH_SHADOWS defaults to false, meaning report-only.

• CLAUDE_MEM_CCS_ALIGN_ENABLED (default true)
• CLAUDE_MEM_CCS_ALIGN_VIEWER_IDS (default ccs-align)
• CLAUDE_MEM_CCS_ALIGN_TRIGGER_TYPES (default decision,bugfix,security_alert,sensitive)
• CLAUDE_MEM_CCS_ALIGN_PATCH_SHADOWS (default false)