/zylos-memory

name: zylos-memory
description: >-
  Core memory system. Maintains persistent memory across sessions via tiered
  markdown files following the Inside Out model. Handles Memory Sync (processing
  conversations into structured memory), session rotation, consolidation, and
  context-aware state saving. Must be launched via a runtime-appropriate
  background subagent mechanism — do not invoke with the Skill tool.
disable-model-invocation: true
user-invocable: false

Memory System

Maintains persistent memory across sessions via tiered markdown files. This skill must be run via a runtime-appropriate background subagent mechanism. For Claude, use the Task tool (`subagent_type: general-purpose`, `model: sonnet`, `run_in_background: true`). For Codex, prefer the session's native subagent tools `spawn_agent`/`wait_agent` (host session tools — they do not appear in `codex --help`) with a Codex-supported model; do not hardcode `sonnet`.

Architecture

~/zylos/memory/
├── identity.md              # Bot soul + digital assets (always loaded)
├── state.md                 # Active working state (always loaded)
├── references.md            # Pointers to config files (always loaded)
├── users/
│   └── <id>/profile.md      # Per-user preferences
├── reference/
│   ├── decisions.md         # Key decisions with rationale
│   ├── projects.md          # Active/planned projects
│   ├── preferences.md       # Shared team preferences
│   └── ideas.md             # Uncommitted plans and ideas
├── sessions/
│   ├── current.md           # Today's session log
│   └── YYYY-MM-DD.md        # Past session logs
└── archive/                 # Cold storage

Memory Sync

Priority

Memory Sync is the highest-priority internal maintenance task. When triggered, run it before handling queued user messages.

Memory Sync is maintenance-only. A sync subagent must not reply through C4, process user-facing tasks, modify business/project repositories, install or upgrade components, restart services, or apply runtime changes outside the sync flow below.

Trigger Paths

1. Session init: if C4 unsummarized count is over threshold, launch memory sync. 2. Scheduled context check: if context usage is high, launch memory sync.

Both launch a background subagent using the current runtime's supported subagent mechanism with this file's Sync Flow as the prompt.

Codex Background Execution

In Codex, use the session's native subagent tools: `spawn_agent` to launch the sync subagent and `wait_agent` to collect its result. These are host session tools — they do not appear in `codex --help`. For a single long-running command, an async exec session (`exec_command` + `write_stdin`) also works. Bare `nohup ... &` does NOT survive the tool-call boundary and must never be used for sync. Never use PM2 for sync — do not create PM2 services, run `pm2 start ... codex exec ...`, or fork an extra `codex exec` sidecar: one-shot sync processes leave stopped services piling up in the PM2 list. If the session exposes no native background-agent capability, run the sync inline as a last resort and note that in the handoff/status.

Before starting Memory Sync, check for existing in-flight sync work: if the runtime exposes background-agent status, check it for a running sync subagent and do not start another sync writer while one is in flight.

Sync Flow

1. Rotate session log if needed: `node ~/zylos/.claude/skills/zylos-memory/scripts/rotate-session.js` 2. Fetch unsummarized conversations from C4: `node ~/zylos/.claude/skills/comm-bridge/scripts/c4-fetch.js --unsummarized` If output says "No unsummarized conversations.", skip to step 5 (still save current state). Otherwise, note the `end_id` from the `[Unsummarized Range]` line. 3. Read memory files (`identity.md`, `state.md`, `references.md`, user profiles, `reference/*`, `sessions/current.md`). 4. Extract and classify updates from conversations into the correct files. 5. Write memory updates (always — even without new conversations, update `state.md` and `sessions/current.md` with current context). 6. Audit `references.md` against its content rules (`references/references-file-format.md`): relocate rule-violating entries to their routed destination (`reference/decisions.md`, `archive/`, or a pointer to the config file) instead of leaving or appending them. If the file exceeds the 8KB warn threshold (`memory-status.js` reports WARN), trim until it is back under. 7. Audit `state.md` against its content rules (`references/state-format.md`): relocate rule-violating content to its routed destination (`reference/projects.md`, `reference/decisions.md`, `archive/`, or a pointer to the on-demand file that already holds it) instead of leaving or appending it. If the file exceeds the 10KB warn threshold (`memory-status.js` reports WARN), trim until it is back under. 8. Create checkpoint (only if conversations were fetched in step 2): `node ~/zylos/.claude/skills/comm-bridge/scripts/c4-checkpoint.js create <end_id> --summary "SUMMARY"` 9. Confirm completion.

Classification Rules

• `reference/decisions.md`: committed choices that close alternatives.
• `reference/projects.md`: scoped work efforts with status.
• `reference/preferences.md`: standing team-wide preferences.
• `reference/ideas.md`: uncommitted proposals.
• `users/<id>/profile.md`: user-specific preferences.
• `state.md`: active focus, pending items, and blockers only, per the

content rules in `references/state-format.md`; completed-task narrative, decisions, and run history are routed out, never accumulated.

• `references.md`: pointers and stable identifiers only, per the content

rules in `references/references-file-format.md`; never duplicate config values, never accumulate narrative history.

File Formats and Examples

Each memory file type has a format definition in `references/` and a worked example in `examples/`:

| File | Format | Example | |---