@leejungkiin/awkit 1.0.0

package/skill-packs/neural-memory/skills/nm-memory-sync/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: nm-memory-sync
+description: |
+  NeuralMemory-powered ambient brain sync. Replaces flat-file memory-sync with
+  associative graph recall via spreading activation. Auto-reads/writes brain on
+  every session, debug, task, and error — with richer context than keyword matching.
+metadata:
+  stage: core
+  version: "1.0"
+  replaces: memory-sync, ambient-brain
+  requires: neural-memory (pip install neural-memory)
+  tags: [memory, neural, sync, core, ambient]
+agent: Ambient Neural Brain
+allowed-tools:
+  - nmem_remember
+  - nmem_recall
+  - nmem_context
+  - nmem_stats
+  - nmem_auto
+---
+
+# NM Memory Sync — Ambient Neural Brain
+
+> Drop-in upgrade for `memory-sync` and `ambient-brain`.
+> Uses NeuralMemory's spreading activation instead of keyword overlap.
+
+---
+
+## Core Difference vs memory-sync
+
+| Feature | memory-sync (flat-file) | nm-memory-sync (this) |
+|---------|------------------------|----------------------|
+| Storage | Markdown files | SQLite graph (neurons + synapses) |
+| Recall | keyword overlap > 2 | Spreading activation graph |
+| Causality | None | `CAUSED_BY`, `LEADS_TO` links |
+| Time decay | None | Natural decay by age/priority |
+| Dedup | None | Automatic conflict detection |
+| Context | Whole file | Scoped activation subgraph |
+
+---
+
+## READ TRIGGERS (Auto-Read từ Brain)
+
+### R1: Session Start
+**Condition:** Conversation bắt đầu
+**Action:** `nmem_context()` → load recent + high-activation memories
+**Output:** Silent loading, brief summary nếu relevant
+
+### R2: New Task / Debugging
+**Condition:** User bắt đầu task mới hoặc debug session
+**Action:** `nmem_recall(task_keywords)` → associative recall
+**Output:** Show relevant decisions, past errors, solutions
+
+### R3: Error Encountered
+**Condition:** Exception, crash, hoặc lỗi xuất hiện
+**Action:** `nmem_recall(error_type + keywords)` → find past similar errors
+**Output:** Auto-propose known solutions if confidence > 0.7
+
+### R4: Architecture Question
+**Condition:** User hỏi về design, pattern, tech choice
+**Action:** `nmem_recall(topic, depth=3)` → deep associative recall
+**Output:** Related decisions, constraints, context
+
+### R5: Recurring Problem (Enhanced)
+**Condition:** Vấn đề tương tự đã gặp (spreading activation detects similarity)
+**Action:** Activate related memory cluster
+**Output:** "🧠 Similar to [memory]: [solution]" — NO keyword threshold needed
+
+---
+
+## WRITE TRIGGERS (Auto-Write vào Brain)
+
+### W1: Decision Made → `decision` type
+**Condition:** AI hoặc user đưa ra quyết định kỹ thuật
+**Capture:** "Chose X because Y" format
+**Store:** `nmem_remember(content, type="decision", priority=7)`
+**Links:** Auto-link to related memories via NeuralMemory engine
+
+### W2: Bug Fixed → `error` type
+**Condition:** User confirm fix thành công ("xong", "ok", "chạy rồi")
+**Capture:** Error + root cause + solution
+**Store:** `nmem_remember(content, type="error", priority=8)`
+**Links:** `CAUSED_BY` → triggering condition, `LEADS_TO` → fix applied
+
+### W3: Architecture Change → `instruction` type
+**Condition:** File structure thay đổi, pattern mới được áp dụng
+**Capture:** What changed + why
+**Store:** `nmem_remember(content, type="instruction", priority=7)`
+**Links:** `SUPERSEDES` → old pattern if exists
+
+### W4: Task Complete → `workflow` type
+**Condition:** Task marked done trong Beads
+**Capture:** What was done + approach taken
+**Store:** `nmem_remember(content, type="workflow", priority=5)`
+
+### W5: User Preference Detected → `preference` type
+**Condition:** User consistently uses pattern or expresses preference
+**Capture:** The preference + context
+**Store:** `nmem_remember(content, type="preference", priority=6)`
+
+---
+
+## Sync Protocol
+
+### Session Start Flow
+```
+1. nmem_context() → get active memory cluster
+2. Filter by project tags (from .project-identity if available)
+3. SILENT load — no output unless > 3 highly relevant memories
+4. If relevant: "🧠 Recalled: [brief summary]"
+```
+
+### Error Flow
+```
+1. Extract: error_type, file, function, keywords
+2. nmem_recall(f"{error_type} {keywords}", depth=2)
+3. If match (activation > 0.6):
+   → "🧠 Similar error: [past error] — Solution: [fix]"
+4. After fix confirmed:
+   → nmem_remember(error + solution, type="error", tags=[...])
+   → Create CAUSED_BY + LEADS_TO synapses
+```
+
+### Decision Write Flow
+```
+1. Detect decision signal words: "chose", "decided", "going with", "will use"
+2. Extract: choice + reason (requires both for quality decision memory)
+3. nmem_recall(topic) → check for conflicts
+4. SILENT store: nmem_remember(content, type="decision", priority=7)
+5. Confirm: "💾 Saved decision: [brief]"
+```
+
+---
+
+## Associative Recall Strategy
+
+Unlike keyword overlap (old memory-sync), nm-memory-sync uses:
+
+```
+Query: "API authentication failing"
+         ↓ spreading activation
+Anchor neurons: [api, auth, fail]
+         ↓ activate synapses (depth=2)
+Related neurons: [jwt, token, session, middleware]
+         ↓ intersect top activations
+Surface memories: 
+  - "Decided JWT over sessions for stateless API" (decision, auth tags)
+  - "Fixed middleware order causing 401" (error, api tags)
+  - "Never store tokens in localStorage" (instruction, security tags)
+```
+
+This surfaces memories that a keyword search would miss.
+
+---
+
+## Notification Behavior
+
+| Event | Output |
+|-------|--------|
+| Relevant memory found (activation > 0.7) | `🧠 [brief recall]` |
+| Decision auto-saved | `💾 Saved: [brief]` |
+| Bug solution stored | `🔧 Stored fix: [brief]` |
+| No relevant memory | Silent (no output) |
+| Conflict detected | `⚠️ Conflicts with: [memory]` |
+
+---
+
+## Fallback Mode (NeuralMemory Not Installed)
+
+If `nmem` is not available, falls back to flat-file behavior:
+```
+- Reads from brain/decisions/, brain/solutions/
+- Keyword overlap matching (legacy behavior)
+- Shows warning once: "⚠️ NeuralMemory not installed. Using flat-file fallback."
+```
+
+---
+
+## Integration
+
+- Works alongside `beads-manager` for task lifecycle hooks
+- Reads `.project-identity` for project-scoped memory filtering
+- Feeds data to `nm-memory-audit` for quality checks
+- Activated before `orchestrator` dispatches (priority 2.5 in skill chain)

