@vuau/agent-memory 0.2.0 → 0.3.0

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 (11) hide show
  1. package/README.md +77 -104
  2. package/README.vi.md +80 -89
  3. package/dist/bin/cli.js +192 -89
  4. package/dist/index.js +84 -164
  5. package/docs/ARCHITECTURE.md +6 -9
  6. package/docs/ARCHITECTURE.vi.md +10 -14
  7. package/docs/RESEARCH.md +5 -12
  8. package/docs/RESEARCH.vi.md +5 -12
  9. package/package.json +6 -13
  10. package/templates/cursorrules.md +43 -0
  11. package/templates/windsurfrules.md +43 -0
package/README.md CHANGED
@@ -13,105 +13,64 @@ AI coding assistants lose context between sessions. They can't remember:
13
13
 
14
14
  **agent-memory** solves this with a simple file-based memory system that any AI can read.
15
15
 
16
- ## Research & Architecture
16
+ ## Quick Start
17
17
 
18
- Want to understand the reasoning behind this approach?
19
-
20
- - **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments with memsearch/MCP, comparison matrix, why file-based wins
21
- - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, IDE integration, migration guide
18
+ ```bash
19
+ # Interactive mode — choose your IDEs
20
+ npx @vuau/agent-memory init
22
21
 
23
- Read these if you're evaluating solutions or migrating from other systems.
22
+ # Or specify directly
23
+ npx @vuau/agent-memory init --opencode # OpenCode only
24
+ npx @vuau/agent-memory init --copilot --cursor # Multiple IDEs
25
+ npx @vuau/agent-memory init --all # All IDEs
26
+ ```
24
27
 
25
- ## Architecture: 4 Layers
28
+ ## What It Creates
26
29
 
27
30
  ```
28
31
  / (Project Root)
29
- ├── AGENTS.md # Layer 1: Router — rules + pointers (~100 lines)
32
+ ├── AGENTS.md # OpenCode rules
33
+ ├── .cursorrules # Cursor rules
34
+ ├── .windsurfrules # Windsurf rules
30
35
  ├── .github/
31
- │ └── copilot-instructions.md # Router for GitHub Copilot
32
- ├── .agents/
33
- │ ├── MEMORY.md # Layer 2: Long-term memory — curated decisions
34
- │ ├── TASKS.md # Layer 3: Working memory — current plans
35
- │ └── spec/
36
- │ ├── architecture.md # Layer 4: Specs — detailed documentation
37
- │ └── ...
38
- ```
39
-
40
- ### Layer 1: Router (AGENTS.md)
41
- - Root file every AI IDE reads first
42
- - Max 150 lines — rules + pointers to spec files
43
- - **Not** a knowledge dump — a table of contents
44
-
45
- ### Layer 2: Long-term Memory (.agents/MEMORY.md)
46
- - Curated decisions and patterns (1-line entries)
47
- - Category headers with pointers to spec files
48
- - Agents write here when user approves a decision
49
-
50
- ### Layer 3: Working Memory (.agents/TASKS.md)
51
- - Current tasks, in-progress work, next steps
52
- - Updated at start/end of sessions
53
- - Enables cross-session continuity
54
-
55
- ### Layer 4: Specs (.agents/spec/)
56
- - Detailed documentation per domain
57
- - Referenced by MEMORY.md pointers
58
- - Agents read on-demand, not every session
59
-
60
- ## Install
61
-
62
- ### As OpenCode Plugin
63
-
64
- ```json
65
- // opencode.json
66
- {
67
- "plugin": ["@vuau/agent-memory"]
68
- }
36
+ │ └── copilot-instructions.md # GitHub Copilot rules
37
+ └── .agents/
38
+ ├── MEMORY.md # Long-term memory (decisions, patterns)
39
+ ├── TASKS.md # Working memory (current tasks)
40
+ └── spec/ # Detailed specs (on-demand)
69
41
  ```
70
42
 
71
- The plugin auto-scaffolds `.agents/` on first session and provides lifecycle hooks.
43
+ ## How It Works
72
44
 
73
- ### Standalone (any project)
45
+ 1. **You run `init`** → Creates IDE config files + `.agents/` structure
46
+ 2. **Agent reads rules** → Finds documentation map pointing to `.agents/`
47
+ 3. **Agent works** → Reads MEMORY.md before implementing, updates TASKS.md
48
+ 4. **You approve decision** → Agent writes 1-line entry to MEMORY.md
49
+ 5. **Next session** → Agent reads memory, continues where you left off
74
50
 
