| 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, 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
- Session init: if C4 unsummarized count is over threshold, launch memory sync.
- 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, when the current session has a native background-agent capability,
Memory Sync must use that capability directly. Do not create PM2 services,
run pm2 start ... codex exec ..., or fork an extra codex exec sidecar.
PM2 is only a fallback when no native background-agent capability is
available; if used, explicitly record the reason in the handoff/status.
Before starting Memory Sync, check for existing memory-sync-* PM2 entries.
If one is running, do not start another sync writer. If only stopped entries
exist, report them as historical records and do not create a replacement.
Sync Flow
- Rotate session log if needed:
node ~/zylos/.claude/skills/zylos-memory/scripts/rotate-session.js
- 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.
- Read memory files (
identity.md, state.md, references.md, user profiles, reference/*, sessions/current.md).
- Extract and classify updates from conversations into the correct files.
- Write memory updates (always — even without new conversations,
update
state.md and sessions/current.md with current context).
- 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"
- 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/:
| 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/.references.md: keep pointers and lookup facts only. Move prose,
project history, and detailed decisions to reference/.
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
- Never delete — always move to
archive/. Content is recoverable
from archive/ or git history.
- Log consolidation actions in
sessions/current.md.
Best Practices
- Keep
state.md lean (tight context budget).
- Prefer updates over duplication.
- Use explicit dates/timestamps for entries.
- Archive instead of deleting historical data.
- Route user data to user profiles.
- Keep configuration values in config files; use
references.md as an index.
