@kevin0181/memoc 1.4.2 → 1.4.5

package/package.json

@@ -1,37 +1,39 @@
-{
-  "name": "@kevin0181/memoc",
-  "version": "1.4.2",
-  "description": "Give AI agents a memory. Scaffolds session-to-session context for Claude Code, Codex, Cursor, and more.",
-  "keywords": [
-    "ai",
-    "agent",
-    "memory",
-    "context",
-    "scaffold",
-    "claude",
-    "codex",
-    "llm"
-  ],
-  "author": "kevin0181",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/neneee0181/memoc.git"
-  },
-  "homepage": "https://github.com/neneee0181/memoc#readme",
-  "bugs": {
-    "url": "https://github.com/neneee0181/memoc/issues"
-  },
-  "bin": {
-    "memoc": "bin/cli.js"
-  },
-  "scripts": {
-    "test": "node --test"
-  },
-  "files": [
-    "bin/"
-  ],
-  "engines": {
-    "node": ">=16"
-  }
-}
+{
+  "name": "@kevin0181/memoc",
+  "version": "1.4.5",
+  "description": "Give AI agents a memory. Scaffolds session-to-session context for Claude Code, Codex, Cursor, and more.",
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "context",
+    "scaffold",
+    "claude",
+    "codex",
+    "llm"
+  ],
+  "author": "kevin0181",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neneee0181/memoc.git"
+  },
+  "homepage": "https://github.com/neneee0181/memoc#readme",
+  "bugs": {
+    "url": "https://github.com/neneee0181/memoc/issues"
+  },
+  "bin": {
+    "memoc": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin/",
+    "plugins/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/plugins/memoc/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "memoc",
+  "description": "Agent memory skills for memoc: scaffold, maintain, query, and compact markdown-based project memory.",
+  "author": {
+    "name": "kevin0181",
+    "url": "https://github.com/neneee0181"
+  }
+}

package/plugins/memoc/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "memoc",
+  "version": "1.4.5",
+  "description": "Agent memory skills for memoc — scaffold, maintain, and query session-to-session AI memory.",
+  "author": {
+    "name": "kevin0181",
+    "url": "https://github.com/neneee0181"
+  },
+  "homepage": "https://github.com/neneee0181/memoc",
+  "repository": "https://github.com/neneee0181/memoc",
+  "license": "MIT",
+  "keywords": ["memory", "agent", "ai", "context", "scaffold"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "memoc",
+    "shortDescription": "Session-to-session memory for AI agents.",
+    "longDescription": "memoc scaffolds a structured memory system into any codebase so AI agents can pick up exactly where they left off. Skills cover init, upgrade, compress, search, work logs, notes, and health checks.",
+    "developerName": "kevin0181",
+    "category": "Productivity",
+    "capabilities": ["Write", "Read"],
+    "websiteURL": "https://github.com/neneee0181/memoc",
+    "privacyPolicyURL": "https://github.com/neneee0181/memoc/blob/main/README.md",
+    "termsOfServiceURL": "https://github.com/neneee0181/memoc/blob/main/LICENSE",
+    "defaultPrompt": ["Use memoc skills to manage agent memory."],
+    "brandColor": "#4F46E5"
+  }
+}