75
- ```bash
76
- npx @vuau/agent-memory init
77
- ```
51
+ **No plugin required.** The rules in AGENTS.md/copilot-instructions.md instruct the agent what to do.
78
52
 
79
- ### Options
53
+ ## CLI Options
80
54
 
81
55
  ```bash
82
- npx @vuau/agent-memory init --force # Overwrite existing files
83
- npx @vuau/agent-memory init --name "My App" # Custom project name
84
- npx @vuau/agent-memory init --no-copilot # Skip copilot-instructions.md
85
- npx @vuau/agent-memory init --opencode # Wire up OpenCode plugin
86
- npx @vuau/agent-memory doctor # Validate structure
56
+ npx @vuau/agent-memory init [options]
57
+
58
+ Options:
59
+ --opencode Create AGENTS.md for OpenCode
60
+ --copilot Create .github/copilot-instructions.md
61
+ --cursor Create .cursorrules
62
+ --windsurf Create .windsurfrules
63
+ --all Create config for all IDEs
64
+ --force Overwrite existing files without asking
65
+ --name <n> Project name (default: from package.json)
66
+
67
+ npx @vuau/agent-memory doctor # Validate structure
68
+ npx @vuau/agent-memory help # Show help
87
69
  ```
88
70
 
89
- #### `--opencode` flag
90
-
91
- Wires up the OpenCode plugin automatically:
92
- - Creates/updates `.opencode/package.json` with `@vuau/agent-memory` dependency
93
- - Creates/updates `opencode.json` with `"plugin": ["@vuau/agent-memory"]`
94
-
95
- After running, restart OpenCode to activate the plugin.
96
-
97
- ## How It Works
98
-
99
- ### For AI Agents
100
- 1. Agent reads `AGENTS.md` → finds documentation map
101
- 2. Before implementing → reads `MEMORY.md` for past decisions
102
- 3. Needs details → follows pointer to spec file
103
- 4. User approves decision → agent appends to `MEMORY.md`
104
- 5. End of session → agent updates `TASKS.md`
105
-
106
- ### For Developers
107
- - `MEMORY.md` = curated knowledge (you control what stays)
108
- - `TASKS.md` = resume where you left off
109
- - `spec/` = detailed docs agents update as they explore
110
- - All markdown — readable by humans, agents, and any IDE
111
-
112
71
  ## Memory Protocol
113
72
 
114
- Agents follow this protocol (defined in AGENTS.md):
73
+ Agents follow this protocol (defined in config files):
115
74
 
116
75
  ```markdown
117
76
  ## When to write
@@ -126,39 +85,53 @@ Agents follow this protocol (defined in AGENTS.md):
126
85
  ### MEMORY.md Example
127
86
 
128
87
  ```markdown
129
- ## Storybook Prototypes
130
- → Full spec: `.agents/spec/storybook.md`
131
- - 2026-04-24: State files = 3 layers (interfaces → defaults → variants via spread)
132
- - 2026-04-24: Dumb components: initialState prop + optional callbacks. No services.
88
+ ## Patterns
89
+ - 2026-04-24: State files = 3 layers (interfaces → defaults → variants)
90
+ - 2026-04-24: Dumb components: initialState prop + optional callbacks
133
91
 
134
- ## Responsive Design
92
+ ## Decisions
135
93
  - 2026-04-06: Use useMediaQuery over CSS display:none for heavy components