package/skill-packs/neural-memory/workflows/nm-import.md

@@ -0,0 +1,73 @@
+---
+description: Import project knowledge into NeuralMemory (decisions, errors, patterns)
+---
+
+# /nm-import — Project Knowledge Import
+
+## When to use
+- Bắt đầu NeuralMemory trên project đã có sẵn
+- Sau khi `awkit enable-pack neural-memory` lần đầu
+- Muốn bulk-import từ brain/ Markdown files (legacy)
+
+## What to import
+
+```
+Priority 1 — Decisions (brain/decisions/*.md)
+Priority 2 — Solutions (brain/solutions/*.md)  
+Priority 3 — CODEBASE.md (architecture patterns)
+Priority 4 — .project-identity (project context)
+Priority 5 — git log (recent changes pattern)
+```
+
+## Steps
+
+### Step 1: Scan sources
+```
+Sources found:
+  brain/decisions/ — 12 files
+  brain/solutions/ — 8 files
+  CODEBASE.md — 1 file
+  .project-identity — 1 file
+
+Total import estimate: ~45 memories
+Proceed? [yes/no]
+```
+
+### Step 2: Parse each source
+For each file:
+- Extract individual information units
+- Classify by type (decision, error, fact, instruction)
+- Extract tags from content
+- Set priority based on type
+
+### Step 3: Deduplication
+```python
+# Check NeuralMemory for existing similar memories
+nmem_recall(content_keywords)
+# → Skip if identical
+# → Flag if conflicting
+```
+
+### Step 4: Batch import preview
+Show 10 at a time, confirm each batch
+
+### Step 5: Build synapse graph
+After import, run:
+```python
+nmem_auto()  # Auto-detect relationships between imported memories
+```
+
+### Step 6: Import summary
+```
+✅ Import Complete
+   Imported: 42 memories
+   Skipped: 3 duplicates
+   Auto-linked: 18 synapse connections
+
+Brain is now seeded. Run /memory-audit to check quality.
+```
+
+## Anti-patterns
+- Do NOT import everything blindly — quality over quantity
+- Do NOT import temporary notes or debug snippets
+- Do NOT skip the deduplication step (creates noise)

