@vuau/agent-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Au Pham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @vuau/agent-memory
+
+Structured AI memory for codebases. Works with OpenCode, GitHub Copilot, Cursor, Windsurf, and any AI coding assistant that reads markdown files.
+
+**[Tiếng Việt →](./README.vi.md)**
+
+## Problem
+
+AI coding assistants lose context between sessions. They can't remember:
+- Architecture decisions you made last week
+- Code patterns specific to your project  
+- What task you were working on yesterday
+
+**agent-memory** solves this with a simple file-based memory system that any AI can read.
+
+## Research & Architecture
+
+Want to understand the reasoning behind this approach?
+
+- **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments with memsearch/MCP, comparison matrix, why file-based wins
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, IDE integration, migration guide
+
+Read these if you're evaluating solutions or migrating from other systems.
+
+## Architecture: 4 Layers
+
+```
+/ (Project Root)
+├── AGENTS.md                    # Layer 1: Router — rules + pointers (~100 lines)
+├── .github/
+│   └── copilot-instructions.md  # Router for GitHub Copilot
+├── .agents/
+│   ├── MEMORY.md                # Layer 2: Long-term memory — curated decisions
+│   ├── TASKS.md                 # Layer 3: Working memory — current plans
+│   └── spec/
+│       ├── architecture.md      # Layer 4: Specs — detailed documentation
+│       └── ...
+```
+
+### Layer 1: Router (AGENTS.md)
+- Root file every AI IDE reads first
+- Max 150 lines — rules + pointers to spec files
+- **Not** a knowledge dump — a table of contents
+
+### Layer 2: Long-term Memory (.agents/MEMORY.md)
+- Curated decisions and patterns (1-line entries)
+- Category headers with pointers to spec files
+- Agents write here when user approves a decision
+
+### Layer 3: Working Memory (.agents/TASKS.md)
+- Current tasks, in-progress work, next steps
+- Updated at start/end of sessions
+- Enables cross-session continuity
+
+### Layer 4: Specs (.agents/spec/)
+- Detailed documentation per domain
+- Referenced by MEMORY.md pointers
+- Agents read on-demand, not every session
+
+## Install
+
+### As OpenCode Plugin
+
+```json
+// opencode.json
+{
+  "plugin": ["@vuau/agent-memory"]
+}
+```
+
+The plugin auto-scaffolds `.agents/` on first session and provides lifecycle hooks.
+
+### Standalone (any project)
+
+```bash
+npx @vuau/agent-memory init
+```
+
+### Options
+
+```bash
+npx @vuau/agent-memory init --force          # Overwrite existing files
+npx @vuau/agent-memory init --name "My App"  # Custom project name
+npx @vuau/agent-memory init --no-copilot     # Skip copilot-instructions.md
+npx @vuau/agent-memory doctor                # Validate structure
+```
+
+## How It Works
+
+### For AI Agents
+1. Agent reads `AGENTS.md` → finds documentation map
+2. Before implementing → reads `MEMORY.md` for past decisions
+3. Needs details → follows pointer to spec file
+4. User approves decision → agent appends to `MEMORY.md`
+5. End of session → agent updates `TASKS.md`
+
+### For Developers
+- `MEMORY.md` = curated knowledge (you control what stays)
+- `TASKS.md` = resume where you left off
+- `spec/` = detailed docs agents update as they explore
+- All markdown — readable by humans, agents, and any IDE
+
+## Memory Protocol
+
+Agents follow this protocol (defined in AGENTS.md):
+
+```markdown
+## When to write
+- User approves a decision → append to .agents/MEMORY.md
+- Explore codebase/architecture → update .agents/spec/*.md
+- Start/finish a large task → update .agents/TASKS.md
+
+## Entry format
+- YYYY-MM-DD: <1-line decision or pattern>
+```
+
+### MEMORY.md Example
+
+```markdown
+## Storybook Prototypes
+→ Full spec: `.agents/spec/storybook.md`
+- 2026-04-24: State files = 3 layers (interfaces → defaults → variants via spread)
+- 2026-04-24: Dumb components: initialState prop + optional callbacks. No services.
+
+## Responsive Design
+- 2026-04-06: Use useMediaQuery over CSS display:none for heavy components
+```
+
+## Cross-IDE Compatibility
+
+| IDE | Reads | Writes |
+|-----|-------|--------|
+| OpenCode | AGENTS.md + .agents/* (auto via plugin) | MEMORY.md, TASKS.md, spec/* |
+| GitHub Copilot | copilot-instructions.md → .agents/* | MEMORY.md (via rules) |
+| Cursor | .cursorrules → .agents/* | MEMORY.md (via rules) |
+| Windsurf | .windsurfrules → .agents/* | MEMORY.md (via rules) |
+
+## Roadmap
+
+- [x] OpenCode plugin with lifecycle hooks
+- [x] CLI scaffolding (`npx init`, `doctor`)
+- [ ] VSCode extension (sidebar, Copilot Chat integration)
+- [ ] Memory archiving and compression
+- [ ] Multi-project memory sharing
+
+## Documentation
+
+- **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments, comparison, solution
+- **[RESEARCH.vi.md](./docs/RESEARCH.vi.md)** — Vietnamese version
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer architecture & scalability
+- **[ARCHITECTURE.vi.md](./docs/ARCHITECTURE.vi.md)** — Vietnamese version
+- **[README.vi.md](./README.vi.md)** — Vietnamese README
+
+## License
+
+MIT

package/README.vi.md

@@ -0,0 +1,145 @@
+# @vuau/agent-memory
+
+Bộ nhớ AI có cấu trúc cho các codebase. Hoạt động với OpenCode, GitHub Copilot, Cursor, Windsurf, và bất kỳ AI coding assistant nào đọc markdown files.
+
+## Bài toán
+
+AI coding assistants mất bối cảnh giữa các phiên. Họ không thể nhớ:
+- Các quyết định kiến trúc bạn đã đưa ra tuần trước
+- Các mẫu thiết kế cụ thể của dự án
+- Task bạn đang làm hôm qua
+
+**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.
+
+## Kiến trúc: 4 Lớp
+
+```
+/ (Project Root)
+├── AGENTS.md                    # Lớp 1: Router — rules + pointers (~100 dòng)
+├── .github/
+│   └── copilot-instructions.md  # Router cho GitHub Copilot
+├── .agents/
+│   ├── MEMORY.md                # Lớp 2: Long-term memory — curated decisions
+│   ├── TASKS.md                 # Lớp 3: Working memory — current plans
+│   └── spec/
+│       ├── architecture.md      # Lớp 4: Specs — detailed documentation
+│       └── ...
+```
+
+### Lớp 1: Router (AGENTS.md)
+- Root file mọi IDE đọc đầu tiên
+- Max 150 dòng — rules + pointers đến spec files
+- **Không phải** knowledge dump — table of contents
+
+### Lớp 2: Long-term Memory (.agents/MEMORY.md)
+- Curated decisions và patterns (1-line entries)
+- Category headers với pointers đến spec files
+- Agents ghi khi user approves decision
+
+### Lớp 3: Working Memory (.agents/TASKS.md)
+- Current tasks, in-progress work, next steps
+- Updated khi session start/end
+- Enable cross-session continuity
+
+### Lớp 4: Specs (.agents/spec/)
+- Detailed documentation per domain
+- Referenced bởi MEMORY.md pointers
+- Agents đọc on-demand, không every session
+
+## Cài đặt
+
+### Như OpenCode Plugin
+
+```json
+// opencode.json
+{
+  "plugin": ["@vuau/agent-memory"]
+}
+```
+
+Plugin auto-scaffolds `.agents/` khi session đầu tiên và cung cấp lifecycle hooks.
+
+### Standalone (any project)
+
+```bash
+npx @vuau/agent-memory init
+```
+
+### Tùy chọn
+
+```bash
+npx @vuau/agent-memory init --force          # Overwrite existing files
+npx @vuau/agent-memory init --name "My App"  # Custom project name
+npx @vuau/agent-memory init --no-copilot     # Skip copilot-instructions.md
+npx @vuau/agent-memory doctor                # Validate structure
+```
+
+## Cách hoạt động
+
+### Cho AI Agents
+1. Agent đọc `AGENTS.md` → tìm documentation map
+2. Trước khi implement → đọc `MEMORY.md` cho decisions trong quá khứ
+3. Cần details → follow pointer đến spec file
+4. User approves decision → agent append vào `MEMORY.md`
+5. End of session → agent update `TASKS.md`
+
+### Cho Developers
+- `MEMORY.md` = curated knowledge (bạn kiểm soát gì còn lại)
+- `TASKS.md` = resume từ nơi dừng lại
+- `spec/` = detailed docs agents update khi explore
+- Tất cả markdown — readable bởi humans, agents, và any IDE
+
+## Memory Protocol
+
+Agents follow protocol này (defined trong AGENTS.md):
+
+```markdown
+## Khi nào ghi
+- User approves decision → append vào .agents/MEMORY.md
+- Explore codebase/architecture → update .agents/spec/*.md
+- Start/finish large task → update .agents/TASKS.md
+
+## Entry format
+- YYYY-MM-DD: <1-line decision hoặc pattern>
+```
+
+### MEMORY.md Ví dụ
+
+```markdown
+## Storybook Prototypes
+→ Full spec: `.agents/spec/storybook.md`
+- 2026-04-24: State files = 3 layers (interfaces → defaults → variants via spread)
+- 2026-04-24: Dumb components: initialState prop + optional callbacks. No services.
+
+## Responsive Design
+- 2026-04-06: Use useMediaQuery over CSS display:none cho heavy components
+```
+
+## Cross-IDE Compatibility
+
+| IDE | Reads | Writes |
+|-----|-------|--------|
+| OpenCode | AGENTS.md + .agents/* (auto via plugin) | MEMORY.md, TASKS.md, spec/* |
+| GitHub Copilot | copilot-instructions.md → .agents/* | MEMORY.md (via rules) |
+| Cursor | .cursorrules → .agents/* | MEMORY.md (via rules) |
+| Windsurf | .windsurfrules → .agents/* | MEMORY.md (via rules) |
+
+## Roadmap
+
+- [x] OpenCode plugin với lifecycle hooks
+- [x] CLI scaffolding (`npx init`, `doctor`)
+- [ ] VSCode extension (sidebar, Copilot Chat integration)
+- [ ] Memory archiving và compression
+- [ ] Multi-project memory sharing
+
+## Tài liệu
+
+- **[RESEARCH.md](./docs/RESEARCH.md)** — Vấn đề, thử nghiệm, so sánh, giải pháp
+- **[RESEARCH.vi.md](./docs/RESEARCH.vi.md)** — Bản tiếng Việt của RESEARCH
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer architecture & scalability
+- **[ARCHITECTURE.vi.md](./docs/ARCHITECTURE.vi.md)** — Bản tiếng Việt của ARCHITECTURE
+- **[README.md](./README.md)** — English version
+
+## License
+
+MIT

package/bin/cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node --experimental-strip-types --no-warnings
+/**
+ * CLI entry point for @vuau/agent-memory
+ *
+ * Usage:
+ *   npx @vuau/agent-memory init [--force] [--name <project-name>]
+ *   npx @vuau/agent-memory doctor
+ */
+
+import { scaffold } from "../src/core/scaffold.ts"
+import { doctor } from "../src/core/doctor.ts"
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+function printUsage() {
+  console.log(`
+@vuau/agent-memory — Structured AI memory for codebases
+
+Usage:
+  agent-memory init [options]    Scaffold .agents/ structure
+  agent-memory doctor            Validate .agents/ structure
+  agent-memory help              Show this help
+
+Options (init):
+  --force                        Overwrite existing files
+  --name <name>                  Project name (default: from package.json)
+  --no-copilot                   Skip .github/copilot-instructions.md
+`)
+}
+
+function runInit() {
+  const force = args.includes("--force")
+  const noCopilot = args.includes("--no-copilot")
+  const nameIdx = args.indexOf("--name")
+  const projectName = nameIdx !== -1 ? args[nameIdx + 1] : undefined
+
+  const cwd = process.cwd()
+  console.log(`Initializing agent memory in ${cwd}...`)
+
+  const result = scaffold(cwd, {
+    projectName,
+    copilotInstructions: !noCopilot,
+  }, force)
+
+  if (result.created.length > 0) {
+    console.log("\nCreated:")
+    for (const f of result.created) {
+      console.log(`  ✓ ${f}`)
+    }
+  }
+
+  if (result.skipped.length > 0) {
+    console.log("\nSkipped (already exist):")
+    for (const f of result.skipped) {
+      console.log(`  - ${f}`)
+    }
+  }
+
+  if (result.created.length === 0 && result.skipped.length > 0) {
+    console.log("\nAll files already exist. Use --force to overwrite.")
+  }
+
+  console.log("\nNext steps:")
+  console.log("  1. Edit AGENTS.md — add your project-specific rules")
+  console.log("  2. Add spec files to .agents/spec/ for detailed documentation")
+  console.log("  3. For OpenCode: add to opencode.json → { \"plugin\": [\"@vuau/agent-memory\"] }")
+  console.log("")
+}
+
+function runDoctor() {
+  const cwd = process.cwd()
+  const result = doctor(cwd)
+
+  if (result.issues.length === 0) {
+    console.log("✓ All checks passed!")
+    return
+  }
+
+  for (const issue of result.issues) {
+    const icon = issue.level === "error" ? "✗" : issue.level === "warning" ? "⚠" : "ℹ"
+    console.log(`  ${icon} [${issue.level}] ${issue.file}: ${issue.message}`)
+  }
+
+  console.log("")
+  if (result.ok) {
+    console.log("⚠ Passed with warnings. Run 'agent-memory init' to fix missing files.")
+  } else {
+    console.log("✗ Failed. Run 'agent-memory init' to create missing files.")
+    process.exit(1)
+  }
+}
+
+switch (command) {
+  case "init":
+    runInit()
+    break
+  case "doctor":
+    runDoctor()
+    break
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage()
+    break
+  default:
+    console.error(`Unknown command: ${command}`)
+    printUsage()
+    process.exit(1)
+}