@dinasor/mnemo-cli 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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
+- Vector engine now loads project `.env` values (when `GEMINI_API_KEY` is not already set in the shell) before provider resolution, so local API key setup works more reliably in CLI and MCP contexts.
+- Default vector provider auto-resolves to `gemini` when `MNEMO_PROVIDER` is unset and `GEMINI_API_KEY` is available; otherwise it falls back to `openai`.
+- Vector memory root discovery now prioritizes the script location (repo-local `scripts/memory/mnemo_vector.py`) before current working directory scanning, preventing cross-project context leaks when invoked from another directory.
+- Embedded POSIX fallback vector engine now mirrors the same `.env` and provider-resolution behavior as the primary template.
+
+### Added
+- `mnemo_vector.py` now supports direct CLI operations: `sync`, `search`, `forget`, `health`, and `status`, enabling manual vector workflows outside MCP tool calls.
+
 ## [0.0.2] - 2026-02-21
 
 ### Changed
@@ -55,6 +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.2...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
@@ -218,7 +223,7 @@ scripts/
 | `add-lesson.ps1` | Creates next `L-XXX` lesson with normalized tags |
 | `add-journal-entry.ps1` | Adds entry under current date in monthly journal |
 | `clear-active.ps1` | Resets `active-context.md` |
-| `mnemo_vector.py` | Vector sync/search MCP server (vector mode only) |
+| `mnemo_vector.py` | Vector MCP server + CLI (`sync`, `search`, `forget`, `health`, `status`) in vector mode |
 
 ## 🔐 Git hooks and API keys
 
@@ -230,12 +235,17 @@ Mnemo auto-configures `core.hooksPath` to `.githooks` and installs:
 Important:
 - Cursor MCP tools read API keys from `.mnemo/mcp/cursor.mcp.json` env placeholders (`.cursor/mcp.json` stays bridged).
 - Git hooks read API keys from your shell environment.
+- If `GEMINI_API_KEY` is not already in the environment, `scripts/memory/mnemo_vector.py` also tries loading keys from project-root `.env`.
 
 ```sh
 # bash/zsh example
 export OPENAI_API_KEY="sk-..."
 # or
 export GEMINI_API_KEY="..."
+
+# optional direct CLI usage (outside MCP tool calls)
+python3 scripts/memory/mnemo_vector.py sync
+python3 scripts/memory/mnemo_vector.py health
 ```
 
 ## ✅ Recommended daily workflow

package/VERSION

@@ -1 +1 @@
-0.0.2
+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)
 
@@ -1821,9 +1840,70 @@ from mcp.server.fastmcp import FastMCP
 
 SCHEMA_VERSION = 2
 EMBED_DIM = 1536