package/plugins/memoc/skills/memoc/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: memoc
+description: >
+  Follow the full memoc operating protocol for a project: read memory first,
+  preserve durable context, use the project-local memoc runtime when available,
+  and record important work before handoff. Trigger: /memoc, "use memoc",
+  "follow memoc memory", "resume with memoc".
+---
+
+Use this skill as the default operating mode for a repository that has, or should have, memoc memory.
+
+## Operating protocol
+
+1. Start by checking whether memoc is installed in the current project.
+   - Prefer `.memoc/` plus project-local launchers.
+   - If absent and the user wants memory set up, run `/memoc-init` or `memoc init`.
+
+2. Read memory before acting.
+   - First run `memoc summary` when available.
+   - Then open only the memory files that are relevant to the task, such as `.memoc/session-summary.md`, `.memoc/02-current-project-state.md`, `.memoc/04-handoff.md`, `.memoc/wiki/`, or worklog entries.
+
+3. Keep memory durable and concise.
+   - Record decisions, user preferences, active constraints, and handoff notes.
+   - Do not store transient command output, obvious code facts, secrets, credentials, or noisy chat history.
+   - Prefer wiki notes for reusable knowledge and worklog entries for session activity.
+
+4. Use the right memoc command when useful.
+   - `memoc search "<query>"` before broad filesystem search when looking for prior context.
+   - `memoc work "<title>"` after meaningful work so future agents know what changed.
+   - `memoc note "<title>"` for durable knowledge that should survive sessions.
+   - `memoc doctor` when memory looks stale, malformed, too large, or inconsistent.
+   - `memoc compress` when memory is noisy or oversized.
+   - `memoc upgrade` after updating memoc itself or when runtime/wrapper files are stale.
+
+5. Preserve user work.
+   - Treat memory files as collaborative project state.
+   - Do not overwrite user-authored notes unless the command is designed to preserve and merge them.
+   - Before final handoff, mention any memory updates made and any remaining health issues.
+
+## Binary resolution (all skills use this order)
+
+1. Windows: `.\.memoc\bin\memoc.cmd`
+2. macOS/Linux: `.memoc/bin/memoc`
+3. Fallback: `npx @kevin0181/memoc@latest`
+
+## Related focused skills
+
+- `/memoc-init` initializes memoc in the current project.
+- `/memoc-upgrade` refreshes runtime files while preserving memory.
+- `/memoc-search` searches memory and agent docs.
+- `/memoc-work` records session activity.
+- `/memoc-note` saves durable knowledge.
+- `/memoc-doctor` checks memory health.
+- `/memoc-compress` compacts noisy memory.

package/plugins/memoc/skills/memoc-code/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: memoc-code
+description: >
+  Coding guardrails adapted from multica-ai/andrej-karpathy-skills. Use when
+  writing, fixing, reviewing, or refactoring code: think before coding, keep the
+  solution simple, edit surgically, and verify against concrete success criteria.
+  Trigger: /memoc-code, "use memoc coding guardrails", "code carefully".
+license: MIT
+---
+
+Use this skill to reduce common AI coding mistakes: guessing, overbuilding,
+unrelated edits, and stopping before the result is verified.
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+## Protocol
+
+1. Think before coding.
+   - State assumptions when the request is ambiguous.
+   - Ask when uncertainty would change the implementation.
+   - Surface tradeoffs instead of silently choosing.
+
+2. Keep it simple.
+   - Build only what was requested.
+   - Avoid speculative configuration, future-proofing, and one-use abstractions.
+   - If the solution feels large for the problem, reduce it.
+
+3. Edit surgically.
+   - Touch only files and lines needed for the task.
+   - Match the local style.
+   - Do not clean up unrelated code; mention it separately.
+   - Remove only dead code created by your own changes.
+
+4. Make success verifiable.
+   - Turn the request into observable checks.
+   - For bugs, prefer a reproducing test or concrete repro before the fix.
+   - For refactors, verify behavior before and after.
+   - Keep looping until the check passes or the blocker is clear.
+
+## Shortcuts
+
+- `/memoc-think` for ambiguity, assumptions, and tradeoffs.
+- `/memoc-simple` for reducing overbuilt designs.
+- `/memoc-scope` for tight, minimal diffs.
+- `/memoc-goal` for tests, repros, and verification loops.