package/skill-packs/neural-memory/workflows/nm-recall.md

@@ -0,0 +1,67 @@
+---
+description: Query NeuralMemory với associative recall (spreading activation)
+---
+
+# /nm-recall — NeuralMemory Associative Recall
+
+## When to use
+- Cần tìm lại quyết định, lỗi, hoặc patterns từ past sessions
+- Regular recall không đủ — cần associative links
+- Muốn surface hidden connections giữa các memories
+
+## Steps
+
+1. **Extract query keywords** từ user's question
+   - Lấy 3-5 keywords cốt lõi
+   - Bỏ qua stop words
+
+2. **Run activating recall**
+   ```
+   nmem_recall(query, depth=2)
+   ```
+   - `depth=1`: Instant recall — direct matches only
+   - `depth=2`: Context recall — + 1 hop via synapses (default)
+   - `depth=3`: Deep recall — use for complex architecture questions
+
+3. **Format recall results**
+   ```
+   🧠 Recalled [N] memories for: "[query]"
+   
+   [type] "[content excerpt]"
+   → Tags: [tags] | Priority: [P] | Age: [X days]
+   → Connected to: [related memory brief] via [synapse_type]
+   
+   [type] "[content excerpt]"
+   ...
+   ```
+
+4. **Surface connections**
+   - Highlight `CAUSED_BY`, `LEADS_TO`, `DISCUSSED` links
+   - Show causal chains when relevant: A → caused → B → leads to → C
+
+5. **If no results (depth=2)**
+   - Try `depth=3` automatically
+   - If still empty: "🧠 No relevant memories found. Consider /nm-intake to capture this."
+
+## Output Examples
+
+```
+🧠 Recalled 3 memories for: "auth JWT"
+
+[decision] "Chose JWT over sessions for stateless API auth"
+→ Tags: [auth, jwt, api, decision] | Priority: 8 | Age: 14 days
+→ Caused by: "Need to support mobile + web clients simultaneously"
+→ Leads to: "JWT stored in Authorization header, 24h expiry"
+
+[error] "Fixed: JWT middleware running before auth check caused 401 on valid tokens"
+→ Tags: [auth, jwt, middleware, error] | Priority: 7 | Age: 5 days
+→ Solution: "Reorder middleware: auth check → JWT verify → route handler"
+
+[instruction] "Never store JWT in localStorage — XSS vulnerability"
+→ Tags: [auth, security, jwt, instruction] | Priority: 9 | Age: 30 days
+```
+
+## Anti-patterns
+- Do NOT just keyword search — use NeuralMemory's associative engine
+- Do NOT show all memories — only top activations (max 8)
+- Do NOT skip connections — the synapse links ARE the value