136
94
  ```
137
95
 
138
- ## Cross-IDE Compatibility
96
+ ## Architecture
139
97
 
140
- | IDE | Reads | Writes |
141
- |-----|-------|--------|
142
- | OpenCode | AGENTS.md + .agents/* (auto via plugin) | MEMORY.md, TASKS.md, spec/* |
143
- | GitHub Copilot | copilot-instructions.md → .agents/* | MEMORY.md (via rules) |
144
- | Cursor | .cursorrules → .agents/* | MEMORY.md (via rules) |
145
- | Windsurf | .windsurfrules → .agents/* | MEMORY.md (via rules) |
98
+ ### 4-Layer Design
99
+
100
+ | Layer | File | Purpose |
101
+ |-------|------|---------|
102
+ | Router | AGENTS.md / .cursorrules / etc | Rules + pointers (~100 lines) |
103
+ | Memory | .agents/MEMORY.md | Curated decisions (1-line each) |
104
+ | Tasks | .agents/TASKS.md | Current work, next steps |
105
+ | Specs | .agents/spec/*.md | Detailed docs (on-demand) |
106
+
107
+ ### Why File-Based?
108
+
109
+ We tested memsearch, qmd, mem0, memories.sh — all failed for various reasons (see [RESEARCH.md](./docs/RESEARCH.md)):
110
+
111
+ - **Context Blindness**: Auto-capture can't link user intent to prior analysis
112
+ - **Context Bloat**: Fallback to transcripts costs 47k+ tokens
113
+ - **Platform issues**: Dependencies don't work on Windows/VM
114
+
115
+ File-based solution:
116
+ - Agent writes when they understand context (quality > automation)
117
+ - Plain markdown (portable, git-versionable, human-readable)
118
+ - No dependencies (works everywhere)
119
+
120
+ ## Cross-IDE Compatibility
146
121
 
147
- ## Roadmap
122
+ | IDE | Config File | Reads .agents/* |
123
+ |-----|-------------|-----------------|
124
+ | OpenCode | AGENTS.md | ✅ |
125
+ | GitHub Copilot | .github/copilot-instructions.md | ✅ |
126
+ | Cursor | .cursorrules | ✅ |
127
+ | Windsurf | .windsurfrules | ✅ |
148
128
 
149
- - [x] OpenCode plugin with lifecycle hooks
150
- - [x] CLI scaffolding (`npx init`, `doctor`)
151
- - [ ] VSCode extension (sidebar, Copilot Chat integration)
152
- - [ ] Memory archiving and compression
153
- - [ ] Multi-project memory sharing
129
+ All IDEs use the same `.agents/` memory structure.
154
130
 
155
131
  ## Documentation
156
132
 
157
- - **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments, comparison, solution
158
- - **[RESEARCH.vi.md](./docs/RESEARCH.vi.md)** — Vietnamese version
159
- - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer architecture & scalability
160
- - **[ARCHITECTURE.vi.md](./docs/ARCHITECTURE.vi.md)** — Vietnamese version
161
- - **[README.vi.md](./README.vi.md)** — Vietnamese README
133
+ - **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments, comparison, why file-based wins
134
+ - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, migration
162
135
 
163
136
  ## License
164
137
 
package/README.vi.md CHANGED
@@ -11,87 +11,64 @@ AI coding assistants mất bối cảnh giữa các phiên. Họ không thể nh
11
11
 
12
12
  **agent-memory** giải quyết bằng hệ thống bộ nhớ đơn giản dựa trên file mà bất kỳ AI nào cũng có thể đọc.
13
13
 
14
- ## Kiến trúc: 4 Lớp
14
+ ## Bắt đầu nhanh
15
15
 
16
- ```
17
- / (Project Root)
18
- ├── AGENTS.md # Lớp 1: Router — rules + pointers (~100 dòng)
19
- ├── .github/
20
- │ └── copilot-instructions.md # Router cho GitHub Copilot
21
- ├── .agents/
22
- │ ├── MEMORY.md # Lớp 2: Long-term memory — curated decisions
23
- │ ├── TASKS.md # Lớp 3: Working memory — current plans
24
- │ └── spec/
25
- │ ├── architecture.md # Lớp 4: Specs — detailed documentation
26
- │ └── ...
27
- ```
28
-
29
- ### Lớp 1: Router (AGENTS.md)
30
- - Root file mọi IDE đọc đầu tiên
31
- - Max 150 dòng — rules + pointers đến spec files
32
- - **Không phải** knowledge dump — table of contents
33
-
34
- ### Lớp 2: Long-term Memory (.agents/MEMORY.md)
35
- - Curated decisions và patterns (1-line entries)
36
- - Category headers với pointers đến spec files
37
- - Agents ghi khi user approves decision
38
-
39
- ### Lớp 3: Working Memory (.agents/TASKS.md)
40
- - Current tasks, in-progress work, next steps
41
- - Updated khi session start/end
42
- - Enable cross-session continuity
43
-
44
- ### Lớp 4: Specs (.agents/spec/)
45
- - Detailed documentation per domain
46
- - Referenced bởi MEMORY.md pointers
47
- - Agents đọc on-demand, không every session
16
+ ```bash
17
+ # Interactive mode — chọn IDEs của bạn
18
+ npx @vuau/agent-memory init
48
19
 