package/plugins/memoc/skills/memoc-compress/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: memoc-compress
+description: >
+  Compact memoc memory files and refresh generated indexes. Removes redundancy,
+  trims verbose entries, rebuilds activity and wiki indexes.
+  Trigger: /memoc-compress, "compress memoc", "compact memory", "clean up memoc files",
+  "memoc files too big".
+---
+
+Run `memoc compress` in the current working directory.
+
+## Steps
+
+1. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd compress`
+   - macOS/Linux: `.memoc/bin/memoc compress`
+   - Fallback: `npx @kevin0181/memoc@latest compress`
+
+2. **Run compress** and capture output.
+
+3. **Report**:
+   - Which files were compacted
+   - Token/size reduction achieved (if reported)
+   - Any indexes rebuilt
+
+## When to use
+
+- `memoc tokens` shows large files (⚠ warnings)
+- After extended sessions with many entries
+- Before important commits to keep memory lean
+- session-summary.md exceeds ~800B

package/plugins/memoc/skills/memoc-doctor/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: memoc-doctor
+description: >
+  Check common memoc health issues: broken links, missing files, malformed frontmatter,
+  oversized summaries, stale content. Diagnose and suggest fixes.
+  Trigger: /memoc-doctor, "memoc health check", "check memoc", "diagnose memoc",
+  "is memoc healthy", "memoc issues".
+---
+
+Run `memoc doctor` in the current working directory.
+
+## Steps
+
+1. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd doctor`
+   - macOS/Linux: `.memoc/bin/memoc doctor`
+   - Fallback: `npx @kevin0181/memoc@latest doctor`
+
+2. **Display output** verbatim.
+
+3. **For each issue found**, offer to fix it:
+   - Oversized summary → `/memoc-trim`
+   - Broken wiki links → `/memoc-lint`
+   - Large files → `/memoc-compress`
+   - Missing wrapper → run `memoc upgrade`
+
+4. **If no issues**: confirm memoc is healthy.
+
+## What doctor checks
+
+- `.memoc/` directory exists and is valid
+- session-summary.md size is within budget
+- Agent entry files (CLAUDE.md etc.) are present
+- Project-local wrapper scripts are functional
+- Frontmatter validity on memory files

package/plugins/memoc/skills/memoc-goal/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: memoc-goal
+description: >
+  Goal-driven execution for coding tasks. Use when work needs clear success
+  criteria, tests, reproduction steps, or a verification loop. Trigger:
+  /memoc-goal.
+license: MIT
+---
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+Turn the task into a verifiable goal:
+
+- Define what success looks like before making broad edits.
+- For a bug, create or describe the failing repro first, then fix it.
+- For validation, test invalid and valid inputs.
+- For refactors, verify behavior before and after.
+- For multi-step work, pair each step with a check.
+- Keep iterating until checks pass, or report the exact blocker.

package/plugins/memoc/skills/memoc-init/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: memoc-init
+description: >
+  Initialize memoc in the current project. Scaffolds agent memory files, detects stack,
+  generates CLAUDE.md/AGENTS.md and .memoc/ directory.
+  Trigger: /memoc-init, "initialize memoc", "setup memoc memory", "scaffold memoc",
+  "install memoc in this project".
+---
+
+Run `memoc init` in the current working directory.
+
+## Steps
+
+1. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd init`
+   - macOS/Linux: `.memoc/bin/memoc init`
+   - Fallback: `npx @kevin0181/memoc@latest init`
+
+2. **Run init** and capture output.
+
+3. **Report** what was created:
+   - Which agent entry files were generated (CLAUDE.md, AGENTS.md, GEMINI.md, etc.)
+   - Whether `.memoc/` directory was created or updated
+   - Any stack detection results
+
+4. **If already initialized**: init auto-updates managed sections. Report what changed.
+
+5. **If Node.js missing**: stop and tell user to install Node.js LTS with npm first.
+
+## After init
+
+Remind user to source the PATH helper so the project-local wrapper is available:
+- PowerShell: `. .\.memoc\env.ps1`
+- bash/zsh: `. .memoc/env.sh`

package/plugins/memoc/skills/memoc-note/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: memoc-note
+description: >
+  Save a durable topic/query-result scaffold for knowledge that should persist across sessions.
+  Creates a structured note in the memoc wiki for later reference by agents.
+  Trigger: /memoc-note, "save a note", "create memoc note", "remember this topic",
+  "add to knowledge base", "save research result".
+---
+
+Run `memoc note "<title>"` in the current working directory.
+
+## Steps
+
+1. **Get title** from user's message or args. If not provided, ask: "Topic or title for this note?"
+
+2. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd note "<title>"`
+   - macOS/Linux: `.memoc/bin/memoc note "<title>"`
+   - Fallback: `npx @kevin0181/memoc@latest note "<title>"`
+
+3. **Run command** and report the created file path.
+
+4. **Help populate** the note with content from the current conversation if relevant:
+   - Key findings or decisions
+   - Code patterns or solutions
+   - External references
+   - Related topics
+
+## Use cases
+
+- Saving research findings for future sessions
+- Documenting architectural decisions not obvious from code
+- Recording API quirks, gotchas, or workarounds
+- Building a queryable knowledge base with `memoc search`

