@jaguilar87/gaia 5.1.0 → 5.1.1

package/bin/cli/memory.py

@@ -13,10 +13,17 @@ Mutating subcommands operate on the curated ``memory`` table in
 ``~/.gaia/gaia.db`` (the project-level / user-level / feedback notes):
 
   add --name=<slug> --type=<project|user|feedback> --body="..."
-      [--description=...] [--workspace=<ws>] [--json]
+      [--description=...] [--workspace=<ws>]
+      [--project=<name> | --project-ref=<identity>] [--json]
                                           DB-only writer; no filesystem side
                                           effects (no .md under
                                           ~/.claude/projects/.../memory/).
+                                          --project anchors memory.project_ref
+                                          (N3, forward-only) by resolving a
+                                          project name within --workspace to
+                                          its stable project_identity; never
+                                          guesses (clear error if the project
+                                          does not exist or has no identity).
 """
 
 from __future__ import annotations
@@ -706,6 +713,8 @@ def _cmd_add(args) -> int:
     workspace = _resolve_workspace(getattr(args, "workspace", None))
     class_flag = getattr(args, "class_", None)
     status_flag = getattr(args, "status", None)
+    project_flag = getattr(args, "project", None)
+    project_ref_flag = getattr(args, "project_ref", None)
 
     if not name:
         return _err("--name is required", as_json)
@@ -731,7 +740,8 @@ def _cmd_add(args) -> int:
 
     try:
         from gaia.store.writer import (
-            upsert_memory, reclassify_memory, VALID_MEMORY_TYPES,
+            upsert_memory, reclassify_memory, resolve_project_ref,
+            VALID_MEMORY_TYPES,
         )
     except ImportError as exc:
         return _err(f"gaia.store.writer not importable: {exc}", as_json)
@@ -742,6 +752,19 @@ def _cmd_add(args) -> int:
             as_json,
         )
 
+    # N3: forward-only project_ref anchor. --project resolves a project name
+    # (within `workspace`) to its stable project_identity; --project-ref
+    # passes an already-known identity directly. Neither guesses: an
+    # unresolvable --project is a clear error, never a silent NULL.
+    project_ref = None
+    if project_flag is not None:
+        try:
+            project_ref = resolve_project_ref(workspace, project_flag)
+        except ValueError as exc:
+            return _err(str(exc), as_json)
+    elif project_ref_flag is not None:
+        project_ref = project_ref_flag
+
     try:
         res = upsert_memory(
             workspace,
@@ -749,6 +772,7 @@ def _cmd_add(args) -> int:
             type=mem_type,
             body=body,
             description=description,
+            project_ref=project_ref,
         )
     except ValueError as exc:
         return _err(str(exc), as_json)
@@ -796,6 +820,8 @@ def _cmd_add(args) -> int:
             "body_preview": snippet,
             "updated_at": res.get("updated_at"),
         }
+        if project_ref is not None:
+            out["project_ref"] = project_ref
         if reclassify_result is not None:
             out["class"] = reclassify_result["class"]
             out["memory_status"] = reclassify_result["memory_status"]
@@ -805,6 +831,8 @@ def _cmd_add(args) -> int:
         print(f"{verb} memory '{name}' (type={mem_type}, workspace={workspace})")
         if description:
             print(f"  description: {description}")
+        if project_ref is not None:
+            print(f"  project_ref: {project_ref}")
         print(f"  body: {snippet}")
         if reclassify_result is not None:
             print(
@@ -1004,6 +1032,9 @@ def _cmd_get_relevant(args) -> int:
                 "SELECT name, type, description, updated_at, class, status "
                 "FROM memory "
                 "WHERE workspace = ? "
+                # scan-v2 SV3: a soft-deleted (tombstoned) row must not be
+                # injected into the SessionStart memory block.
+                "  AND deleted_at IS NULL "
                 "  AND name NOT IN ("
                 "    SELECT dst_name FROM memory_links "
                 "    WHERE workspace = ? AND kind = 'supersedes'"
@@ -1384,18 +1415,27 @@ def _cmd_curated_show(args) -> int:
 
 
 def _cmd_delete(args) -> int:
-    """Hard-delete a curated memory row (FTS5 mirror cleared via trigger)."""
+    """Soft-delete (tombstone) a curated memory row -- scan-v2 SV3.
+
+    By default this is a SOFT delete: the row's ``deleted_at`` is stamped so the
+    row and its body survive (recoverable, invisible to reads). ``--hard``
+    performs the irreversible physical DELETE, reserved for explicit human
+    curation. Both paths keep the FTS5 mirror in sync via triggers.
+    """
     as_json = getattr(args, "json", False)
     workspace = _resolve_workspace(getattr(args, "workspace", None))
     name = args.name
     skip_confirm = getattr(args, "yes", False)
+    hard = getattr(args, "hard", False)
 
     try:
         from gaia.store.writer import get_memory, delete_memory
     except ImportError as exc:
         return _err(f"gaia.store.writer not importable: {exc}", as_json)
 
-    row = get_memory(workspace, name)
+    # For a hard delete we may target a row that is already tombstoned; reach it
+    # via include_deleted so a soft-then-hard flow works.
+    row = get_memory(workspace, name, include_deleted=hard)
     if row is None:
         return _err(
             f"memory '{name}' not found in workspace '{workspace}'",
@@ -1403,7 +1443,8 @@ def _cmd_delete(args) -> int:
         )
 
     if not skip_confirm:
-        prompt = f"Delete memory '{name}' (type={row['type']})? [y/N] "
+        verb = "HARD-delete (irreversible)" if hard else "delete (tombstone)"
+        prompt = f"{verb} memory '{name}' (type={row['type']})? [y/N] "
         try:
             answer = input(prompt)
         except EOFError:
@@ -1417,7 +1458,7 @@ def _cmd_delete(args) -> int:
             return 0
 
     try:
-        deleted = delete_memory(workspace, name)
+        deleted = delete_memory(workspace, name, hard=hard)
     except PermissionError as exc:
         return _err(str(exc), as_json)
     if not deleted:
@@ -1426,15 +1467,18 @@ def _cmd_delete(args) -> int:
             as_json,
         )
 
+    mode = "hard" if hard else "tombstone"
     if as_json:
         print(json.dumps({
             "deleted": True,
+            "mode": mode,
             "name": name,
             "workspace": workspace,
             "previous_type": row["type"],
         }, indent=2, default=str))
     else:
-        print(f"Deleted memory '{name}' (workspace={workspace!r}, "
+        verb = "Hard-deleted" if hard else "Tombstoned"
+        print(f"{verb} memory '{name}' (workspace={workspace!r}, "
               f"previous_type={row['type']!r})")
     return 0
 
@@ -1937,10 +1981,18 @@ def register(subparsers):
     # -- delete -------------------------------------------------------------
     delete_p = actions.add_parser(
         "delete",
-        help="Hard-delete a curated memory row",
-        description="Drop the row; the FTS5 mirror is cleared via trigger.",
+        help="Soft-delete (tombstone) a curated memory row; --hard to purge",
+        description=(
+            "Tombstone the row by default (deleted_at stamped; row + body "
+            "survive, invisible to reads, recoverable). Use --hard for the "
+            "irreversible physical DELETE (explicit human curation only)."
+        ),
         formatter_class=_argparse.RawDescriptionHelpFormatter,
-        epilog="Examples:\n  gaia memory delete project_old --yes\n",
+        epilog=(
+            "Examples:\n"
+            "  gaia memory delete project_old --yes\n"
+            "  gaia memory delete project_old --hard --yes\n"
+        ),
     )
     delete_p.add_argument("name", help="Curated memory slug.")
     delete_p.add_argument("--workspace", default=None, metavar="W",
@@ -1949,6 +2001,11 @@ def register(subparsers):
         "--yes", action="store_true", default=False,
         help="Skip confirm prompt. bool. Default: false.",
     )
+    delete_p.add_argument(
+        "--hard", action="store_true", default=False,
+        help="Physically DELETE the row (irreversible). Default: false "
+             "(soft-delete/tombstone).",
+    )
     delete_p.add_argument(
         "--json", action="store_true", default=False,
         help="Emit JSON. bool.",
@@ -2131,6 +2188,25 @@ def register(subparsers):
     )
     add_p.add_argument("--description", default=None,
                        help="Short summary. Shown in list.")
+    _add_project_group = add_p.add_mutually_exclusive_group()
+    _add_project_group.add_argument(
+        "--project", default=None,
+        help=(
+            "N3: anchor this memory to a project by NAME (resolved within "
+            "--workspace to its stable projects.project_identity, persisted "
+            "as memory.project_ref). Forward-only: errors clearly if the "
+            "project does not exist or has no project_identity yet -- never "
+            "guesses. Mutually exclusive with --project-ref."
+        ),
+    )
+    _add_project_group.add_argument(
+        "--project-ref", dest="project_ref", default=None,
+        help=(
+            "N3: anchor this memory directly to a known stable "
+            "project_identity string, bypassing name resolution. Use "
+            "--project instead unless you already hold the identity value."
+        ),
+    )
     add_p.add_argument(
         "--class", dest="class_", default=None,
         choices=("anchor", "thread", "log"),