# Memory Skill > Use when starting a session or when Codex needs machine, repo, or cross-repo context from the curated memory repo managed by `memory-skill`. - Skill: `wncfht/memory-skill` (Agent Skill, multi-file: 22 files) - Install (CLI): `npx skillmds@latest add wncfht/memory-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/wncfht/memory-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: WncFht (https://skillmd.com/u/wncfht) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/wncfht/memory-skill --- # Memory Skill You maintain curated, reusable agent memory in an active memory repo managed by `memory-skill`. This is not per-repo scratch space, not a chronological log, and not a place to dump temporary state. ## Runtime Contract Always use the skill-owned entrypoints: - `~/.codex/skills/memory-skill/scripts/init-memory.sh` - `~/.codex/skills/memory-skill/scripts/sync-memory.sh` - `~/.codex/skills/memory-skill/scripts/resolve-machine.sh` Do not improvise your own sync sequence inside the memory repo. The active memory root resolves in this order: 1. `--memory-root ` 2. `MEMORY_ROOT` 3. `~/.codex/state/memory-skill/state.json` 4. default `~/.codex/memory` ## What Lives In Memory Memory lives inside the resolved memory root. - `core.md`: shared defaults - `rules.md`: curation policy - `machines/index.md`: machine routing - `machines//summary.md`: machine-specific context - `machines//repo-paths.md`: local path to repo-id routing - `repos/index.md`: canonical repo identities - `repos//summary.md`: repo entrypoint - `repos//*.md`: repo detail packs - `topics/.md`: cross-repo topic packs Index files route lookups. Packs hold curated knowledge. ## Session Bootstrap At session start, before the first user-facing response: 1. Before relying on any memory file, run `~/.codex/skills/memory-skill/scripts/sync-memory.sh pre-read`. 2. If that fails because no valid memory repo exists yet, initialize or adopt one with `~/.codex/skills/memory-skill/scripts/init-memory.sh --memory-root `. 3. If sync fails for any other reason, stop and surface the reason. 4. Read the resolved repo's `core.md`. 5. Resolve the current machine through `machines/index.md`. Prefer `~/.codex/skills/memory-skill/scripts/resolve-machine.sh` instead of shelling out to `hostname`; some runtimes do not provide that command. 6. Read the matching machine summary. 7. If the current working directory maps to a known repo, read that repo's `summary.md`. Do not announce that memory was read. Just apply it. ## Read Rounds Treat memory access as read rounds. - Run `pre-read` once at the start of a round. - Read as many relevant files as needed from that synchronized snapshot. - Do not rerun `pre-read` for every single file. Start a new read round when: - you return to memory after doing other work - the task shifts to a different memory question - you need memory again after publishing a write batch ## Progressive Disclosure Start with the minimum useful set: - `core.md` - current machine summary - current repo summary, if resolved Only expand when the task truly needs it: - read a topic pack for a tool, platform, or recurring failure mode - read a repo detail pack when the repo summary points to it - prefer opening one additional file at a time Never bulk-read the whole memory tree just because it exists. ## Machine Resolution Resolve the machine first through `machines/index.md`. Preferred resolver: - `~/.codex/skills/memory-skill/scripts/resolve-machine.sh` That entrypoint prints the normalized hostname key used for routing. Use `--json` when you also need the raw hostname and the detection source. Do not assume `hostname` exists on PATH; if you need a shell fallback, prefer `uname -n`. After resolving the machine id: - read `machines//summary.md` - use `machines//repo-paths.md` to map the current working directory to a repo id when needed If the machine has no entry yet, continue without machine memory until you have durable facts worth recording. ## Repo Resolution Repo memory lives only under `repos/` in the memory repo. Resolve the current repo in this order: 1. exact or longest-parent-prefix path matches from the current machine's `repo-paths.md` 2. if still unresolved and you are inside a git repo, use git metadata to match an existing entry in `repos/index.md` 3. if still unknown, continue without repo memory until you have enough stable information to create a pack Never write repo memory back into the target repo itself. ## Write Batches Treat memory updates as write batches. - A write batch may touch multiple memory files that belong to the same logical update. - After editing any memory file in that batch, run `~/.codex/skills/memory-skill/scripts/sync-memory.sh post-write` once. - Do not leave local memory edits unpublished between batches. Use the default commit message unless the update clearly deserves a more specific `-m`. ## What Is Worth Writing Back Write only durable, reusable information: - stable user preferences - machine-specific environment facts - repo workflows that will recur - cross-repo operational knowledge Do not write: - one-off timelines - verbose logs - speculative notes without future reuse value - transient working state that belongs in the current task, not memory ## Failure Handling If sync fails: - do not auto-stash changes - do not silently skip sync - do not read known-stale memory as if it were current Surface the failure clearly and stop, unless the only problem is that no valid memory repo exists yet and you can initialize or adopt one safely. ## Network And Auth Note The runtime is proxy-aware and can help with GitHub sync on difficult networks. - It may use `MEMORY_SYNC_SOCKS_PROXY`, `ALL_PROXY`, or `all_proxy`. - It may auto-detect common local SOCKS endpoints. - For GitHub remotes, it can use token-backed HTTPS fallback via `MEMORY_SYNC_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `GH_TOKEN`. Those capabilities help the runtime sync successfully, but your instruction as the agent does not change: if sync still fails, stop and surface the reason. ## Practical Rule Treat `memory-skill` as a live memory system optimized for future execution speed and reliability. Keep it small, trustworthy, and publishable.