package/plugins/memoc/skills/memoc-scope/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: memoc-scope
+description: >
+  Surgical-change discipline. Use when editing an existing codebase and the
+  important thing is to avoid drive-by refactors, unrelated formatting churn, or
+  accidental behavior changes. Trigger: /memoc-scope.
+license: MIT
+---
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+Keep the diff tight:
+
+- Touch only what the user request requires.
+- Match existing style even when you would design it differently.
+- Do not rewrite adjacent comments, formatting, or APIs for taste.
+- Do not delete unrelated dead code; mention it separately.
+- Remove imports, variables, and helpers only when your own change made them unused.
+- Every changed line should trace back to the requested outcome.

package/plugins/memoc/skills/memoc-search/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: memoc-search
+description: >
+  Search memory files and agent docs for a query. Finds relevant notes, decisions,
+  worklogs, and wiki entries. Supports --snippets for line-level matches.
+  Trigger: /memoc-search, "search memoc", "search memory", "find in notes",
+  "search agent docs", "look up in memory".
+---
+
+Run `memoc search "<query>"` in the current working directory.
+
+## Steps
+
+1. **Get query** from user's message or args. Required — if not provided, ask.
+
+2. **Choose mode**:
+   - Default: file names with match counts sorted by relevance + recency
+   - With `--snippets` flag: show matching lines with context
+
+3. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd search "<query>" [flags]`
+   - macOS/Linux: `.memoc/bin/memoc search "<query>" [flags]`
+   - Fallback: `npx @kevin0181/memoc@latest search "<query>" [flags]`
+
+4. **Display results** and offer to open the most relevant file.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--snippets` | Show matching lines instead of file list |
+| `--limit N` | Limit results (default 12) |
+| `--all` | Show all matches without limit |
+
+## Scope
+
+Searches `.memoc/` directory and agent entry files (CLAUDE.md, AGENTS.md, etc.).
+For project source files, use `/memoc-grep` instead.

package/plugins/memoc/skills/memoc-simple/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: memoc-simple
+description: >
+  Simplicity-first coding. Use when implementing a feature or fix that risks
+  overengineering, speculative abstraction, or unnecessary configurability.
+  Trigger: /memoc-simple.
+license: MIT
+---
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+Prefer the smallest solution that genuinely solves the request:
+
+- Do not add features the user did not ask for.
+- Do not add abstractions for single-use code.
+- Do not add flexibility or configuration just in case.
+- Do not add error handling for impossible or irrelevant cases.
+- If the implementation feels too large, simplify before continuing.
+- Use existing local patterns before introducing new ones.

