| 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.
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, 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
- 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).
- 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.
- 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.
- 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, 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
- 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.
