@kevin0181/memoc 1.0.6 → 1.1.0

package/README.md

@@ -4,15 +4,18 @@
 
 Scaffolds a Markdown-based project memory into any codebase. Works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.
 
-## Quick Start
-
+## Quick Start
+
 ```bash
 npx @kevin0181/memoc init
+
+# Upgrade memoc in this project without deleting existing memory
+npx @kevin0181/memoc@latest upgrade
 ```
 
 Run inside your project directory. Detects your stack automatically and generates everything agents need.
 
-`init` also creates PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH. It installs a `memoc` launcher into a writable directory already on the current PATH when possible, then also installs a user-local launcher and registers that launcher directory on Windows, macOS, and Linux.
+`init` also creates project-local PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH.
 
 ```bash
 # PowerShell
@@ -22,9 +25,48 @@ Run inside your project directory. Detects your stack automatically and generate
 . ./.memoc/env.sh
 ```
 
-Agents are instructed to try commands in this order: `memoc <command>`, `.\.memoc\bin\memoc.cmd <command>` on Windows or `.memoc/bin/memoc <command>` in sh, then `npx @kevin0181/memoc <command>`.
-
----
+Agents are instructed to use the project-local wrapper if PATH fails:
+
+```bash
+# Windows
+.\.memoc\bin\memoc.cmd summary
+
+# macOS / Linux
+.memoc/bin/memoc summary
+```
+
+---
+
+## Ask An Agent To Install
+
+If you are giving this repo or npm package to an AI coding agent, use a prompt like:
+
+```text
+Install memoc in this project and run init.
+Use npm/npx if available. If npm is missing but node is available, clone or download
+https://github.com/neneee0181/memoc and run `node <memoc-repo>/bin/cli.js init`
+from this project's root. After init, verify with the project-local wrapper:
+Windows: .\.memoc\bin\memoc.cmd summary
+macOS/Linux: .memoc/bin/memoc summary
+```
+
+Agent install checklist:
+
+1. Run `node --version`. If Node.js is missing, ask the user to install Node.js LTS first.
+2. Run `npx @kevin0181/memoc init` from the target project root.
+3. If `npx` or `npm` is missing, use GitHub source instead:
+   ```bash
+   git clone https://github.com/neneee0181/memoc.git
+   node /path/to/memoc/bin/cli.js init
+   ```
+4. If `git` is missing too, download the GitHub ZIP, extract it, then run `node /path/to/memoc/bin/cli.js init`.
+5. After init, do not depend on global PATH. Use the project-local wrapper when needed:
+   - Windows: `.\.memoc\bin\memoc.cmd <command>`
+   - macOS/Linux: `.memoc/bin/memoc <command>`
+
+If `node --version` fails, memoc cannot run yet. Install Node.js first, then repeat the steps above.
+
+---
 
 ## The Problem
 
@@ -46,10 +88,14 @@ npx @kevin0181/memoc update
 # Print current status in ~10 lines
 npx @kevin0181/memoc summary
 
-# Find relevant files before opening them (token-efficient)
+# Search memory/agent docs first (token-efficient)
 npx @kevin0181/memoc search "auth"
 npx @kevin0181/memoc search "auth" --snippets --limit 5
 
+# Search project source/text files only when memory is not enough
+npx @kevin0181/memoc grep "GetParticles"
+npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
+
 # Estimate token cost of current memory files
 npx @kevin0181/memoc tokens
 
@@ -65,7 +111,38 @@ npx @kevin0181/memoc add gemini
 
 ---
 
-## What Gets Created
+## Upgrade Existing Projects
+
+memoc never auto-updates itself. Upgrade only when you choose to run:
+
+```bash
+npx @kevin0181/memoc@latest upgrade
+```
+
+Run it from the project root. It preserves existing project memory, including:
+
+- `.memoc/session-summary.md`
+- `.memoc/02-current-project-state.md` human-written sections
+- `.memoc/03-decisions.md`
+- `.memoc/04-handoff.md`
+- `.memoc/06-project-rules.md`
+- `.memoc/log.md`
+- `.memoc/systems/`
+- `.memoc/wiki/`
+
+It refreshes the managed blocks, project-local wrappers, runtime copy, PATH helpers, and missing template files. If `memoc` is not on PATH after upgrading, keep using:
+
+```bash
+# Windows
+.\.memoc\bin\memoc.cmd summary
+
+# macOS / Linux
+.memoc/bin/memoc summary
+```
+
+---
+
+## What Gets Created
 
 ```
 CLAUDE.md                                    ← Claude Code entry point (auto-loaded)
@@ -73,11 +150,11 @@ AGENTS.md                                    ← Codex entry point (auto-loaded)
 llms.txt                                     ← LLM-facing project map
 .claude/settings.json                        ← Claude Code Stop hook
 
-.memoc/
-  bin/memoc                                  ← project-local wrapper for PATH fallback
-  env.ps1 · env.sh                           ← shell helpers that prepend .memoc/bin to PATH
-  session-summary.md                         ← Only required startup read (~150 tokens)
-  02-current-project-state.md               ← Status, open tasks, commands
+.memoc/
+  bin/memoc                                  ← project-local wrapper for PATH fallback
+  env.ps1 · env.sh                           ← shell helpers that prepend .memoc/bin to PATH
+  session-summary.md                         ← Only required startup read (~150 tokens)
+  02-current-project-state.md               ← Status, open tasks, commands
   03-decisions.md                            ← Durable decision log
   04-handoff.md                              ← Resume context, verified/unverified
   06-project-rules.md                        ← User preferences