@kevin0181/memoc 1.0.0 → 1.0.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 +169 -155
- package/bin/cli.js +1574 -1394
- package/package.json +37 -34
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,169 +1,183 @@
|
|
|
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
|
-
## Quick Start
|
|
8
|
-
|
|
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
|
+
## Quick Start
|
|
8
|
+
|
|
9
9
|
```bash
|
|
10
10
|
npx @kevin0181/memoc init
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
Run inside your project directory. Detects your stack automatically and generates everything agents need.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
## The Problem
|
|
18
|
-
|
|
19
|
-
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.
|
|
20
|
-
|
|
21
|
-
memoc installs a memory structure that agents read at session start, update as they work, and hand off to the next session — automatically.
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
|
-
## Commands
|
|
15
|
+
`init` also creates PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH. It installs a user-local `memoc` launcher and adds that launcher directory to PATH on Windows, macOS, and Linux; open a new terminal if the current shell does not pick it up immediately.
|
|
26
16
|
|
|
27
17
|
```bash
|
|
28
|
-
#
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
# Re-scan project and refresh managed sections
|
|
32
|
-
npx @kevin0181/memoc update
|
|
33
|
-
|
|
34
|
-
# Print current status in ~10 lines
|
|
35
|
-
npx @kevin0181/memoc summary
|
|
36
|
-
|
|
37
|
-
# Find relevant files before opening them (token-efficient)
|
|
38
|
-
npx @kevin0181/memoc search "auth"
|
|
39
|
-
npx @kevin0181/memoc search "auth" --snippets --limit 5
|
|
40
|
-
|
|
41
|
-
# Estimate token cost of current memory files
|
|
42
|
-
npx @kevin0181/memoc tokens
|
|
43
|
-
|
|
44
|
-
# Archive old log entries to keep log.md small
|
|
45
|
-
npx @kevin0181/memoc compress
|
|
18
|
+
# PowerShell
|
|
19
|
+
. .\.memoc\env.ps1
|
|
46
20
|
|
|
47
|
-
#
|
|
48
|
-
|
|
49
|
-
npx @kevin0181/memoc add windsurf
|
|
50
|
-
npx @kevin0181/memoc add copilot
|
|
51
|
-
npx @kevin0181/memoc add gemini
|
|
21
|
+
# sh/bash
|
|
22
|
+
. ./.memoc/env.sh
|
|
52
23
|
```
|
|
53
24
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
25
|
+
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>`.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## The Problem
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
memoc installs a memory structure that agents read at session start, update as they work, and hand off to the next session — automatically.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Commands
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
# First-time setup — scaffold memory, detect stack, install Claude Code hook
|
|
41
|
+
npx @kevin0181/memoc init
|
|
42
|
+
|
|
43
|
+
# Re-scan project and refresh managed sections
|
|
44
|
+
npx @kevin0181/memoc update
|
|
45
|
+
|
|
46
|
+
# Print current status in ~10 lines
|
|
47
|
+
npx @kevin0181/memoc summary
|
|
48
|
+
|
|
49
|
+
# Find relevant files before opening them (token-efficient)
|
|
50
|
+
npx @kevin0181/memoc search "auth"
|
|
51
|
+
npx @kevin0181/memoc search "auth" --snippets --limit 5
|
|
52
|
+
|
|
53
|
+
# Estimate token cost of current memory files
|
|
54
|
+
npx @kevin0181/memoc tokens
|
|
55
|
+
|
|
56
|
+
# Archive old log entries to keep log.md small
|
|
57
|
+
npx @kevin0181/memoc compress
|
|
58
|
+
|
|
59
|
+
# Add the same protocol to another agent's entry file
|
|
60
|
+
npx @kevin0181/memoc add cursor
|
|
61
|
+
npx @kevin0181/memoc add windsurf
|
|
62
|
+
npx @kevin0181/memoc add copilot
|
|
63
|
+
npx @kevin0181/memoc add gemini
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## What Gets Created
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
CLAUDE.md ← Claude Code entry point (auto-loaded)
|
|
72
|
+
AGENTS.md ← Codex entry point (auto-loaded)
|
|
73
|
+
llms.txt ← LLM-facing project map
|
|
74
|
+
.claude/settings.json ← Claude Code Stop hook
|
|
75
|
+
|
|
64
76
|
.memoc/
|
|
77
|
+
bin/memoc ← project-local wrapper for PATH fallback
|
|
78
|
+
env.ps1 · env.sh ← shell helpers that prepend .memoc/bin to PATH
|
|
65
79
|
session-summary.md ← Only required startup read (~150 tokens)
|
|
66
80
|
02-current-project-state.md ← Status, open tasks, commands
|
|
67
|
-
03-decisions.md ← Durable decision log
|
|
68
|
-
04-handoff.md ← Resume context, verified/unverified
|
|
69
|
-
06-project-rules.md ← User preferences
|
|
70
|
-
log.md ← Append-only activity log
|
|
71
|
-
systems/ ← Subsystem docs
|
|
72
|
-
wiki/ ← Synthesized knowledge base
|
|
73
|
-
|
|
74
|
-
skills/project-memory-maintainer/SKILL.md ← Wiki & systems operations guide
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
---
|
|
78
|
-
|
|
79
|
-
## How Agents Use It
|
|
80
|
-
|
|
81
|
-
Every entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) gets the same protocol injected as a managed block:
|
|
82
|
-
|
|
83
|
-
```
|
|
84
|
-
## Session Start
|
|
85
|
-
- [ ] Read `.memoc/session-summary.md`
|
|
86
|
-
- [ ] `.pending` exists? → review changed files → update memory if needed → delete it
|
|
87
|
-
|
|
88
|
-
## Before Opening More Files
|
|
89
|
-
- [ ] Run `memoc search "<query>"` first
|
|
90
|
-
- [ ] Open on demand: `02` status · `04` resume · `06` rules · `llms.txt` map
|
|
91
|
-
- [ ] Keep output small: `summary`, `search --limit`, `search --snippets`
|
|
92
|
-
|
|
93
|
-
## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
|
|
94
|
-
- [ ] Code/config/deps changed → `02` (version, commands list, Last synced) + `session-summary.md` (status, changed, open tasks)
|
|
95
|
-
- [ ] Decision made → `03-decisions.md` (what & why) + `02`
|
|
96
|
-
- [ ] Work incomplete or risky → `04-handoff.md` (verified commands, unverified items, next steps)
|
|
97
|
-
- [ ] Rule/preference set → `06-project-rules.md`
|
|
98
|
-
- [ ] Wiki/systems work → read `skills/project-memory-maintainer/SKILL.md`
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
The checklist tells agents exactly when to update, which file to update, and what to record — so nothing gets missed.
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Token Efficiency
|
|
106
|
-
|
|
107
|
-
Startup cost is kept minimal by design.
|
|
108
|
-
|
|
109
|
-
| What loads | Tokens |
|
|
110
|
-
|---|---|
|
|
111
|
-
| `CLAUDE.md` (managed block only) | ~280 |
|
|
112
|
-
| `session-summary.md` (only required read) | ~150 |
|
|
113
|
-
| **Total startup** | **~430** |
|
|
114
|
-
|
|
115
|
-
Everything else is on-demand. Use `memoc tokens` to see the live breakdown for your project.
|
|
116
|
-
|
|
117
|
-
---
|
|
118
|
-
|
|
119
|
-
## Claude Code Auto-Detection
|
|
120
|
-
|
|
121
|
-
`init` installs a lightweight `Stop` hook in `.claude/settings.json`. After each Claude Code response it checks:
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
git status --porcelain
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
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.
|
|
128
|
-
|
|
129
|
-
No extra setup. Add `.memoc/.pending` to `.gitignore` to keep it untracked.
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## Multi-Agent Support
|
|
134
|
-
|
|
135
|
-
`init` creates `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex) by default. All agents follow the same 3-phase checklist protocol.
|
|
136
|
-
|
|
137
|
-
Add more agents on demand:
|
|
138
|
-
|
|
139
|
-
| Command | Creates |
|
|
140
|
-
|---|---|
|
|
141
|
-
| `add cursor` | `.cursorrules` |
|
|
142
|
-
| `add windsurf` | `.windsurfrules` |
|
|
143
|
-
| `add copilot` | `.github/copilot-instructions.md` |
|
|
144
|
-
| `add gemini` | `GEMINI.md` |
|
|
145
|
-
|
|
146
|
-
Running `update` refreshes managed blocks in all existing agent files.
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## Supported Stacks
|
|
151
|
-
|
|
152
|
-
Auto-detected from your project files:
|
|
153
|
-
|
|
154
|
-
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
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
## How It Works
|
|
159
|
-
|
|
160
|
-
- **New project** — scaffolds all memory files with sensible defaults.
|
|
161
|
-
- **Existing project** — detects your stack and fills in real project info (name, scripts, config files).
|
|
162
|
-
- **Already initialized** — `init` injects the managed block without touching your existing content. `update` re-scans and refreshes project-specific sections.
|
|
163
|
-
- **Long-running projects** — run `compress` to archive old `log.md` entries when the file grows large.
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## License
|
|
168
|
-
|
|
169
|
-
MIT
|
|
81
|
+
03-decisions.md ← Durable decision log
|
|
82
|
+
04-handoff.md ← Resume context, verified/unverified
|
|
83
|
+
06-project-rules.md ← User preferences
|
|
84
|
+
log.md ← Append-only activity log
|
|
85
|
+
systems/ ← Subsystem docs
|
|
86
|
+
wiki/ ← Synthesized knowledge base
|
|
87
|
+
|
|
88
|
+
skills/project-memory-maintainer/SKILL.md ← Wiki & systems operations guide
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## How Agents Use It
|
|
94
|
+
|
|
95
|
+
Every entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) gets the same protocol injected as a managed block:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
## Session Start
|
|
99
|
+
- [ ] Read `.memoc/session-summary.md`
|
|
100
|
+
- [ ] `.pending` exists? → review changed files → update memory if needed → delete it
|
|
101
|
+
|
|
102
|
+
## Before Opening More Files
|
|
103
|
+
- [ ] Run `memoc search "<query>"` first
|
|
104
|
+
- [ ] Open on demand: `02` status · `04` resume · `06` rules · `llms.txt` map
|
|
105
|
+
- [ ] Keep output small: `summary`, `search --limit`, `search --snippets`
|
|
106
|
+
|
|
107
|
+
## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
|
|
108
|
+
- [ ] Code/config/deps changed → `02` (version, commands list, Last synced) + `session-summary.md` (status, changed, open tasks)
|
|
109
|
+
- [ ] Decision made → `03-decisions.md` (what & why) + `02`
|
|
110
|
+
- [ ] Work incomplete or risky → `04-handoff.md` (verified commands, unverified items, next steps)
|
|
111
|
+
- [ ] Rule/preference set → `06-project-rules.md`
|
|
112
|
+
- [ ] Wiki/systems work → read `skills/project-memory-maintainer/SKILL.md`
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The checklist tells agents exactly when to update, which file to update, and what to record — so nothing gets missed.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Token Efficiency
|
|
120
|
+
|
|
121
|
+
Startup cost is kept minimal by design.
|
|
122
|
+
|
|
123
|
+
| What loads | Tokens |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `CLAUDE.md` (managed block only) | ~280 |
|
|
126
|
+
| `session-summary.md` (only required read) | ~150 |
|
|
127
|
+
| **Total startup** | **~430** |
|
|
128
|
+
|
|
129
|
+
Everything else is on-demand. Use `memoc tokens` to see the live breakdown for your project.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Claude Code Auto-Detection
|
|
134
|
+
|
|
135
|
+
`init` installs a lightweight `Stop` hook in `.claude/settings.json`. After each Claude Code response it checks:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
git status --porcelain
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
No extra setup. Add `.memoc/.pending` to `.gitignore` to keep it untracked.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Multi-Agent Support
|
|
148
|
+
|
|
149
|
+
`init` creates `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex) by default. All agents follow the same 3-phase checklist protocol.
|
|
150
|
+
|
|
151
|
+
Add more agents on demand:
|
|
152
|
+
|
|
153
|
+
| Command | Creates |
|
|
154
|
+
|---|---|
|
|
155
|
+
| `add cursor` | `.cursorrules` |
|
|
156
|
+
| `add windsurf` | `.windsurfrules` |
|
|
157
|
+
| `add copilot` | `.github/copilot-instructions.md` |
|
|
158
|
+
| `add gemini` | `GEMINI.md` |
|
|
159
|
+
|
|
160
|
+
Running `update` refreshes managed blocks in all existing agent files.
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Supported Stacks
|
|
165
|
+
|
|
166
|
+
Auto-detected from your project files:
|
|
167
|
+
|
|
168
|
+
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
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## How It Works
|
|
173
|
+
|
|
174
|
+
- **New project** — scaffolds all memory files with sensible defaults.
|
|
175
|
+
- **Existing project** — detects your stack and fills in real project info (name, scripts, config files).
|
|
176
|
+
- **Already initialized** — `init` injects the managed block without touching your existing content. `update` re-scans and refreshes project-specific sections.
|
|
177
|
+
- **Long-running projects** — run `compress` to archive old `log.md` entries when the file grows large.
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT
|