@kevin0181/memoc 1.1.0 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +174 -177
  3. package/bin/cli.js +1953 -1711
  4. package/package.json +37 -37
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 neneee0181
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 neneee0181
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
- # memoc
2
-
3
- > AI agents forget everything when a session ends. memoc gives them a structured memory system so they can pick up exactly where they left off — without you repeating yourself.
4
-
5
- Scaffolds a Markdown-based project memory into any codebase. Works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.
6
-
1
+ # memoc
2
+
3
+ > AI agents forget everything when a session ends. memoc gives them a structured memory system so they can pick up exactly where they left off — without you repeating yourself.
4
+
5
+ Scaffolds a Markdown-based project memory into any codebase. Works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.
6
+
7
7
  ## Quick Start
8
8
 
9
9
  ```bash
@@ -43,74 +43,71 @@ If you are giving this repo or npm package to an AI coding agent, use a prompt l
43
43
 
44
44
  ```text
45
45
  Install memoc in this project and run init.
46
- Use npm/npx if available. If npm is missing but node is available, clone or download
47
- https://github.com/neneee0181/memoc and run `node <memoc-repo>/bin/cli.js init`
48
- from this project's root. After init, verify with the project-local wrapper:
46
+ Use the npm package only. Run `npx @kevin0181/memoc@latest init`
47
+ from this project's root. Do not clone the GitHub repository into this project.
48
+ If npm/npx is missing, stop and ask the user to install Node.js LTS with npm first.
49
+ After init, verify with the project-local wrapper:
49
50
  Windows: .\.memoc\bin\memoc.cmd summary
50
51
  macOS/Linux: .memoc/bin/memoc summary