package/skill-packs/neural-memory/workflows/nm-snapshot.md

@@ -0,0 +1,69 @@
+---
+description: Export NeuralMemory brain state to JSON snapshot (portable consciousness)
+---
+
+# /nm-snapshot — Brain Snapshot Export
+
+## When to use
+- Trước khi switch AI tools hoặc agents
+- Backup trước sprint hoặc major refactor
+- Share brain với teammate/agent
+- "Portable Consciousness" — export & re-import vào agent khác
+
+## Steps
+
+### Step 1: Choose snapshot scope
+```
+Snapshot scope:
+  a) Full brain — all memories + synapses
+  b) Topic scope — memories matching [topic]
+  c) Recent — memories from last [N] days
+  d) High priority — priority >= 7 only
+
+[Choose scope]
+```
+
+### Step 2: Generate snapshot
+```python
+# Export to JSON
+snapshot = {
+  "version": "1.0",
+  "exported_at": "2026-02-26T12:00:00Z",
+  "project": "<from .project-identity>",
+  "scope": "<chosen scope>",
+  "memories": [...],
+  "synapses": [...],
+  "stats": {
+    "total_memories": N,
+    "total_synapses": N,
+    "avg_priority": X.X
+  }
+}
+```
+
+### Step 3: Save + report
+```
+✅ Snapshot saved: brain_snapshot_2026-02-26.json
+
+  Memories: 127
+  Synapses: 245
+  Size: 48KB
+
+💡 To import into another agent:
+   nmem import brain_snapshot_2026-02-26.json
+   
+💡 To share with teammate:
+   Copy the JSON file and they run nmem import
+```
+
+## Portable Consciousness
+
+This snapshot is the "Brain-as-a-Service" concept from NeuralMemory's vision:
+- All associative reflexes are preserved in the synapse graph
+- Another agent loading this snapshot gets all the relationships
+- Not just facts — but the causal and temporal reasoning
+
+## Anti-patterns
+- Do NOT snapshot before deduplication (exports noise)
+- Do NOT share snapshots with sensitive credentials/tokens in memories
+- DO run /memory-audit before important snapshots

