@dinasor/mnemo-cli 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -6,6 +6,15 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo u
 
 ## [Unreleased]
 
+## [0.0.4] - 2026-02-22
+
+### Added
+- Installers now seed a project-level Cursor skill at `.cursor/skills/mnemo-codebase-optimizer/` (`SKILL.md` + `reference.md`) to accelerate high-signal memory bootstrapping for any codebase.
+
+### Changed
+- Installer-managed `.gitignore` now includes `.cursor/skills/` to keep generated Mnemo skill artifacts out of default project tracking.
+- Windows and POSIX regression tests now assert skill generation so installer behavior stays consistent across platforms.
+
 ## [0.0.3] - 2026-02-21
 
 ### Changed
@@ -66,7 +75,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo u
 - Version string drift between installer metadata and generated output by using `VERSION` as single source of truth.
 - Python fallback handling in memory query flows that previously depended on a single interpreter name.
 
-[Unreleased]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.3...HEAD
+[Unreleased]: https://github.com/DiNaSoR/Mnemo/compare/v0.0.4...HEAD
+[0.0.4]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.4
 [0.0.3]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.3
 [0.0.2]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.2
 [0.0.1]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.1

package/README.md

@@ -138,6 +138,7 @@ You should see MCP tools:
 - **Atomic lessons**: `.mnemo/memory/lessons/L-XXX-*.md` + generated lesson index
 - **Monthly journal + digests**: `.mnemo/memory/journal/YYYY-MM.md` + `.mnemo/memory/digests/*.digest.md`
 - **Rule enforcement**: `.mnemo/rules/cursor/00-memory-system.mdc` and `.mnemo/rules/agent/00-memory-system.md` (bridged to `.cursor/rules/` and `.agent/rules/`)
+- **Project skill bootstrap**: `.cursor/skills/mnemo-codebase-optimizer/{SKILL.md,reference.md}` for fast codebase-to-memory optimization workflows
 - **Helper scripts**: `scripts/memory/*` (rebuild, lint, query, add-lesson, add-journal-entry, clear-active)
 - **Optional SQLite FTS**: `.mnemo/memory/memory.sqlite` when Python is available
 - **Optional vector layer**: `scripts/memory/mnemo_vector.py` + MCP tools
@@ -191,6 +192,10 @@ Runner triggers:
 .cursor/                     # permanent compatibility bridge
   memory/
   rules/
+  skills/
+    mnemo-codebase-optimizer/
+      SKILL.md
+      reference.md
   mcp.json                  # bridge to .mnemo/mcp/cursor.mcp.json
 
 .agent/                     # permanent compatibility bridge

package/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

package/memory.ps1

@@ -154,6 +154,7 @@ Write-Host "  Query:       scripts\memory\query-memory.ps1 -Query ""..."" [-UseS
 Write-Host "  Lint:        scripts\memory\lint-memory.ps1" -ForegroundColor DarkGray
 Write-Host "  Clear:       scripts\memory\clear-active.ps1" -ForegroundColor DarkGray
 Write-Host "  Rebuild:     scripts\memory\rebuild-memory-index.ps1" -ForegroundColor DarkGray
