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, use the current session's available background-agent capability 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.

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. 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"
7. 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 and pending tasks.
• references.md: pointers only; do not duplicate .env values.

File Formats and Examples

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

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).
• memory-status.js: quick health summary.

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/.
• state.md is the strictest — must stay under 4KB.

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.