51
52
  ```
52
53
 
53
54
  Agent install checklist:
54
55
 
55
- 1. Run `node --version`. If Node.js is missing, ask the user to install Node.js LTS first.
56
- 2. Run `npx @kevin0181/memoc init` from the target project root.
57
- 3. If `npx` or `npm` is missing, use GitHub source instead:
58
- ```bash
59
- git clone https://github.com/neneee0181/memoc.git
60
- node /path/to/memoc/bin/cli.js init
61
- ```
62
- 4. If `git` is missing too, download the GitHub ZIP, extract it, then run `node /path/to/memoc/bin/cli.js init`.
56
+ 1. Run `node --version` and `npm --version`. If either fails, ask the user to install Node.js LTS with npm first.
57
+ 2. Run `npx @kevin0181/memoc@latest init` from the target project root.
58
+ 3. Do not clone this GitHub repository into the target project. Do not download the repo ZIP as an installer.
59
+ 4. `.claude/settings.json` is intentionally generated for the Claude Code Stop hook; keep or commit it only if the project wants that hook.
63
60
  5. After init, do not depend on global PATH. Use the project-local wrapper when needed:
64
61
  - Windows: `.\.memoc\bin\memoc.cmd <command>`
65
62
  - macOS/Linux: `.memoc/bin/memoc <command>`
66
63
 
67
- If `node --version` fails, memoc cannot run yet. Install Node.js first, then repeat the steps above.
64
+ If `node --version` or `npm --version` fails, memoc cannot be installed yet. Install Node.js LTS with npm first, then repeat the steps above.
65
+
66
+ ---
67
+
68
+ ## The Problem
69
+
70
+ Every new AI session starts cold. You re-explain the project, the decisions already made, what's done and what isn't. The agent rediscovers what the last one figured out.
71
+
72
+ memoc installs a memory structure that agents read at session start, update as they work, and hand off to the next session — automatically.
68
73
 
69
74
  ---
70
-
71
- ## The Problem
72
-
73
- Every new AI session starts cold. You re-explain the project, the decisions already made, what's done and what isn't. The agent rediscovers what the last one figured out.
74
-
75
- memoc installs a memory structure that agents read at session start, update as they work, and hand off to the next session — automatically.
76
-
77
- ---
78
-
79
- ## Commands
80
-
81
- ```bash
82
- # First-time setup — scaffold memory, detect stack, install Claude Code hook
83
- npx @kevin0181/memoc init
84
-
85
- # Re-scan project and refresh managed sections
86
- npx @kevin0181/memoc update
87
-
88
- # Print current status in ~10 lines
89
- npx @kevin0181/memoc summary
90
-
91
- # Search memory/agent docs first (token-efficient)
92
- npx @kevin0181/memoc search "auth"
93
- npx @kevin0181/memoc search "auth" --snippets --limit 5
94
-
95
- # Search project source/text files only when memory is not enough
96
- npx @kevin0181/memoc grep "GetParticles"
97
- npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
98
-
99
- # Estimate token cost of current memory files
100
- npx @kevin0181/memoc tokens
101
-
102
- # Archive old log entries to keep log.md small
103
- npx @kevin0181/memoc compress
104
-
105
- # Add the same protocol to another agent's entry file
106
- npx @kevin0181/memoc add cursor
107
- npx @kevin0181/memoc add windsurf
108
- npx @kevin0181/memoc add copilot
109
- npx @kevin0181/memoc add gemini
110
- ```
111
-
112
- ---
113
-
75
+
76
+ ## Commands
77
+
78
+ ```bash
79
+ # First-time setup — scaffold memory, detect stack, install Claude Code hook
80
+ npx @kevin0181/memoc init
81
+
82
+ # Re-scan project and refresh managed sections
83
+ npx @kevin0181/memoc update
84
+
85
+ # Print current status in ~10 lines
86
+ npx @kevin0181/memoc summary
87
+
88
+ # Search memory/agent docs first (token-efficient)
89
+ npx @kevin0181/memoc search "auth"
90
+ npx @kevin0181/memoc search "auth" --snippets --limit 5
91
+
92
+ # Search project source/text files only when memory is not enough
93
+ npx @kevin0181/memoc grep "GetParticles"
94
+ npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
95
+
96
+ # Estimate token cost of current memory files
97
+ npx @kevin0181/memoc tokens
98
+
99
+ # Archive old log entries to keep log.md small
100
+ npx @kevin0181/memoc compress
101
+
102
+ # Add the same protocol to another agent's entry file
103
+ npx @kevin0181/memoc add cursor
104
+ npx @kevin0181/memoc add windsurf
105
+ npx @kevin0181/memoc add copilot
106
+ npx @kevin0181/memoc add gemini
107
+ ```
108
+
109
+ ---
110
+
114
111
  ## Upgrade Existing Projects
115
112
 
116
113
  memoc never auto-updates itself. Upgrade only when you choose to run:
@@ -143,118 +140,118 @@ It refreshes the managed blocks, project-local wrappers, runtime copy, PATH help
143
140
  ---
144
141
 
145
142
  ## What Gets Created
146
-
147
- ```
148
- CLAUDE.md ← Claude Code entry point (auto-loaded)
149
- AGENTS.md ← Codex entry point (auto-loaded)
150
- llms.txt ← LLM-facing project map
151
- .claude/settings.json ← Claude Code Stop hook
152
-
153
- .memoc/
154
- bin/memoc ← project-local wrapper for PATH fallback
155
- env.ps1 · env.sh ← shell helpers that prepend .memoc/bin to PATH
156
- session-summary.md ← Only required startup read (~150 tokens)
157
- 02-current-project-state.md ← Status, open tasks, commands
158
- 03-decisions.md ← Durable decision log
159
- 04-handoff.md ← Resume context, verified/unverified
160
- 06-project-rules.md ← User preferences
161
- log.md ← Append-only activity log
162
- systems/ ← Subsystem docs
163
- wiki/ ← Synthesized knowledge base
164
-
165
- skills/project-memory-maintainer/SKILL.md ← Wiki & systems operations guide
166
- ```
167
-
168
- ---
169
-
170
- ## How Agents Use It
171
-
172
- Every entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) gets the same protocol injected as a managed block:
173
-
174
- ```
175
- ## Session Start
176
- - [ ] Read `.memoc/session-summary.md`
177
- - [ ] `.pending` exists? → review changed files → update memory if needed → delete it
178
-
179
- ## Before Opening More Files
180
- - [ ] Run `memoc search "<query>"` first
181
- - [ ] Open on demand: `02` status · `04` resume · `06` rules · `llms.txt` map
182
- - [ ] Keep output small: `summary`, `search --limit`, `search --snippets`
183
-
184
- ## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
185
- - [ ] Code/config/deps changed → `02` (version, commands list, Last synced) + `session-summary.md` (status, changed, open tasks)
186
- - [ ] Decision made → `03-decisions.md` (what & why) + `02`
187
- - [ ] Work incomplete or risky → `04-handoff.md` (verified commands, unverified items, next steps)
188
- - [ ] Rule/preference set → `06-project-rules.md`
189
- - [ ] Wiki/systems work → read `skills/project-memory-maintainer/SKILL.md`
190
- ```
191
-
192
- The checklist tells agents exactly when to update, which file to update, and what to record — so nothing gets missed.
193
-
194
- ---
195
-
196
- ## Token Efficiency
197
-
198
- Startup cost is kept minimal by design.
199
-
200
- | What loads | Tokens |
201
- |---|---|
202
- | `CLAUDE.md` (managed block only) | ~280 |
203
- | `session-summary.md` (only required read) | ~150 |
204
- | **Total startup** | **~430** |
205
-
206
- Everything else is on-demand. Use `memoc tokens` to see the live breakdown for your project.
207
-
208
- ---
209
-
210
- ## Claude Code Auto-Detection
211
-
212
- `init` installs a lightweight `Stop` hook in `.claude/settings.json`. After each Claude Code response it checks:
213
-
214
- ```bash
215
- git status --porcelain
216
- ```
217
-
218
- If uncommitted changes exist, it writes `.memoc/.pending` with a timestamp and the changed filenames. At the next session start, Claude reads `.pending` and decides whether to update memory — then deletes the file.
219
-
220
- No extra setup. Add `.memoc/.pending` to `.gitignore` to keep it untracked.
221
-
222
- ---
223
-
224
- ## Multi-Agent Support
225
-
226
- `init` creates `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex) by default. All agents follow the same 3-phase checklist protocol.
227
-
228
- Add more agents on demand:
229
-
230
- | Command | Creates |
231
- |---|---|
232
- | `add cursor` | `.cursorrules` |
233
- | `add windsurf` | `.windsurfrules` |
234
- | `add copilot` | `.github/copilot-instructions.md` |
235
- | `add gemini` | `GEMINI.md` |
236
-
237
- Running `update` refreshes managed blocks in all existing agent files.
238
-
239
- ---
240
-
241
- ## Supported Stacks
242
-
243
- Auto-detected from your project files:
244
-
245
- Node.js · Next.js · React · Vue · Svelte · Angular · Nuxt · Astro · Express · Fastify · Hono · Electron · Tauri · TypeScript · Prisma · Drizzle · Supabase · Python · FastAPI · Django · Flask · PyTorch · Rust · Go · C++ / CMake · .NET · Java · Flutter · Unreal Engine
246
-
247
- ---
248
-
249
- ## How It Works
250
-
251
- - **New project** — scaffolds all memory files with sensible defaults.
252
- - **Existing project** — detects your stack and fills in real project info (name, scripts, config files).
253
- - **Already initialized** — `init` injects the managed block without touching your existing content. `update` re-scans and refreshes project-specific sections.
254
- - **Long-running projects** — run `compress` to archive old `log.md` entries when the file grows large.
255
-
256
- ---
257
-
258
- ## License
259
-
260
- MIT
143
+
144
+ ```
145
+ CLAUDE.md ← Claude Code entry point (auto-loaded)
146
+ AGENTS.md ← Codex entry point (auto-loaded)
147
+ llms.txt ← LLM-facing project map
148
+ .claude/settings.json ← Claude Code Stop hook
149
+
150
+ .memoc/
151
+ bin/memoc ← project-local wrapper for PATH fallback
152
+ env.ps1 · env.sh ← shell helpers that prepend .memoc/bin to PATH
153
+ session-summary.md ← Only required startup read (~150 tokens)
154
+ 02-current-project-state.md ← Status, open tasks, commands
155
+ 03-decisions.md ← Durable decision log
156
+ 04-handoff.md ← Resume context, verified/unverified
157
+ 06-project-rules.md ← User preferences
158
+ log.md ← Append-only activity log
159
+ systems/ ← Subsystem docs
160
+ wiki/ ← Synthesized knowledge base
161
+
162
+ skills/project-memory-maintainer/SKILL.md ← Wiki & systems operations guide
163
+ ```
164
+
165
+ ---
166
+
167
+ ## How Agents Use It
168
+
169
+ Every entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) gets the same protocol injected as a managed block:
170
+
171
+ ```
172
+ ## Session Start
173
+ - [ ] Read `.memoc/session-summary.md`
174
+ - [ ] `.pending` exists? → review changed files → update memory if needed → delete it
175
+
176
+ ## Before Opening More Files
177
+ - [ ] Run `memoc search "<query>"` first
178
+ - [ ] Open on demand: `02` status · `04` resume · `06` rules · `llms.txt` map
179
+ - [ ] Keep output small: `summary`, `search --limit`, `search --snippets`
180
+
181
+ ## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
182
+ - [ ] Code/config/deps changed → `02` (version, commands list, Last synced) + `session-summary.md` (status, changed, open tasks)
183
+ - [ ] Decision made → `03-decisions.md` (what & why) + `02`
184
+ - [ ] Work incomplete or risky → `04-handoff.md` (verified commands, unverified items, next steps)
185
+ - [ ] Rule/preference set → `06-project-rules.md`
186
+ - [ ] Wiki/systems work → read `skills/project-memory-maintainer/SKILL.md`
187
+ ```
188
+
189
+ The checklist tells agents exactly when to update, which file to update, and what to record — so nothing gets missed.
190
+
191
+ ---
192
+
193
+ ## Token Efficiency
194
+
195
+ Startup cost is kept minimal by design.
196
+
197
+ | What loads | Tokens |
198
+ |---|---|
199
+ | `CLAUDE.md` (managed block only) | ~280 |
200
+ | `session-summary.md` (only required read) | ~150 |
201
+ | **Total startup** | **~430** |
202
+
203
+ Everything else is on-demand. Use `memoc tokens` to see the live breakdown for your project.
204
+
205
+ ---
206
+
207
+ ## Claude Code Auto-Detection
208
+
209
+ `init` installs a lightweight `Stop` hook in `.claude/settings.json`. After each Claude Code response it checks:
210
+
211
+ ```bash
212
+ git status --porcelain
213
+ ```
214
+
215
+ If uncommitted changes exist, it writes `.memoc/.pending` with a timestamp and the changed filenames. At the next session start, Claude reads `.pending` and decides whether to update memory — then deletes the file.
216
+
217
+ No extra setup. Add `.memoc/.pending` to `.gitignore` to keep it untracked.
218
+
219
+ ---
220
+
221
+ ## Multi-Agent Support
222
+
223
+ `init` creates `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex) by default. All agents follow the same 3-phase checklist protocol.
224
+
225
+ Add more agents on demand:
226
+
227
+ | Command | Creates |
228
+ |---|---|
229
+ | `add cursor` | `.cursorrules` |
230
+ | `add windsurf` | `.windsurfrules` |
231
+ | `add copilot` | `.github/copilot-instructions.md` |
232
+ | `add gemini` | `GEMINI.md` |
233
+
234
+ Running `update` refreshes managed blocks in all existing agent files.
235
+
236
+ ---
237
+
238
+ ## Supported Stacks
239
+
240
+ Auto-detected from your project files:
241
+
242
+ Node.js · Next.js · React · Vue · Svelte · Angular · Nuxt · Astro · Express · Fastify · Hono · Electron · Tauri · TypeScript · Prisma · Drizzle · Supabase · Python · FastAPI · Django · Flask · PyTorch · Rust · Go · C++ / CMake · .NET · Java · Flutter · Unreal Engine
243
+
244
+ ---
245
+
246
+ ## How It Works
247
+
248
+ - **New project** — scaffolds all memory files with sensible defaults.
249
+ - **Existing project** — detects your stack and fills in real project info (name, scripts, config files).
250
+ - **Already initialized** — `init` injects the managed block without touching your existing content. `update` re-scans and refreshes project-specific sections.
251
+ - **Long-running projects** — run `compress` to archive old `log.md` entries when the file grows large.
252
+
253
+ ---
254
+
255
+ ## License
256
+
257
+ MIT