+Write-Host "  Skill:       .cursor\skills\mnemo-codebase-optimizer\SKILL.md" -ForegroundColor DarkGray
 Write-Host ""
 
 if ($EnableVector -and (-not $DryRun)) {

package/memory_mac.sh

@@ -11,7 +11,7 @@
 #   sh ./memory_mac.sh --enable-vector --vector-provider gemini
 #
 # This creates:
-#   .cursor/memory/*, .cursor/rules/*, scripts/memory/*, .githooks/pre-commit
+#   .cursor/memory/*, .cursor/rules/*, .cursor/skills/*, scripts/memory/*, .githooks/pre-commit
 #   (and optional .githooks/post-commit when --enable-vector is used)
 
 set -eu
@@ -126,6 +126,17 @@ write_file() {
   printf '%s\n' "WROTE: $path"
 }
 
+install_template_file() {
+  # install_template_file <template_path> <dest_path>
+  template_path="$1"
+  dest_path="$2"
+  if [ ! -f "$template_path" ]; then
+    printf '%s\n' "WARNING: Template not found: $template_path"
+    return 0
+  fi
+  write_file "$dest_path" < "$template_path"
+}
+
 sync_dir_one_way() {
   src="$1"
   dst="$2"
@@ -599,6 +610,14 @@ This project uses Mnemo for structured AI memory. All memory lives in `.cursor/m
 - Clear active-context.md when task is merged
 EOF
 
+# -------------------------
+# Cursor project skills
+# -------------------------
+
+_skills_tpl_dir="$_INSTALLER_DIR/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer"
+install_template_file "$_skills_tpl_dir/SKILL.md" "$CURSOR_DIR/skills/mnemo-codebase-optimizer/SKILL.md"
+install_template_file "$_skills_tpl_dir/reference.md" "$CURSOR_DIR/skills/mnemo-codebase-optimizer/reference.md"
+
 write_file "$MEM_SCRIPTS_DIR/customization.md" <<'EOF'
 # Mnemo Memory Customization Prompt (paste into an AI)
 
@@ -2388,6 +2407,7 @@ GI_END="# <<< Mnemo (generated) >>>"
 ignore_lines=".mnemo/
 .cursor/memory/
 .cursor/rules/
+.cursor/skills/
 .cursor/mcp.json
 .agent/rules/
 scripts/memory/
@@ -2461,6 +2481,7 @@ fi
 echo ""
 echo "Setup complete. (Mnemo v$MNEMO_VERSION)"
 echo "Next:"
+echo "  skill: .cursor/skills/mnemo-codebase-optimizer/SKILL.md"
 echo "  sh ./scripts/memory/rebuild-memory-index.sh"
 echo "  sh ./scripts/memory/lint-memory.sh"
 if [ "$ENABLE_VECTOR" = "1" ] && [ "$DRY_RUN" != "1" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinasor/mnemo-cli",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Mnemo installer CLI for the current project folder.",
   "license": "MIT",
   "repository": {

package/scripts/memory/installer/features/gitignore_setup.ps1

@@ -1,68 +1,69 @@
-<#
-gitignore_setup.ps1 - Managed .gitignore block for Mnemo generated artifacts.
-Dot-sourced by bootstrap.ps1.
-#>
-
-function Update-MnemoGitignore {
-  param(
-    [Parameter(Mandatory=$true)][hashtable]$Ctx,
-    [switch]$EnableVector
-  )
-
-  $giPath = Join-Path $Ctx.RepoRoot ".gitignore"
-  $giBeginMarker = "# >>> Mnemo (generated) - do not edit this block manually <<<"
-  $giEndMarker   = "# <<< Mnemo (generated) >>>"
-
-  # User-facing default: ignore the full Mnemo generated footprint so target repos stay clean by default.
-  $ignoreLines = @(
-    ".mnemo/",
-    ".cursor/memory/",
-    ".cursor/rules/",
-    ".cursor/mcp.json",
-    ".agent/rules/",
-    "scripts/memory/",
-    ".githooks/"
-  )
-
-  $giLineEndings = "CRLF"
-  $giContent = ""
-  if (Test-Path $giPath) {
-    $giContent = Get-Content -Raw -Encoding UTF8 -ErrorAction SilentlyContinue $giPath
-    if ($null -eq $giContent) { $giContent = "" }
-    if ($giContent.Length -gt 0 -and [int]$giContent[0] -eq 0xFEFF) { $giContent = $giContent.Substring(1) }
-    $giLineEndings = if ($giContent -match "`r`n") { "CRLF" } else { "LF" }
-  }
-
-  $newBlock = $giBeginMarker + "`n" + ($ignoreLines -join "`n") + "`n" + $giEndMarker
-
-  if ($script:DryRun) {
-    Write-Host "[DRY RUN] WOULD UPDATE: $giPath (managed Mnemo block)" -ForegroundColor DarkCyan
-    return
-  }
-
-  $beginEsc = [regex]::Escape($giBeginMarker)
-  $endEsc   = [regex]::Escape($giEndMarker)
-  $blockPattern = "(?s)$beginEsc.*?$endEsc"
-
-  if ($giContent -match $blockPattern) {
-    $newContent = [regex]::Replace($giContent, $blockPattern, $newBlock.Replace('$', '$$'))
-    $existingNorm = $giContent -replace "`r?`n", "`n"
-    $newNorm      = $newContent -replace "`r?`n", "`n"
-    if ($newNorm -ne $existingNorm) {
-      $enc = New-Object System.Text.UTF8Encoding($false)
-      $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
-      [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
-      Write-Host "WROTE: $giPath (updated Mnemo managed block)" -ForegroundColor Green
-    } else {
-      Write-Host "SKIP (exists): $giPath (Mnemo managed block unchanged)" -ForegroundColor DarkYellow
-    }
-  } else {
-    $trimmed = $giContent.TrimEnd("`r", "`n")
-    $sep = if ($trimmed.Length -gt 0) { "`n`n" } else { "" }
-    $newContent = $trimmed + $sep + $newBlock + "`n"
-    $enc = New-Object System.Text.UTF8Encoding($false)
-    $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
-    [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
-    Write-Host "WROTE: $giPath (added Mnemo managed block)" -ForegroundColor Green
-  }
-}
+<#
+gitignore_setup.ps1 - Managed .gitignore block for Mnemo generated artifacts.
+Dot-sourced by bootstrap.ps1.
+#>
+
+function Update-MnemoGitignore {
+  param(
+    [Parameter(Mandatory=$true)][hashtable]$Ctx,
+    [switch]$EnableVector
+  )
+
+  $giPath = Join-Path $Ctx.RepoRoot ".gitignore"
+  $giBeginMarker = "# >>> Mnemo (generated) - do not edit this block manually <<<"
+  $giEndMarker   = "# <<< Mnemo (generated) >>>"
+
+  # User-facing default: ignore the full Mnemo generated footprint so target repos stay clean by default.
+  $ignoreLines = @(
+    ".mnemo/",
+    ".cursor/memory/",
+    ".cursor/rules/",
+    ".cursor/skills/",
+    ".cursor/mcp.json",
+    ".agent/rules/",
+    "scripts/memory/",
+    ".githooks/"
+  )
+
+  $giLineEndings = "CRLF"
+  $giContent = ""
+  if (Test-Path $giPath) {
+    $giContent = Get-Content -Raw -Encoding UTF8 -ErrorAction SilentlyContinue $giPath
+    if ($null -eq $giContent) { $giContent = "" }
+    if ($giContent.Length -gt 0 -and [int]$giContent[0] -eq 0xFEFF) { $giContent = $giContent.Substring(1) }
+    $giLineEndings = if ($giContent -match "`r`n") { "CRLF" } else { "LF" }
+  }
+
+  $newBlock = $giBeginMarker + "`n" + ($ignoreLines -join "`n") + "`n" + $giEndMarker
+
+  if ($script:DryRun) {
+    Write-Host "[DRY RUN] WOULD UPDATE: $giPath (managed Mnemo block)" -ForegroundColor DarkCyan
+    return
+  }
+
+  $beginEsc = [regex]::Escape($giBeginMarker)
+  $endEsc   = [regex]::Escape($giEndMarker)
+  $blockPattern = "(?s)$beginEsc.*?$endEsc"
+
+  if ($giContent -match $blockPattern) {
+    $newContent = [regex]::Replace($giContent, $blockPattern, $newBlock.Replace('$', '$$'))
+    $existingNorm = $giContent -replace "`r?`n", "`n"
+    $newNorm      = $newContent -replace "`r?`n", "`n"
+    if ($newNorm -ne $existingNorm) {
+      $enc = New-Object System.Text.UTF8Encoding($false)
+      $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
+      [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
+      Write-Host "WROTE: $giPath (updated Mnemo managed block)" -ForegroundColor Green
+    } else {
+      Write-Host "SKIP (exists): $giPath (Mnemo managed block unchanged)" -ForegroundColor DarkYellow
+    }
+  } else {
+    $trimmed = $giContent.TrimEnd("`r", "`n")
+    $sep = if ($trimmed.Length -gt 0) { "`n`n" } else { "" }
+    $newContent = $trimmed + $sep + $newBlock + "`n"
+    $enc = New-Object System.Text.UTF8Encoding($false)
+    $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
+    [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
+    Write-Host "WROTE: $giPath (added Mnemo managed block)" -ForegroundColor Green
+  }
+}

package/scripts/memory/installer/features/memory_scaffold.ps1

@@ -436,6 +436,16 @@ function Install-MemoryScripts {
       -ForceWrite:$Force
   }
 
+  $cursorSkillTemplates = @("SKILL.md", "reference.md")
+  foreach ($f in $cursorSkillTemplates) {
+    Install-TemplateFile `
+      -TemplateName "skills\mnemo-codebase-optimizer\$f" `
+      -DestPath (Join-Path $Ctx.CursorDir "skills\mnemo-codebase-optimizer\$f") `
+      -InstallerRoot $InstallerRoot `
+      -LineEndings "LF" `
+      -ForceWrite:$Force
+  }
+
   if ($EnableVector) {
     Install-TemplateFile `
       -TemplateName "mnemo_vector.py" `

package/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: mnemo-codebase-optimizer
+description: Builds high-signal Mnemo memory quickly for any codebase by mapping architecture, ownership, workflows, risks, and commands, then writing optimized memo/hot-rules/active-context/lessons/journal entries and validating retrieval quality. Use when users ask to bootstrap Mnemo memory, optimize project context, or fill memory in a new or existing repository.
+---
+
+# Mnemo Codebase Optimizer
+
+## Purpose
+
+Use this skill to rapidly produce a detailed, reliable Mnemo knowledge base for any project.
+The goal is high retrieval quality with low token waste.
+
+## Quick Start
+
+Use this checklist and keep one step `in_progress` at a time:
+
+```text
+Memory Seeding Progress
+- [ ] 1) Confirm Mnemo install + paths
+- [ ] 2) Map codebase architecture and ownership
+- [ ] 3) Extract runbook commands and dev workflows
+- [ ] 4) Write/update core memory files
+- [ ] 5) Add initial lessons and journal summary
+- [ ] 6) Rebuild + lint + (optional) vector sync
+- [ ] 7) Validate retrieval quality and refine
+```
+
+## 1) Confirm Mnemo Install
+
+Verify these paths exist:
+- `.mnemo/memory/`
+- `.mnemo/rules/`
+- `scripts/memory/`
+
+If missing, run installer first and stop this skill until setup succeeds.
+
+## 2) Map Architecture Fast
+
+Collect only high-value context:
+- product purpose and core user flows
+- entrypoints and runtime boundaries (frontend/backend/workers/CLI)
+- module ownership and key responsibilities
+- data model sources and contracts
+- integration surfaces (APIs, queues, webhooks, external services)
+- quality/security constraints and release workflow
+
+Avoid copying large code blocks into memory files. Summarize and reference paths.
+
+## 3) Capture Operational Workflow
+
+Record:
+- install/build/test/lint commands
+- local run commands for each app/service
+- deployment/release commands and prerequisites
+- debugging commands and common failure signatures
+
+Prefer explicit command examples over vague prose.
+
+## 4) Write Core Memory Files
+
+Update these files in priority order:
+
+1. `.mnemo/memory/hot-rules.md`
+   - 10-20 lines max
+   - only hard invariants and "never do" rules
+2. `.mnemo/memory/memo.md`
+   - architecture map, ownership, critical paths, runbook
+3. `.mnemo/memory/active-context.md`
+   - current migration task + open risks + next actions
+
+Use short sections and bullets. Keep each bullet atomic and testable.
+
+## 5) Seed Lessons + Journal
+
+Create 3-8 starter lessons from known pitfalls:
+- naming conventions
+- data migration gotchas
+- environment/setup traps
+- release regressions and prevention checks
+
+Add one monthly journal entry summarizing:
+- what memory was seeded
+- why those sections matter
+- what remains unknown
+
+## 6) Rebuild and Validate
+
+Run:
+- `scripts/memory/rebuild-memory-index.ps1` (or shell equivalent)
+- `scripts/memory/lint-memory.ps1` (or shell equivalent)
+
+If vector mode is enabled:
+- run `vector_sync`
+- run `vector_health`
+
+## 7) Retrieval Quality Gate
+
+Ask 5-10 realistic queries and verify results:
+- architecture query (module boundaries)
+- workflow query (how to run/test/release)
+- ownership query (who owns what)
+- pitfall query (common mistakes)
+- troubleshooting query (known failure/fix)
+
+If retrieval misses:
+- tighten memo headings
+- split overloaded bullets
+- add a lesson instead of bloating memo
+- prune low-signal historical text
+
+## Memory Quality Rules
+
+- Keep `hot-rules.md` tiny and immutable-focused.
+- Keep `memo.md` as current truth, not raw history.
+- Put historical detail in journal, not memo.
+- Prefer lessons for reusable error-prevention patterns.
+- Use stable terminology for search consistency.
+- Every important claim should map to concrete file paths or commands.
+
+## Output Contract
+
+When done, return:
+
+1. **Coverage summary**
+   - what domains are now represented in memory
+2. **Files changed**
+   - list of memory files updated/created
+3. **Quality checks**
+   - rebuild/lint/vector status
+4. **Top retrieval queries**
+   - sample queries and expected hit files
+5. **Remaining unknowns**
+   - explicit gaps to fill in next pass
+
+## Additional Resources
+
+- Detailed templates: [reference.md](reference.md)

package/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer/reference.md

@@ -0,0 +1,138 @@
+# Mnemo Codebase Optimizer Reference
+
+## Memo Template (Detailed)
+
+Use this structure for `.mnemo/memory/memo.md`:
+
+```markdown
+# Project Memo - <project>
+
+## Mission
+- One-paragraph purpose and primary user outcomes.
+
+## System Shape
+- Runtime components:
+  - `<component>`: `<responsibility>`
+- Boundaries:
+  - `<boundary>` -> `<dependency>`
+
+## Ownership Map
+- `<module/path>` -> `<team/owner>`
+- `<module/path>` -> `<team/owner>`
+
+## Critical Flows
+- Flow A:
+  - Trigger:
+  - Core path:
+  - Side effects:
+  - Failure modes:
+- Flow B:
+  - Trigger:
+  - Core path:
+  - Side effects:
+  - Failure modes:
+
+## Data Contracts
+- `<type/schema/file>`: purpose + key fields + constraints
+- `<type/schema/file>`: purpose + key fields + constraints
+
+## Commands Runbook
+- Install: `<command>`
+- Dev run: `<command>`
+- Tests: `<command>`
+- Lint/format: `<command>`
+- Build/release: `<command>`
+
+## Constraints and Guardrails
+- Non-negotiables:
+  - `<rule>`
+  - `<rule>`
+- Security/compliance:
+  - `<constraint>`
+
+## Known Risks
+- `<risk>` -> detection -> mitigation
+- `<risk>` -> detection -> mitigation
+```
+
+## Hot Rules Template
+
+Use this structure for `.mnemo/memory/hot-rules.md` (10-20 lines):
+
+```markdown
+# Hot Rules
+
+- Never bypass `<critical check>`.
+- Do not edit `<generated path>` manually.
+- Keep `<artifact>` synchronized with `<source>`.
+- Before release: run `<required command list>`.
+- If `<failure condition>`, stop and verify `<source of truth>`.
+```
+
+## Active Context Template
+
+Use this structure for `.mnemo/memory/active-context.md`:
+
+```markdown
+# Active Context
+
+## Current Task
+- Goal:
+- Scope:
+- Out of scope:
+
+## Working Notes
+- Current status:
+- Decisions made:
+- Risks and blockers:
+
+## Next Actions
+1. `<action>`
+2. `<action>`
+3. `<action>`
+```
+
+## Starter Lesson Template
+
+Use this for each `L-XXX-*.md`:
+
+```markdown
+---
+id: L-XXX
+title: "<short pitfall title>"
+tags: ["pitfall", "regression", "<domain>"]
+applies_to: ["<path/glob>"]
+rule: "<single actionable rule>"
+---
+
+## Context
+When this appears and why it happens.
+
+## Failure Pattern
+Observable signs and likely root causes.
+
+## Corrective Action
+Exact steps to fix safely.
+
+## Prevention Check
+How to detect it before merge/release.
+```
+
+## Retrieval Validation Query Set
+
+Run and confirm each query returns high-signal files:
+
+1. "What are the core runtime boundaries?"
+2. "Which files define the main data contracts?"
+3. "How do I run full tests and lint before release?"
+4. "What regressions happened before and how do we prevent them?"
+5. "Who owns `<critical module>` and what are the rules?"
+6. "What are the top production risks in this repo?"
+
+## Optimization Heuristics
+
+- Prefer one clear heading over long paragraphs.
+- Replace duplicate bullets with one canonical bullet.
+- If a memo section grows too long, split into lessons.
+- Keep journaling chronological; keep memo conceptual.
+- Remove stale TODOs from memo; keep only current truth.