49
- ## Cài đặt
20
+ # Hoặc chỉ định trực tiếp
21
+ npx @vuau/agent-memory init --opencode # Chỉ OpenCode
22
+ npx @vuau/agent-memory init --copilot --cursor # Nhiều IDEs
23
+ npx @vuau/agent-memory init --all # Tất cả IDEs
24
+ ```
50
25
 
51
- ### Như OpenCode Plugin
26
+ ## Cấu trúc tạo ra
52
27
 
53
- ```json
54
- // opencode.json
55
- {
56
- "plugin": ["@vuau/agent-memory"]
57
- }
28
+ ```
29
+ / (Project Root)
30
+ ├── AGENTS.md # OpenCode rules
31
+ ├── .cursorrules # Cursor rules
32
+ ├── .windsurfrules # Windsurf rules
33
+ ├── .github/
34
+ │ └── copilot-instructions.md # GitHub Copilot rules
35
+ └── .agents/
36
+ ├── MEMORY.md # Long-term memory (decisions, patterns)
37
+ ├── TASKS.md # Working memory (current tasks)
38
+ └── spec/ # Detailed specs (on-demand)
58
39
  ```
59
40
 
60
- Plugin auto-scaffolds `.agents/` khi session đầu tiên và cung cấp lifecycle hooks.
41
+ ## Cách hoạt động
61
42
 
62
- ### Standalone (any project)
43
+ 1. **Bạn chạy `init`** → Tạo IDE config files + `.agents/` structure
44
+ 2. **Agent đọc rules** → Tìm documentation map trỏ đến `.agents/`
45
+ 3. **Agent làm việc** → Đọc MEMORY.md trước khi implement, update TASKS.md
46
+ 4. **Bạn approve decision** → Agent ghi 1-line entry vào MEMORY.md
47
+ 5. **Phiên tiếp theo** → Agent đọc memory, tiếp tục từ nơi dừng lại
63
48
 
64
- ```bash
65
- npx @vuau/agent-memory init
66
- ```
49
+ **Không cần plugin.** Rules trong AGENTS.md/copilot-instructions.md hướng dẫn agent phải làm gì.
67
50
 
68
- ### Tùy chọn
51
+ ## CLI Options
69
52
 
70
53
  ```bash
71
- npx @vuau/agent-memory init --force # Overwrite existing files
72
- npx @vuau/agent-memory init --name "My App" # Custom project name
73
- npx @vuau/agent-memory init --no-copilot # Skip copilot-instructions.md
74
- npx @vuau/agent-memory doctor # Validate structure
54
+ npx @vuau/agent-memory init [options]
55
+
56
+ Options:
57
+ --opencode Tạo AGENTS.md cho OpenCode
58
+ --copilot Tạo .github/copilot-instructions.md
59
+ --cursor Tạo .cursorrules
60
+ --windsurf Tạo .windsurfrules
61
+ --all Tạo config cho tất cả IDEs
62
+ --force Ghi đè files có sẵn mà không hỏi
63
+ --name <n> Tên project (mặc định: từ package.json)
64
+
65
+ npx @vuau/agent-memory doctor # Validate structure
66
+ npx @vuau/agent-memory help # Hiện help
75
67
  ```
76
68
 
77
- ## Cách hoạt động
78
-
79
- ### Cho AI Agents
80
- 1. Agent đọc `AGENTS.md` → tìm documentation map
81
- 2. Trước khi implement → đọc `MEMORY.md` cho decisions trong quá khứ
82
- 3. Cần details → follow pointer đến spec file
83
- 4. User approves decision → agent append vào `MEMORY.md`
84
- 5. End of session → agent update `TASKS.md`
85
-
86
- ### Cho Developers
87
- - `MEMORY.md` = curated knowledge (bạn kiểm soát gì còn lại)
88
- - `TASKS.md` = resume từ nơi dừng lại
89
- - `spec/` = detailed docs agents update khi explore
90
- - Tất cả markdown — readable bởi humans, agents, và any IDE
91
-
92
69
  ## Memory Protocol
93
70
 
94
- Agents follow protocol này (defined trong AGENTS.md):
71
+ Agents follow protocol này (defined trong config files):
95
72
 