-MEM_ROOT = Path(".cursor/memory")
-DB_PATH = MEM_ROOT / "mnemo_vector.sqlite"
-PROVIDER = os.getenv("MNEMO_PROVIDER", "openai").lower()
+
+
+def _resolve_memory_root() -> Path:
+    override = os.getenv("MNEMO_MEMORY_ROOT", "").strip()
+    if override:
+        return Path(override).expanduser().resolve()
+
+    script_repo = Path(__file__).resolve().parents[2]
+    for rel in ((".mnemo", "memory"), (".cursor", "memory")):
+        candidate = script_repo.joinpath(*rel)
+        if candidate.exists():
+            return candidate
+
+    cwd = Path.cwd().resolve()
+    for root in (cwd, *cwd.parents):
+        for rel in ((".mnemo", "memory"), (".cursor", "memory")):
+            candidate = root.joinpath(*rel)
+            if candidate.exists():
+                return candidate
+    return script_repo / ".mnemo" / "memory"
+
+
+def _parse_env_line(raw_line: str):
+    line = raw_line.strip()
+    if not line or line.startswith("#"):
+        return None
+    if line.startswith("export "):
+        line = line[7:].strip()
+    if "=" not in line:
+        return None
+    key, value = line.split("=", 1)
+    key = key.strip()
+    if not key or any(ch.isspace() for ch in key):
+        return None
+    value = value.strip()
+    if value and len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+        value = value[1:-1]
+    elif " #" in value:
+        value = value.split(" #", 1)[0].rstrip()
+    return key, value
+
+
+def _load_project_env() -> None:
+    if os.getenv("GEMINI_API_KEY"):
+        return
+    env_path = Path(".env")
+    if not env_path.exists():
+        return
+    try:
+        for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+            parsed = _parse_env_line(raw_line)
+            if not parsed:
+                continue
+            key, value = parsed
+            os.environ.setdefault(key, value)
+    except OSError:
+        pass
+
+
+MEM_ROOT = _resolve_memory_root()
+_DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
+DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
+_load_project_env()
+PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
 
 SKIP_NAMES = {
     "README.md",
@@ -2327,6 +2407,7 @@ GI_END="# <<< Mnemo (generated) >>>"
 ignore_lines=".mnemo/
 .cursor/memory/
 .cursor/rules/
+.cursor/skills/
 .cursor/mcp.json
 .agent/rules/
 scripts/memory/
@@ -2400,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.2",
+  "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/mnemo_vector.py

@@ -9,6 +9,8 @@ import re
 import json
 import sqlite3
 import hashlib
+import argparse
+import sys
 from pathlib import Path
 
 import sqlite_vec
@@ -27,19 +29,78 @@ def _resolve_memory_root() -> Path:
     if override:
         return Path(override).expanduser().resolve()
 
+    script_repo = Path(__file__).resolve().parents[2]
+    for rel in ((".mnemo", "memory"), (".cursor", "memory")):
+        candidate = script_repo.joinpath(*rel)
+        if candidate.exists():
+            return candidate
+
     cwd = Path.cwd().resolve()
     for root in (cwd, *cwd.parents):
         for rel in ((".mnemo", "memory"), (".cursor", "memory")):
             candidate = root.joinpath(*rel)
             if candidate.exists():
                 return candidate
-    return cwd / ".mnemo" / "memory"
+    return script_repo / ".mnemo" / "memory"
+
+
+def _resolve_repo_root(memory_root: Path) -> Path:
+    root = memory_root.resolve()
+    if root.name == "memory" and root.parent.name in {".mnemo", ".cursor"}:
+        return root.parent.parent
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if candidate.joinpath(".mnemo", "memory").exists() or candidate.joinpath(".cursor", "memory").exists():
+            return candidate
+    return cwd
+
+
+def _parse_env_line(raw_line: str) -> tuple[str, str] | None:
+    line = raw_line.strip()
+    if not line or line.startswith("#"):
+        return None
+    if line.startswith("export "):
+        line = line[7:].strip()
+    if "=" not in line:
+        return None
+
+    key, value = line.split("=", 1)
+    key = key.strip()
+    if not key or any(ch.isspace() for ch in key):
+        return None
+
+    value = value.strip()
+    if value and len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+        value = value[1:-1]
+    elif " #" in value:
+        value = value.split(" #", 1)[0].rstrip()
+    return key, value
+
+
+def _load_project_env(repo_root: Path) -> None:
+    # Keep shell-provided values authoritative; only fill missing vars from .env.
+    if os.getenv("GEMINI_API_KEY"):
+        return
+    env_path = repo_root / ".env"
+    if not env_path.exists():
+        return
+    try:
+        for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+            parsed = _parse_env_line(raw_line)
+            if not parsed:
+                continue
+            key, value = parsed
+            os.environ.setdefault(key, value)
+    except OSError:
+        pass
 
 
 MEM_ROOT = _resolve_memory_root()
+REPO_ROOT = _resolve_repo_root(MEM_ROOT)
+_load_project_env(REPO_ROOT)
 _DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
 DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
-PROVIDER = os.getenv("MNEMO_PROVIDER", "openai").lower()
+PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
 
 SKIP_NAMES = {
     "README.md", "index.md", "lessons-index.json",
@@ -552,5 +613,42 @@ def memory_status() -> str:
         return json.dumps({"error": str(e)})
 
 
+def _run_cli(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Mnemo vector CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("sync", help="Rebuild vector index from memory markdown files")
+
+    p_search = sub.add_parser("search", help="Semantic search memory")
+    p_search.add_argument("query", help="Search query text")
+    p_search.add_argument("--top-k", type=int, default=8, help="Number of results to return")
+
+    p_forget = sub.add_parser("forget", help="Remove vectors by source path")
+    p_forget.add_argument("ref_path", help="Reference path to remove (exact match)")
+
+    sub.add_parser("health", help="Check DB and embedding provider health")
+    sub.add_parser("status", help="Return JSON memory status summary")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "sync":
+            print(vector_sync())
+        elif args.command == "search":
+            print(vector_search(args.query, top_k=args.top_k))
+        elif args.command == "forget":
+            print(vector_forget(args.ref_path))
+        elif args.command == "health":
+            print(vector_health())
+        elif args.command == "status":
+            print(memory_status())
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
 if __name__ == "__main__":
+    cli_commands = {"sync", "search", "forget", "health", "status"}
+    if len(sys.argv) > 1 and sys.argv[1] in cli_commands:
+        raise SystemExit(_run_cli(sys.argv[1:]))
     mcp.run()

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.