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

~/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.

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.

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.