96
73
  ```markdown
97
74
  ## Khi nào ghi
@@ -106,39 +83,53 @@ Agents follow protocol này (defined trong AGENTS.md):
106
83
  ### MEMORY.md Ví dụ
107
84
 
108
85
  ```markdown
109
- ## Storybook Prototypes
110
- → Full spec: `.agents/spec/storybook.md`
111
- - 2026-04-24: State files = 3 layers (interfaces → defaults → variants via spread)
112
- - 2026-04-24: Dumb components: initialState prop + optional callbacks. No services.
86
+ ## Patterns
87
+ - 2026-04-24: State files = 3 layers (interfaces → defaults → variants)
88
+ - 2026-04-24: Dumb components: initialState prop + optional callbacks
113
89
 
114
- ## Responsive Design
90
+ ## Decisions
115
91
  - 2026-04-06: Use useMediaQuery over CSS display:none cho heavy components
116
92
  ```
117
93
 
118
- ## Cross-IDE Compatibility
94
+ ## Kiến trúc
119
95
 
120
- | IDE | Reads | Writes |
121
- |-----|-------|--------|
122
- | OpenCode | AGENTS.md + .agents/* (auto via plugin) | MEMORY.md, TASKS.md, spec/* |
123
- | GitHub Copilot | copilot-instructions.md → .agents/* | MEMORY.md (via rules) |
124
- | Cursor | .cursorrules → .agents/* | MEMORY.md (via rules) |
125
- | Windsurf | .windsurfrules → .agents/* | MEMORY.md (via rules) |
96
+ ### Thiết kế 4-Layer
97
+
98
+ | Layer | File | Mục đích |
99
+ |-------|------|----------|
100
+ | Router | AGENTS.md / .cursorrules / etc | Rules + pointers (~100 dòng) |
101
+ | Memory | .agents/MEMORY.md | Curated decisions (1-line each) |
102
+ | Tasks | .agents/TASKS.md | Current work, next steps |
103
+ | Specs | .agents/spec/*.md | Detailed docs (on-demand) |
104
+
105
+ ### Tại sao File-Based?
106
+
107
+ Chúng tôi đã test memsearch, qmd, mem0, memories.sh — tất cả failed vì nhiều lý do (xem [RESEARCH.md](./docs/RESEARCH.md)):
108
+
109
+ - **Context Blindness**: Auto-capture không thể link user intent với prior analysis
110
+ - **Context Bloat**: Fallback sang transcripts tốn 47k+ tokens
111
+ - **Platform issues**: Dependencies không work trên Windows/VM
112
+
113
+ File-based solution:
114
+ - Agent ghi khi họ hiểu context (quality > automation)
115
+ - Plain markdown (portable, git-versionable, human-readable)
116
+ - Không dependencies (works everywhere)
117
+
118
+ ## Cross-IDE Compatibility
126
119
 
127
- ## Roadmap
120
+ | IDE | Config File | Reads .agents/* |
121
+ |-----|-------------|-----------------|
122
+ | OpenCode | AGENTS.md | ✅ |
123
+ | GitHub Copilot | .github/copilot-instructions.md | ✅ |
124
+ | Cursor | .cursorrules | ✅ |
125
+ | Windsurf | .windsurfrules | ✅ |
128
126
 
129
- - [x] OpenCode plugin với lifecycle hooks
130
- - [x] CLI scaffolding (`npx init`, `doctor`)
131
- - [ ] VSCode extension (sidebar, Copilot Chat integration)
132
- - [ ] Memory archiving và compression
133
- - [ ] Multi-project memory sharing
127
+ Tất cả IDEs dùng cùng `.agents/` memory structure.
134
128
 
135
129
  ## Tài liệu
136
130
 
137
- - **[RESEARCH.md](./docs/RESEARCH.md)** — Vấn đề, thử nghiệm, so sánh, giải pháp
138
- - **[RESEARCH.vi.md](./docs/RESEARCH.vi.md)** — Bản tiếng Việt của RESEARCH
139
- - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer architecture & scalability
140
- - **[ARCHITECTURE.vi.md](./docs/ARCHITECTURE.vi.md)** — Bản tiếng Việt của ARCHITECTURE
141
- - **[README.md](./README.md)** — English version
131
+ - **[RESEARCH.md](./docs/RESEARCH.md)** — Vấn đề, thử nghiệm, so sánh, tại sao file-based thắng
132
+ - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, migration
142
133
 
143
134
  ## License
144
135