zylos-memory

Files (30)

• SKILL.md
• decisions.md · examples/
• ideas.md · examples/
• identity.md · examples/
• preferences.md · examples/
• projects.md · examples/
• references.md · examples/
• session-log.md · examples/
• state.md · examples/
• user-profile.md · examples/
• package-lock.json
• package.json
• decisions-format.md · references/
• ideas-format.md · references/
• identity-format.md · references/
• preferences-format.md · references/
• projects-format.md · references/
• references-file-format.md · references/
• session-log-format.md · references/
• state-format.md · references/
• user-profile-format.md · references/
• consolidate.js · scripts/
• daily-commit.js · scripts/
• memory-status.js · scripts/
• rotate-session.js · scripts/
• session-start-inject.js · scripts/
• shared.js · scripts/
• test-rotate-session.js · scripts/tests/
• test-shared.js · scripts/tests/
• test-utils.js · scripts/tests/

SKILL.md (first lines)

# 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` |

From zylos-ai/zylos-core, MIT.

More from zylos-ai/zylos-core