package/plugins/memoc/skills/memoc-think/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: memoc-think
+description: >
+  Think before coding. Use when a coding task has ambiguity, hidden assumptions,
+  multiple possible interpretations, or tradeoffs that should be surfaced before
+  editing. Trigger: /memoc-think.
+license: MIT
+---
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+Before implementing:
+
+- Name the assumptions you are making.
+- If two interpretations are plausible, present them instead of silently choosing.
+- Ask a concise question when the answer would materially change the code.
+- Push back when a simpler or safer approach fits the request better.
+- Stop and clarify when you are confused; do not code through confusion.

package/plugins/memoc/skills/memoc-upgrade/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: memoc-upgrade
+description: >
+  Upgrade memoc runtime and wrappers in the current project without deleting existing memory.
+  Refreshes managed sections based on current project state.
+  Trigger: /memoc-upgrade, "upgrade memoc", "update memoc", "refresh memoc runtime".
+---
+
+Run `memoc upgrade` in the current working directory.
+
+## Steps
+
+1. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd upgrade`
+   - macOS/Linux: `.memoc/bin/memoc upgrade`
+   - Fallback: `npx @kevin0181/memoc@latest upgrade`
+
+2. **Run upgrade** and capture output.
+
+3. **Report**:
+   - Which files were refreshed vs preserved
+   - New memoc version vs previous version (if shown)
+   - Any managed sections that were updated
+
+## Key behavior
+
+Upgrade preserves all manually-written memory content. Only memoc-managed sections (marked with `<!-- memoc:managed -->` or equivalent) are updated. User-written content is never overwritten.

package/plugins/memoc/skills/memoc-work/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: memoc-work
+description: >
+  Create a conflict-light actor worklog entry for the current work session.
+  Records what was done, by whom, and when — for shared repos with multiple actors.
+  Trigger: /memoc-work, "log work", "create worklog", "record what I did",
+  "add work entry", "memoc log session".
+---
+
+Run `memoc work "<title>"` in the current working directory.
+
+## Steps
+
+1. **Get title** from user's message or args. If not provided, ask: "Brief title for this work entry?"
+
+2. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd work "<title>"`
+   - macOS/Linux: `.memoc/bin/memoc work "<title>"`
+   - Fallback: `npx @kevin0181/memoc@latest work "<title>"`
+
+3. **Run command** and report the created file path.
+
+4. **Open the file** and help user fill in the work details:
+   - What was done
+   - Files changed
+   - Decisions made
+   - Next steps
+
+## Entry format
+
+Worklog entries are Markdown scaffolds stored per-actor to avoid merge conflicts in shared repos. Each entry is timestamped and attributed to the current actor (`memoc actor` to check/set).

package/skills/memoc/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: memoc
+description: >
+  Follow the full memoc operating protocol for a project: read memory first,
+  preserve durable context, use the project-local memoc runtime when available,
+  and record important work before handoff. Trigger: /memoc, "use memoc",
+  "follow memoc memory", "resume with memoc".
+---
+
+Use this skill as the default operating mode for a repository that has, or should have, memoc memory.
+
+## Operating protocol
+
+1. Start by checking whether memoc is installed in the current project.
+   - Prefer `.memoc/` plus project-local launchers.
+   - If absent and the user wants memory set up, run `/memoc-init` or `memoc init`.
+
+2. Read memory before acting.
+   - First run `memoc summary` when available.
+   - Then open only the memory files that are relevant to the task, such as `.memoc/session-summary.md`, `.memoc/02-current-project-state.md`, `.memoc/04-handoff.md`, `.memoc/wiki/`, or worklog entries.
+
+3. Keep memory durable and concise.
+   - Record decisions, user preferences, active constraints, and handoff notes.
+   - Do not store transient command output, obvious code facts, secrets, credentials, or noisy chat history.
+   - Prefer wiki notes for reusable knowledge and worklog entries for session activity.
+
+4. Use the right memoc command when useful.
+   - `memoc search "<query>"` before broad filesystem search when looking for prior context.
+   - `memoc work "<title>"` after meaningful work so future agents know what changed.
+   - `memoc note "<title>"` for durable knowledge that should survive sessions.
+   - `memoc doctor` when memory looks stale, malformed, too large, or inconsistent.
+   - `memoc compress` when memory is noisy or oversized.
+   - `memoc upgrade` after updating memoc itself or when runtime/wrapper files are stale.
+
+5. Preserve user work.
+   - Treat memory files as collaborative project state.
+   - Do not overwrite user-authored notes unless the command is designed to preserve and merge them.
+   - Before final handoff, mention any memory updates made and any remaining health issues.
+
+## Binary resolution (all skills use this order)
+
+1. Windows: `.\.memoc\bin\memoc.cmd`
+2. macOS/Linux: `.memoc/bin/memoc`
+3. Fallback: `npx @kevin0181/memoc@latest`
+
+## Related focused skills
+
+- `/memoc-init` initializes memoc in the current project.
+- `/memoc-upgrade` refreshes runtime files while preserving memory.
+- `/memoc-search` searches memory and agent docs.
+- `/memoc-work` records session activity.
+- `/memoc-note` saves durable knowledge.
+- `/memoc-doctor` checks memory health.
+- `/memoc-compress` compacts noisy memory.

