@kevin0181/memoc 1.1.2 → 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.
- package/LICENSE +21 -21
- package/README.md +165 -165
- package/bin/cli.js +1953 -1711
- 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
|
|
@@ -64,50 +64,50 @@ Agent install checklist:
|
|
|
64
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
65
|
|
|
66
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.
|
|
73
|
-
|
|
74
|
-
---
|
|
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
|
-
|
|
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.
|
|
73
|
+
|
|
74
|
+
---
|
|
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
|
+
|
|
111
111
|
## Upgrade Existing Projects
|
|
112
112
|
|
|
113
113
|
memoc never auto-updates itself. Upgrade only when you choose to run:
|
|
@@ -140,118 +140,118 @@ It refreshes the managed blocks, project-local wrappers, runtime copy, PATH help
|
|
|
140
140
|
---
|
|
141
141
|
|
|
142
142
|
## What Gets Created
|
|
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
|
|
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
|