package/skills/adaptive-language/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: awf-adaptive-language
+description: >-
+  Adjust terminology based on user technical level. Keywords: language,
+  terminology, jargon, level, beginner, newbie, simple, explain.
+  Reads technical_level from preferences.json and sets communication context.
+version: 1.0.0
+---
+
+# AWF Adaptive Language
+
+Tự động điều chỉnh ngôn ngữ kỹ thuật theo trình độ user.
+
+## Trigger Conditions
+
+**Pre-hook for ALL workflows** - Activates at session start.
+
+**Check preferences:**
+```
+if exists(".brain/preferences.json"):
+    → Read technical_level
+else if exists("~/.antigravity/preferences.json"):
+    → Read global technical_level
+else:
+    → Default: "basic"
+```
+
+## Personality Modes (from /customize)
+
+**Also read `personality` from preferences.json:**
+
+### Mentor Mode (`mentor`)
+```
+Khi làm bất kỳ task nào:
+1. Giải thích TẠI SAO làm vậy
+2. Giải thích thuật ngữ mới gặp
+3. Đôi khi hỏi ngược: "Anh nghĩ tại sao phải làm vậy?"
+4. Sau khi xong: "Anh học được gì từ bước này?"
+```
+
+### Strict Coach Mode (`strict_coach`)
+```
+Khi làm bất kỳ task nào:
+1. Đòi hỏi cao về chất lượng
+2. Chỉ ra cách làm tốt hơn
+3. Giải thích best practices
+4. Không chấp nhận code xấu: "Cách này không tối ưu vì..."
+```
+
+### Default (không có personality setting)
+→ Dùng style "Trợ lý thông minh" - hữu ích, đưa lựa chọn
+
+---
+
+## Technical Levels
+
+### Level: `newbie`
+**Target:** Không biết code, chỉ có ý tưởng
+
+| Term | Translation |
+|------|-------------|
+| database | kho lưu trữ thông tin |
+| API | cổng giao tiếp giữa các phần mềm |
+| deploy | đưa lên mạng cho người khác dùng |
+| commit | lưu lại thay đổi |
+| branch | bản nháp của dự án |
+| error | lỗi cần sửa |
+| debug | tìm và sửa lỗi |
+| test | kiểm tra xem có chạy đúng không |
+| server | máy tính chạy ứng dụng |
+| frontend | giao diện người dùng thấy |
+| backend | phần xử lý ẩn phía sau |
+
+**Communication style:**
+- Giải thích MỌI khái niệm kỹ thuật
+- Dùng ví dụ đời thường
+- Tránh từ viết tắt
+- Bước nhỏ, từng bước một
+
+### Level: `basic`
+**Target:** Biết dùng máy tính, đọc được code cơ bản
+
+| Term | Usage |
+|------|-------|
+| database | database (cơ sở dữ liệu) |
+| API | API (giao diện lập trình) |
+| deploy | deploy (triển khai) |
+| commit | commit (lưu thay đổi vào git) |
+
+**Communication style:**
+- Giải thích từ kỹ thuật lần đầu
+- Sau đó dùng bình thường
+- Gợi ý tra cứu thêm nếu cần
+- Nhóm nhiều bước nhỏ lại
+
+### Level: `technical`
+**Target:** Developers, có kinh nghiệm code
+
+**Communication style:**
+- Dùng thuật ngữ chuẩn
+- Không cần giải thích
+- Tập trung vào implementation
+- Có thể dùng viết tắt (PR, CI/CD, etc.)
+
+## Execution Logic
+
+### Step 1: Load Preferences
+
+```
+preferences = null
+
+# Try local first
+if exists(".brain/preferences.json"):
+    preferences = parse(".brain/preferences.json")
+
+# Fallback to global
+if !preferences && exists("~/.antigravity/preferences.json"):
+    preferences = parse("~/.antigravity/preferences.json")
+
+# Extract level
+level = preferences?.technical?.technical_level || "basic"
+```
+
+### Step 2: Set Context
+
+```
+Set internal context for session:
+- terminology_level = level
+- Apply translation rules based on level
+```
+
+### Step 3: Silent Operation
+
+This skill operates SILENTLY:
+- KHÔNG show indicator
+- KHÔNG notify user
+- Just sets context for subsequent responses
+
+## Integration with Workflows
+
+All AWF workflows should respect the set terminology level:
+
+```
+When outputting technical terms:
+if level == "newbie":
+    → Use translated terms from table
+    → Add explanations
+elif level == "basic":
+    → Use term (explanation) format first time
+    → Plain term after that
+else:
+    → Use standard technical terms
+```
+
+## Performance
+
+- Load time: < 100ms
+- Single file read
+- Cached for session duration
+
+## Error Handling
+
+```
+If preferences.json corrupted:
+→ Use default level: "basic"
+→ NO error message to user
+
+If technical_level invalid:
+→ Map to closest: "newbie"/"basic"/"technical"
+→ Log warning internally
+```
+
+## Example Behavior
+
+**User level: newbie**
+```
+User: /deploy
+
+Output: "Sẵn sàng đưa ứng dụng lên mạng (deploy) cho người khác dùng.
+Em sẽ kiểm tra xem mọi thứ đã sẵn sàng chưa..."
+```
+
+**User level: technical**
+```
+User: /deploy
+
+Output: "Initiating deployment pipeline.
+Running pre-deploy checks..."
+```