zylos-memory

# 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 ```text ~/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 | |------|--------|---------| | `identity.md` | `references/identity-format.md` | `examples/identity.md` | | `state.md` | `references/state-format.md` | `examples/state.md` | | `references.md` | `references/references-file-format.md` | `examples/references.md` | | `users/<id>/profile.md` | `references/user-profile-format.md` | `examples/user-profile.md` | | `reference/decisions.md` | `references/decisions-format.md` | `examples/decisions.md` | | `reference/projects.md` | `references/projects-format.md` | `examples/projects.md` | | `reference/preferences.md` | `references/preferences-format.md` | `examples/preferences.md` | | `reference/ideas.md` | `references/ideas-format.md` | `examples/ideas.md` | | `sessions/current.md` | `references/session-log-format.md` | `examples/session-log.md` | ## Supporting Scripts - `session-start-inject.js`: prints core memory context blocks for hooks. - `rotate-session.js`: rotates `sessions/current.md` at day boundary. - `daily-commit.js`: local git snapshot for `memory/` if changed. - `consolidate.js`: JSON consolidation report (sizes, age, budget checks). Use for deliberate memory maintenance, or for scheduler-triggered consolidation when such a task is configured. Review the report and apply the Consolidation Review rules below. - `memory-status.js`: quick health summary. Use when you need a fast manual check of core file sizes and budget status. If it reports `OVER`, run `consolidate.js` and perform the needed cleanup. C4 scripts used by sync flow (provided by comm-bridge skill): - `c4-fetch.js --unsummarized`: fetch unsummarized conversations and range. - `c4-checkpoint.js create <end_id> --summary "..."`: create sync checkpoint. ## Consolidation Review The weekly consolidation task runs `consolidate.js` and outputs a JSON report. Review the report and apply these rules: ### Core File Budgets - Files over 100% budget: summarize and trim older entries. Move historical content to `reference/` or `archive/`. - `identity.md`, `state.md`, and `references.md` must stay under 16KB. - Apply file-specific cleanup: - `identity.md`: keep only stable identity traits, principles, durable collaboration style, and digital asset references. Move operational state and one-off lessons elsewhere. - `state.md`: keep active focus, pending tasks, and recent completions. Move completed or historical detail to `sessions/current.md` or `reference/`. Apply the content rules in `references/state-format.md`; the sync-time audit (Sync Flow step 7) should keep it under the 10KB warn threshold. - `references.md`: keep pointers and lookup facts only. Move prose, project history, and detailed decisions to `reference/`. Apply the content rules in `references/references-file-format.md`; the sync-time audit (Sync Flow step 6) should keep it under the 8KB warn threshold. ### Session Logs - Logs in `archiveCandidatesOlderThan30Days`: move from `sessions/` to `archive/`. ### Reference Files (`reference/*.md`) These files have no size cap. Maintenance is at the entry level. Freshness is reported by file mtime (Phase 1 limitation): - **active** (< 7 days): no action. - **aging** (7–30 days): no action. - **fading** (30–90 days): open the file. Review entries by their dates and status fields. Update or confirm still-relevant entries; move obsolete entries (superseded/completed/abandoned/dropped) to `archive/`. - **stale** (> 90 days): same as fading, but prioritize review. Entries that are clearly still critical may remain. **Immunity:** Entries with importance 1-2 (defined in entry metadata) are immune to automatic fading suggestions. They may still be reviewed but should not be archived based on age alone. ### User Profiles - Profiles over ~1KB: summarize older notes. ### General Rules 1. Never delete — always move to `archive/`. Content is recoverable from `archive/` or git history. 2. Log consolidation actions in `sessions/current.md`. ## Best Practices 1. Keep `state.md` lean (tight context budget). 2. Prefer updates over duplication. 3. Use explicit dates/timestamps for entries. 4. Archive instead of deleting historical data. 5. Route user data to user profiles. 6. Keep configuration values in config files; use `references.md` as an index.