package/skills/memoc-code/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: memoc-code
+description: >
+  Coding guardrails adapted from multica-ai/andrej-karpathy-skills. Use when
+  writing, fixing, reviewing, or refactoring code: think before coding, keep the
+  solution simple, edit surgically, and verify against concrete success criteria.
+  Trigger: /memoc-code, "use memoc coding guardrails", "code carefully".
+license: MIT
+---
+
+Use this skill to reduce common AI coding mistakes: guessing, overbuilding,
+unrelated edits, and stopping before the result is verified.
+
+Source inspiration: `multica-ai/andrej-karpathy-skills`, MIT.
+
+## Protocol
+
+1. Think before coding.
+   - State assumptions when the request is ambiguous.
+   - Ask when uncertainty would change the implementation.
+   - Surface tradeoffs instead of silently choosing.
+
+2. Keep it simple.
+   - Build only what was requested.
+   - Avoid speculative configuration, future-proofing, and one-use abstractions.
+   - If the solution feels large for the problem, reduce it.
+
+3. Edit surgically.
+   - Touch only files and lines needed for the task.
+   - Match the local style.
+   - Do not clean up unrelated code; mention it separately.
+   - Remove only dead code created by your own changes.
+
+4. Make success verifiable.
+   - Turn the request into observable checks.
+   - For bugs, prefer a reproducing test or concrete repro before the fix.
+   - For refactors, verify behavior before and after.
+   - Keep looping until the check passes or the blocker is clear.
+
+## Shortcuts
+
+- `/memoc-think` for ambiguity, assumptions, and tradeoffs.
+- `/memoc-simple` for reducing overbuilt designs.
+- `/memoc-scope` for tight, minimal diffs.
+- `/memoc-goal` for tests, repros, and verification loops.

package/skills/memoc-compress/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: memoc-compress
+description: >
+  Compact memoc memory files and refresh generated indexes. Removes redundancy,
+  trims verbose entries, rebuilds activity and wiki indexes.
+  Trigger: /memoc-compress, "compress memoc", "compact memory", "clean up memoc files",
+  "memoc files too big".
+---
+
+Run `memoc compress` in the current working directory.
+
+## Steps
+
+1. **Find binary** (priority order):
+   - Windows: `.\.memoc\bin\memoc.cmd compress`
+   - macOS/Linux: `.memoc/bin/memoc compress`
+   - Fallback: `npx @kevin0181/memoc@latest compress`
+
+2. **Run compress** and capture output.
+
+3. **Report**:
+   - Which files were compacted
+   - Token/size reduction achieved (if reported)
+   - Any indexes rebuilt
+
+## When to use
+
+- `memoc tokens` shows large files (⚠ warnings)
+- After extended sessions with many entries
+- Before important commits to keep memory lean
+- session-summary.md exceeds ~800B