@dinasor/mnemo-cli 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1,46 +1,72 @@
-# Changelog
-
-All notable changes to Mnemo are documented here.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo uses [Semantic Versioning](https://semver.org/).
-
-## [Unreleased]
-
-## [0.0.1] - 2026-02-21
-
-### Added
-- First public Mnemo release with dual installers: `memory.ps1` (Windows PowerShell 5.1+/7+) and `memory_mac.sh` (macOS/Linux POSIX shell).
-- Installer CLI support for `--dry-run` / `-DryRun`, `--force` / `-Force`, project naming, and optional vector enablement.
-- Modular installer architecture with dedicated core and feature modules under `scripts/memory/installer/` (bootstrap, path resolution, I/O, bridges, scaffold, hooks, vector, MCP, `.gitignore`).
-- Canonical memory root at `.mnemo/` with compatibility bridges to `.cursor/` and `.agent/` so existing IDE integrations continue to work.
-- Bridge manager with cross-platform fallback behavior (symlink/junction/hardlink/mirror) and repair/migration logic for legacy layouts.
-- Canonical memory scaffold including always-read files (`hot-rules.md`, `active-context.md`, `memo.md`), lessons, journals, digests, ADR, and templates.
-- Atomic lesson workflow (`L-XXX-*`) and monthly journal workflow with rebuildable indexes/digests.
-- Helper script suite for daily operations (PowerShell + shell variants): rebuild index, lint memory, query memory, add lesson, add journal entry, clear active context.
-- Tag vocabulary enforcement and memory lint guardrails for frontmatter, structure, and token-safety checks.
-- Optional SQLite FTS support (`memory.sqlite`) when Python is available, including build/query helpers.
-- Optional vector mode with `mnemo_vector.py` MCP server and tools: `vector_search`, `vector_sync`, `vector_forget`, `vector_health`, `memory_status`.
-- Vector embedding provider support for both OpenAI and Gemini.
-- Autonomy runtime templates installed with vector mode (`autonomy/*` + `policies.yaml`) for ingestion, lifecycle, reranking, context safety, and policy handling.
-- Portable git hooks via `.githooks/` with automatic `core.hooksPath` setup.
-- Hook automation: `pre-commit` rebuild/lint and optional `post-commit` non-blocking vector sync.
-- Multi-agent bridge outputs: `CLAUDE.md`, `AGENTS.md`, and `.agent/rules/memory-system.md`.
-- Cross-platform CI coverage (Windows/macOS/Ubuntu), regression tests, modularization guardrails, and Python syntax checks for autonomy/retrieval modules.
-- Nightly benchmark workflow for retrieval quality/drift monitoring plus artifact upload.
-- GitHub release workflow for tag-based publishing with preflight/version/changelog validation and packaged installer assets.
-- Governance and contribution assets: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md`, issue templates, PR template, `CODEOWNERS`, and Dependabot config.
-
-### Changed
-- Versioning is centralized in root `VERSION` and consumed by installers and generated output.
-- Installer/runtime path resolution prefers canonical `.mnemo` while preserving `.cursor` compatibility bridges.
-- Python resolution strategy is aligned across memory tooling (`py` / `python3` / `python` fallback behavior where applicable).
-- Managed `.gitignore` and hook behavior now reflect canonical `.mnemo` artifacts while keeping bridge compatibility.
-
-### Fixed
-- Duplicate managed `.gitignore` entries on repeated force installs.
-- Bridge idempotency/self-copy failures around `.cursor/mcp.json` compatibility targets.
-- 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.1...HEAD
-[0.0.1]: https://github.com/DiNaSoR/Mnemo/releases/tag/v0.0.1
+# Changelog
+
+All notable changes to Mnemo are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Mnemo uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [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
+- Installers no longer generate root `CLAUDE.md` and `AGENTS.md`; integrations now use canonical `.mnemo/memory/` and agent bridge rules under `.agent/rules/`.
+- Agent rule naming is normalized to ordered files: `00-memory-system.md` and `01-vector-search.md` (vector mode), aligned with cursor rule naming.
+- Installer-managed `.gitignore` now uses top-level Mnemo paths (`.mnemo/`, `.cursor/memory/`, `.cursor/rules/`, `.cursor/mcp.json`, `.agent/rules/`, `scripts/memory/`, `.githooks/`) for cleaner defaults in target repositories.
+- README IDE guidance now points Claude/Codex users to canonical `.mnemo/memory/` retrieval flow and updated agent rule paths.
+
+### Fixed
+- PowerShell installer no longer hard-fails when `git config core.hooksPath .githooks` cannot be written (permission/lock); it warns and continues.
+- POSIX vector re-runs are idempotent for autonomy module installation when `--force` is not used.
+- Cross-platform installer regression tests now validate the new numbered agent rule output.
+
+## [0.0.1] - 2026-02-21
+
+### Added
+- First public Mnemo release with dual installers: `memory.ps1` (Windows PowerShell 5.1+/7+) and `memory_mac.sh` (macOS/Linux POSIX shell).
+- Installer CLI support for `--dry-run` / `-DryRun`, `--force` / `-Force`, project naming, and optional vector enablement.
+- Modular installer architecture with dedicated core and feature modules under `scripts/memory/installer/` (bootstrap, path resolution, I/O, bridges, scaffold, hooks, vector, MCP, `.gitignore`).
+- Canonical memory root at `.mnemo/` with compatibility bridges to `.cursor/` and `.agent/` so existing IDE integrations continue to work.
+- Bridge manager with cross-platform fallback behavior (symlink/junction/hardlink/mirror) and repair/migration logic for legacy layouts.
+- Canonical memory scaffold including always-read files (`hot-rules.md`, `active-context.md`, `memo.md`), lessons, journals, digests, ADR, and templates.
+- Atomic lesson workflow (`L-XXX-*`) and monthly journal workflow with rebuildable indexes/digests.
+- Helper script suite for daily operations (PowerShell + shell variants): rebuild index, lint memory, query memory, add lesson, add journal entry, clear active context.
+- Tag vocabulary enforcement and memory lint guardrails for frontmatter, structure, and token-safety checks.
+- Optional SQLite FTS support (`memory.sqlite`) when Python is available, including build/query helpers.
+- Optional vector mode with `mnemo_vector.py` MCP server and tools: `vector_search`, `vector_sync`, `vector_forget`, `vector_health`, `memory_status`.
+- Vector embedding provider support for both OpenAI and Gemini.
+- Autonomy runtime templates installed with vector mode (`autonomy/*` + `policies.yaml`) for ingestion, lifecycle, reranking, context safety, and policy handling.
+- Portable git hooks via `.githooks/` with automatic `core.hooksPath` setup.
+- Hook automation: `pre-commit` rebuild/lint and optional `post-commit` non-blocking vector sync.
+- Multi-agent bridge outputs under `.cursor/rules/` and `.agent/rules/` for IDE-specific rule loading.
+- Cross-platform CI coverage (Windows/macOS/Ubuntu), regression tests, modularization guardrails, and Python syntax checks for autonomy/retrieval modules.
+- Nightly benchmark workflow for retrieval quality/drift monitoring plus artifact upload.
+- GitHub release workflow for tag-based publishing with preflight/version/changelog validation and packaged installer assets.
+- Governance and contribution assets: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md`, issue templates, PR template, `CODEOWNERS`, and Dependabot config.
+
+### Changed
+- Versioning is centralized in root `VERSION` and consumed by installers and generated output.
+- Installer/runtime path resolution prefers canonical `.mnemo` while preserving `.cursor` compatibility bridges.
+- Python resolution strategy is aligned across memory tooling (`py` / `python3` / `python` fallback behavior where applicable).
+- Managed `.gitignore` and hook behavior now reflect canonical `.mnemo` artifacts while keeping bridge compatibility.
+
+### Fixed
+- Duplicate managed `.gitignore` entries on repeated force installs.
+- Bridge idempotency/self-copy failures around `.cursor/mcp.json` compatibility targets.
+- 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
+[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

@@ -86,9 +86,9 @@ Use the section that matches your IDE. Each project should run Mnemo install onc
 | IDE / Agent | What installer creates | What you do next |
 |---|---|---|
 | Cursor | `.mnemo/rules/cursor/00-memory-system.mdc` (+ `.mnemo/mcp/cursor.mcp.json`, bridged to `.cursor/mcp.json`) | Restart Cursor, run `vector_health`, then `vector_sync` |
-| Claude Code | `CLAUDE.md` bridge file | Open repo in Claude Code and follow read order from `CLAUDE.md` |
-| Gemini Antigravity | `.agent/rules/memory-system.md` | Ensure Antigravity loads project rules from `.agent/rules/` |
-| OpenAI Codex | `AGENTS.md` | Start Codex from repo root so `AGENTS.md` is in scope |
+| Claude Code | `.mnemo/memory/` knowledge base (also visible via `.cursor/memory`) | Open repo in Claude Code and follow retrieval order from `.mnemo/memory/index.md` |
+| Gemini Antigravity | `.agent/rules/00-memory-system.md` (+ `.agent/rules/01-vector-search.md` in vector mode) | Ensure Antigravity loads project rules from `.agent/rules/` |
+| OpenAI Codex | `.mnemo/memory/` knowledge base (also visible via `.cursor/memory`) | Start Codex from repo root and follow retrieval order from `.mnemo/memory/index.md` |
 | Windsurf / Other IDEs | `.mnemo/memory/` knowledge base (also visible at `.cursor/memory/`) | Point memory/context path to `.mnemo/memory/` |
 
 ### 1) Cursor IDE 🟦
@@ -105,23 +105,23 @@ You should see MCP tools:
 ### 2) Claude Code 🤝
 
 1. Run Mnemo install in your project root.
-2. Confirm `CLAUDE.md` exists (auto-generated by installer).
+2. Confirm `.mnemo/memory/` exists (and `.cursor/memory/` bridge is present).
 3. Start Claude Code from the project root.
-4. Keep `.mnemo/memory/` committed so memory travels with the repo (Cursor still reads through bridge).
+4. Follow retrieval order from `.mnemo/memory/index.md`.
 
 ### 3) Gemini Antigravity 🔷
 
 1. Run Mnemo install in your project root.
-2. Confirm `.agent/rules/memory-system.md` exists.
+2. Confirm `.agent/rules/00-memory-system.md` exists.
 3. Ensure your Antigravity setup loads `.agent/rules/`.
 4. (Optional) Enable vector mode for semantic memory workflows.
 
 ### 4) OpenAI Codex 🧪
 
 1. Run Mnemo install in your project root.
-2. Confirm `AGENTS.md` exists.
-3. Launch Codex from the same root so `AGENTS.md` is used.
-4. Follow the retrieval order defined in `AGENTS.md`.
+2. Confirm `.mnemo/memory/` exists (and `.cursor/memory/` bridge is present).
+3. Launch Codex from the same project root.
+4. Follow retrieval order from `.mnemo/memory/index.md`.
 
 ### 5) Windsurf / Other IDEs 🌊
 
@@ -137,7 +137,7 @@ You should see MCP tools:
 - **Always-read layer**: `.mnemo/memory/hot-rules.md`, `active-context.md`, `memo.md`
 - **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` (bridged to `.cursor/rules/`)
+- **Rule enforcement**: `.mnemo/rules/cursor/00-memory-system.mdc` and `.mnemo/rules/agent/00-memory-system.md` (bridged to `.cursor/rules/` and `.agent/rules/`)
 - **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
@@ -183,7 +183,8 @@ Runner triggers:
       00-memory-system.mdc
       01-vector-search.mdc   # vector mode only
     agent/
-      memory-system.md
+      00-memory-system.md
+      01-vector-search.md    # vector mode only
   mcp/
     cursor.mcp.json          # vector mode only
 
@@ -217,7 +218,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
 
@@ -229,12 +230,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.1
+0.0.3

package/memory.ps1

@@ -108,10 +108,29 @@ Ensure-MnemoCanonicalBridges -Ctx $ctx
 
 # Auto-configure portable hooks path (removes the manual 'git config' step)
 if (-not $DryRun -and (Test-Path $ctx.GitDir)) {
-  $currentHooksPath = & git -C $RepoRoot config core.hooksPath 2>$null
-  if ($currentHooksPath -ne ".githooks") {
-    & git -C $RepoRoot config core.hooksPath .githooks 2>$null
-    Write-Host "Configured: git config core.hooksPath .githooks" -ForegroundColor Green
+  $nativeErrorPrefVar = Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue
+  $nativeErrorPrefOld = $null
+  if ($null -ne $nativeErrorPrefVar) {
+    $nativeErrorPrefOld = $PSNativeCommandUseErrorActionPreference
+    $PSNativeCommandUseErrorActionPreference = $false
+  }
+
+  try {
+    $currentHooksPath = (& git -C $RepoRoot config core.hooksPath 2>$null | Out-String).Trim()
+    if ($currentHooksPath -ne ".githooks") {
+      $null = & git -C $RepoRoot config core.hooksPath .githooks 2>$null
+      if ($LASTEXITCODE -eq 0) {
+        Write-Host "Configured: git config core.hooksPath .githooks" -ForegroundColor Green
+      } else {
+        Write-Warning "Could not set git core.hooksPath automatically (permission denied or repo locked). Continuing."
+      }
+    }
+  } catch {
+    Write-Warning "Could not set git core.hooksPath automatically. Continuing."
+  } finally {
+    if ($null -ne $nativeErrorPrefVar) {
+      $PSNativeCommandUseErrorActionPreference = $nativeErrorPrefOld
+    }
   }
 }
 
@@ -140,7 +159,7 @@ Write-Host ""
 if ($EnableVector -and (-not $DryRun)) {
   Write-Host "Vector tools enabled ($VectorProvider):" -ForegroundColor Cyan
   Write-Host "  MCP tools: vector_search, vector_sync, vector_forget, vector_health, memory_status" -ForegroundColor DarkGray
-  Write-Host "  Rule: .cursor/rules/01-vector-search.mdc" -ForegroundColor DarkGray
+  Write-Host "  Rules: .cursor/rules/01-vector-search.mdc and .agent/rules/01-vector-search.md" -ForegroundColor DarkGray
   Write-Host "  MCP:  .cursor/mcp.json -> MnemoVector server" -ForegroundColor DarkGray
   Write-Host ""
   Write-Host "Autonomous memory runtime:" -ForegroundColor Cyan

package/memory_mac.sh

@@ -561,36 +561,12 @@ SEARCH FIRST, THEN FETCH:
 EOF
 
 # -------------------------
-# Multi-agent bridge files
+# Agent bridge files
 # -------------------------
 
 mkdir -p "$AGENT_RULES_DIR"
 
-write_file "$REPO_ROOT/CLAUDE.md" <<'EOF'
-# Project Memory (Mnemo)
-
-This project uses Mnemo for structured AI memory.
-Memory lives in `.cursor/memory/` as the single source of truth.
-
-## Read Order (ALWAYS)
-1. `.cursor/memory/hot-rules.md` - tiny invariants (<20 lines)
-2. `.cursor/memory/active-context.md` - current session state
-3. `.cursor/memory/memo.md` - long-term project truth + ownership
-
-## Search First, Then Fetch
-- `.cursor/memory/lessons/index.md` → find lesson ID → open only that lesson file
-- `.cursor/memory/digests/YYYY-MM.digest.md` → before raw journal archaeology
-- `.cursor/memory/journal/YYYY-MM.md` → only for deep history
-
-## After Any Feature/Fix
-1. Update `active-context.md` during work
-2. Add journal entry when done
-3. Create lesson if you discovered a pitfall
-4. Update `memo.md` if project truth changed
-5. Clear `active-context.md` when task is merged
-EOF
-
-write_file "$AGENT_RULES_DIR/memory-system.md" <<'EOF'
+write_file "$AGENT_RULES_DIR/00-memory-system.md" <<'EOF'
 ---
 description: Mnemo memory system - structured AI memory in .cursor/memory/
 alwaysApply: true
@@ -623,28 +599,6 @@ This project uses Mnemo for structured AI memory. All memory lives in `.cursor/m
 - Clear active-context.md when task is merged
 EOF
 
-write_file "$REPO_ROOT/AGENTS.md" <<'EOF'
-# Memory System (Mnemo)
-
-This project uses Mnemo for structured AI memory.
-Memory location: `.cursor/memory/`
-
-## Retrieval Order
-1. Read `.cursor/memory/hot-rules.md` first (tiny, <20 lines)
-2. Read `.cursor/memory/active-context.md` for current session
-3. Read `.cursor/memory/memo.md` for project truth + ownership
-4. Search `.cursor/memory/lessons/index.md` before creating new patterns
-5. Check `.cursor/memory/digests/` before raw journal archaeology
-
-## Authority Order (highest to lowest)
-1. Lessons override EVERYTHING
-2. active-context.md overrides memo/journal (but NOT lessons)
-3. memo.md is long-term project truth
-4. Journal is history
-5. Existing codebase
-6. New suggestions (lowest priority)
-EOF
-
 write_file "$MEM_SCRIPTS_DIR/customization.md" <<'EOF'
 # Mnemo Memory Customization Prompt (paste into an AI)
 
@@ -1867,9 +1821,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",
@@ -2202,6 +2217,32 @@ This rule supplements `00-memory-system.mdc` and does not replace governance.
 - `vector_forget` - remove stale entries.
 - `vector_health` - DB/API health check.
 
+## Fallback
+If vector search is unavailable, keep using:
+- `scripts/memory/query-memory.sh --query "..."`
+- `scripts/memory/query-memory.sh --query "..." --use-sqlite`
+EOF
+
+  write_file "$AGENT_RULES_DIR/01-vector-search.md" <<'EOF'
+---
+description: Mnemo vector semantic retrieval layer (optional)
+alwaysApply: true
+---
+
+# Vector Memory Layer (Optional)
+
+This rule supplements `00-memory-system.md` and does not replace governance.
+
+## Use vector tools when:
+- You do not know the exact keyword for prior context.
+- Keyword/FTS search did not find relevant history.
+
+## MCP tools
+- `vector_search` - semantic retrieval with cosine similarity.
+- `vector_sync` - incremental indexing.
+- `vector_forget` - remove stale entries.
+- `vector_health` - DB/API health check.
+
 ## Fallback
 If vector search is unavailable, keep using:
 - `scripts/memory/query-memory.sh --query "..."`
@@ -2344,25 +2385,13 @@ gi="$REPO_ROOT/.gitignore"
 GI_BEGIN="# >>> Mnemo (generated) - do not edit this block manually <<<"
 GI_END="# <<< Mnemo (generated) >>>"
 
-ignore_lines=".mnemo/memory/memory.sqlite
-.cursor/memory/memory.sqlite
-.mnemo/mcp/cursor.mcp.json
-.cursor/mcp.json"
-if [ "$ENABLE_VECTOR" = "1" ]; then
-  ignore_lines="$ignore_lines
-.mnemo/memory/mnemo_vector.sqlite
-.mnemo/memory/mnemo_vector.sqlite-journal
-.mnemo/memory/mnemo_vector.sqlite-wal
-.mnemo/memory/mnemo_vector.sqlite-shm
-.mnemo/memory/.sync.lock
-.mnemo/memory/.autonomy/
-.cursor/memory/mnemo_vector.sqlite
-.cursor/memory/mnemo_vector.sqlite-journal
-.cursor/memory/mnemo_vector.sqlite-wal
-.cursor/memory/mnemo_vector.sqlite-shm
-.cursor/memory/.sync.lock
-.cursor/memory/.autonomy/"
-fi
+ignore_lines=".mnemo/
+.cursor/memory/
+.cursor/rules/
+.cursor/mcp.json
+.agent/rules/
+scripts/memory/
+.githooks/"
 
 if [ "$DRY_RUN" = "1" ]; then
   echo "[DRY RUN] WOULD UPDATE: $gi (managed Mnemo block)"

package/package.json

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

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

@@ -13,28 +13,16 @@ function Update-MnemoGitignore {
   $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/memory/memory.sqlite",
-    ".cursor/memory/memory.sqlite",
-    ".mnemo/mcp/cursor.mcp.json",
-    ".cursor/mcp.json"
+    ".mnemo/",
+    ".cursor/memory/",
+    ".cursor/rules/",
+    ".cursor/mcp.json",
+    ".agent/rules/",
+    "scripts/memory/",
+    ".githooks/"
   )
-  if ($EnableVector) {
-    $ignoreLines += @(
-      ".mnemo/memory/mnemo_vector.sqlite",
-      ".mnemo/memory/mnemo_vector.sqlite-journal",
-      ".mnemo/memory/mnemo_vector.sqlite-wal",
-      ".mnemo/memory/mnemo_vector.sqlite-shm",
-      ".mnemo/memory/.sync.lock",
-      ".mnemo/memory/.autonomy/",
-      ".cursor/memory/mnemo_vector.sqlite",
-      ".cursor/memory/mnemo_vector.sqlite-journal",
-      ".cursor/memory/mnemo_vector.sqlite-wal",
-      ".cursor/memory/mnemo_vector.sqlite-shm",
-      ".cursor/memory/.sync.lock",
-      ".cursor/memory/.autonomy/"
-    )
-  }
 
   $giLineEndings = "CRLF"
   $giContent = ""

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

@@ -189,30 +189,6 @@ SEARCH FIRST, THEN FETCH:
 - When you discover a bug pattern -> suggest creating a lesson
 - When unsure about architecture -> check lessons/index.md first
 - Don't create parallel systems -> check memo.md ownership map
-"@
-
-  $claudeMd = @"
-# Project Memory (Mnemo)
-
-This project uses [Mnemo](https://github.com/DiNaSoR/Mnemo) for structured AI memory.
-Memory lives in ``.cursor/memory/`` as the single source of truth.
-
-## Read Order (ALWAYS)
-1. ``.cursor/memory/hot-rules.md`` - tiny invariants (<20 lines)
-2. ``.cursor/memory/active-context.md`` - current session state
-3. ``.cursor/memory/memo.md`` - long-term project truth + ownership
-
-## Search First, Then Fetch
-- ``.cursor/memory/lessons/index.md`` -> find lesson ID -> open only that lesson file
-- ``.cursor/memory/digests/YYYY-MM.digest.md`` -> before raw journal archaeology
-- ``.cursor/memory/journal/YYYY-MM.md`` -> only for deep history
-
-## After Any Feature/Fix
-1. Update ``active-context.md`` during work
-2. Add journal entry when done
-3. Create lesson if you discovered a pitfall
-4. Update ``memo.md`` if project truth changed
-5. Clear ``active-context.md`` when task is merged
 "@
 
   $static = @{
@@ -222,7 +198,6 @@ Memory lives in ``.cursor/memory/`` as the single source of truth.
     (Join-Path $Ctx.MemoryDir "memo.md")                       = $memo
     (Join-Path $Ctx.JournalDir "$month.md")                    = $journalMonth
     (Join-Path $Ctx.RulesDir "00-memory-system.mdc")           = $memoryRule
-    (Join-Path $Ctx.RepoRoot "CLAUDE.md")                      = $claudeMd
   }
 
   foreach ($kv in $static.GetEnumerator()) {
@@ -397,7 +372,7 @@ What did we choose?
 Tradeoffs, risks, follow-ups.
 "@ -ForceWrite:$Force
 
-  # Multi-agent bridges
+  # Agent bridge rules
   $geminiRule = @"
 ---
 description: Mnemo memory system - structured AI memory in .cursor/memory/
@@ -426,37 +401,7 @@ This project uses Mnemo for structured AI memory. All memory lives in ``.cursor/
 - Clear active-context.md when task is merged
 "@
 
-  $agentsMd = @"
-# Memory System (Mnemo)
-
-This project uses Mnemo for structured AI memory.
-Memory location: ``.cursor/memory/``
-
-## Retrieval Order
-1. Read ``.cursor/memory/hot-rules.md`` first (tiny, <20 lines)
-2. Read ``.cursor/memory/active-context.md`` for current session
-3. Read ``.cursor/memory/memo.md`` for project truth + ownership
-4. Search ``.cursor/memory/lessons/index.md`` before creating new patterns
-5. Check ``.cursor/memory/digests/`` before raw journal archaeology
-
-## Authority Order (highest to lowest)
-1. Lessons override EVERYTHING
-2. active-context.md overrides memo/journal (but NOT lessons)
-3. memo.md is long-term project truth
-4. Journal is history
-5. Existing codebase
-6. New suggestions (lowest priority)
-
-## After Any Feature/Fix
-- Update active-context.md during work (scratchpad)
-- Add journal entry to journal/YYYY-MM.md when done
-- Create lessons/L-XXX-title.md if you discovered a pitfall
-- Update memo.md if project truth changed
-- Clear active-context.md when task is merged
-"@
-
-  Write-MnemoFile (Join-Path $Ctx.MnemoRulesAgentDir "memory-system.md") $geminiRule -ForceWrite:$Force
-  Write-MnemoFile (Join-Path $Ctx.RepoRoot "AGENTS.md") $agentsMd -ForceWrite:$Force
+  Write-MnemoFile (Join-Path $Ctx.MnemoRulesAgentDir "00-memory-system.md") $geminiRule -ForceWrite:$Force
 
   Write-Host "`nMemory scaffold installed." -ForegroundColor Cyan
 }

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

@@ -99,5 +99,34 @@ If vector search is unavailable, keep using:
 
   Write-MnemoFile (Join-Path $Ctx.RulesDir "01-vector-search.mdc") $vectorRule -ForceWrite:$Force
 
+  $agentVectorRule = @"
+---
+description: Mnemo vector semantic retrieval layer (optional)
+alwaysApply: true
+---
+
+# Vector Memory Layer (Optional)
+
+This rule supplements ``00-memory-system.md`` and does not replace governance.
+
+## Use vector tools when:
+- You do not know the exact keyword for prior context.
+- Keyword/FTS search did not find relevant history.
+
+## MCP tools
+- ``vector_search`` - semantic retrieval with authority-aware reranking.
+- ``vector_sync`` - incremental indexing.
+- ``vector_forget`` - remove stale entries.
+- ``vector_health`` - DB/API health check.
+- ``memory_status`` - JSON summary for autonomous monitoring.
+
+## Fallback
+If vector search is unavailable, keep using:
+- ``scripts/memory/query-memory.ps1 -Query "..."``
+- ``scripts/memory/query-memory.ps1 -Query "..." -UseSqlite``
+"@
+
+  Write-MnemoFile (Join-Path $Ctx.MnemoRulesAgentDir "01-vector-search.md") $agentVectorRule -ForceWrite:$Force
+
   return $vectorPython
 }

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()