memorytalk 0.9.2__tar.gz → 0.9.3__tar.gz

{memorytalk-0.9.2 → memorytalk-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorytalk
-Version: 0.9.2
+Version: 0.9.3
 Summary: Persistent cross-session memory for AI agents — Talk-Card architecture with forum-dynamics sinking/floating (v3)
 License-Expression: Apache-2.0
 Requires-Python: >=3.10

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/api/cards.py

@@ -12,11 +12,12 @@ import datetime as _dt
 from fastapi import APIRouter, HTTPException, Query, Request
 
 from memorytalk.schemas import (
-    CardListResponse, CardMeta, CardTagResponse,
+    CardDeleteResponse, CardListResponse, CardMeta, CardTagResponse,
     CreateCardRequest, CreateCardResponse,
     TagPatchRequest,
 )
 from memorytalk.service import CardConflict, CardServiceError
+from memorytalk.service.cards import CardNotFound
 from memorytalk.util.tag_filter import parse_tag_arg
 from memorytalk.util.tags import TagValidationError, apply_patch
 
@@ -142,3 +143,24 @@ async def patch_card_tags(
                 status_code=404, detail=f"card {card_id!r} not found",
             )
     return CardTagResponse(card_id=card_id, tags=merged)
+
+
+@router.delete("/cards/{card_id}", response_model=CardDeleteResponse)
+async def delete_card(card_id: str, request: Request) -> CardDeleteResponse:
+    """Hard-delete a card: SQLite row + reviews + outbound source_cards
+    + vector embedding + per-card filesystem dir.
+
+    Inbound source_cards (other cards that reference this one) are NOT
+    cascaded — they become dangling references, which the response
+    surfaces as ``inbound_refs_dangling`` so callers can warn the
+    user. recall_event rows that mention this card_id are NOT touched
+    — they're historical records, deleting the card doesn't rewrite
+    history."""
+    svc = request.app.state.cards
+    if svc is None:
+        raise HTTPException(status_code=503, detail="cards service unavailable")
+    try:
+        result = await svc.delete(card_id)
+    except CardNotFound as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    return CardDeleteResponse(**result)

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/cli/_format.py

@@ -858,6 +858,30 @@ def fmt_card_list(payload: dict, filter_summary: str = "") -> str:
     return "\n".join(lines).rstrip() + "\n"
 
 
+def fmt_card_delete(payload: dict) -> str:
+    """Render DELETE /v3/cards/<cid> response.
+
+    One-line confirmation + a hint about inbound-ref dangling when
+    applicable. We deliberately don't moan about every detail (vector
+    cleared / files cleared / etc.) — those are best-effort and
+    typically silent."""
+    cid = payload.get("card_id") or "?"
+    reviews = int(payload.get("reviews_deleted", 0) or 0)
+    dangling = int(payload.get("inbound_refs_dangling", 0) or 0)
+
+    bits = [f"deleted · `{cid}`"]
+    if reviews:
+        bits.append(
+            f"{reviews} review{'s' if reviews != 1 else ''} removed",
+        )
+    if dangling:
+        bits.append(
+            f"⚠ {dangling} inbound `source_cards` reference"
+            f"{'s' if dangling != 1 else ''} now dangling",
+        )
+    return " · ".join(bits) + "\n"
+
+
 def fmt_card_tag(payload: dict, *, is_query: bool) -> str:
     """Render PATCH /v3/cards/<cid>/tags response.
 

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/cli/card.py

@@ -1,6 +1,6 @@
-"""CLI: memory.talk card {create, list, tag} — card write + maintenance.
+"""CLI: memory.talk card {create, list, tag, delete} — card write + maintenance.
 
-Three subcommands:
+Subcommands:
 
   create  write a new immutable card (was the bare ``card '<json>'`` form
           in 0.7.x; hard-renamed in 0.8.x because the top level now hosts
@@ -8,6 +8,7 @@ Three subcommands:
   list    multi-filter listing (tag / created_at) — no source/cwd: cards
           aren't from a source the way sessions are
   tag     query / set / unset kv tags on one card
+  delete  hard-delete a card (SQLite row + reviews + vector + files)
 
 The HTTP-call shape is identical to ``cli/session.py`` — both go through
 the same ``api()`` helper and share fmt_/parse_ helpers. See
@@ -20,7 +21,7 @@ import sys
 import click
 
 from memorytalk.cli._format import (
-    fmt_card_created, fmt_card_list, fmt_card_tag, fmt_error,
+    fmt_card_created, fmt_card_delete, fmt_card_list, fmt_card_tag, fmt_error,
 )
 from memorytalk.cli._http import ApiError, api, extract_error_message
 from memorytalk.cli._render import emit_json, emit_json_err, emit_md, emit_md_err
@@ -33,7 +34,7 @@ from memorytalk.util.tags import TagValidationError, parse_kv_args
 
 @click.group("card")
 def card() -> None:
-    """Card write + maintenance: create / list / tag."""
+    """Card write + maintenance: create / list / tag / delete."""
 
 
 # ────────── card create ──────────
@@ -159,6 +160,68 @@ def tag(card_id: str, kv_args: tuple[str, ...], json_out: bool) -> None:
         emit_md(fmt_card_tag(result, is_query=is_query))
 
 
+# ────────── card delete ──────────
+
+@card.command("delete")
+@click.argument("card_id")
+@click.option("--yes", "-y", is_flag=True, default=False,
+              help="Skip the interactive confirmation prompt.")
+@click.option("--json", "json_out", is_flag=True, default=False,
+              help="Emit JSON")
+def delete(card_id: str, yes: bool, json_out: bool) -> None:
+    """Hard-delete a card: SQLite row + reviews + outbound source_cards
+    + vector + per-card filesystem dir.
+
+    Other cards that reference this one via ``source_cards`` are NOT
+    cascaded — their references become dangling. ``recall_event``
+    history that mentions this card is NOT rewritten (history is
+    history). Pass ``--yes`` to skip the confirm prompt.
+    """
+    cfg = Config()
+
+    # Interactive path: pre-fetch the card to show the user WHAT they're
+    # about to delete (insight + created + reviews count). The DELETE
+    # response also surfaces those numbers, but only after the deed.
+    if not yes and not json_out:
+        try:
+            preview = api("POST", "/v3/read", cfg, json_body={"id": card_id})
+        except ApiError as e:
+            emit_md_err(fmt_error(extract_error_message(e.payload)))
+            sys.exit(1)
+        except Exception as e:
+            _emit_err(json_out, f"cannot reach server: {e}")
+            sys.exit(1)
+
+        card_doc = preview.get("card") or {}
+        reviews = card_doc.get("reviews") or []
+        click.echo("", err=True)
+        click.echo(f"card delete · {card_id}", err=True)
+        click.echo(f"  insight:  {card_doc.get('insight', '?')}", err=True)
+        click.echo(f"  created:  {card_doc.get('created_at', '?')}", err=True)
+        click.echo(f"  reviews:  {len(reviews)} (will be deleted with the card)", err=True)
+        click.echo("", err=True)
+        if not click.confirm("Delete this card?", default=False, err=True):
+            click.echo("aborted.", err=True)
+            sys.exit(1)
+
+    try:
+        result = api("DELETE", f"/v3/cards/{card_id}", cfg)
+    except ApiError as e:
+        if json_out:
+            emit_json_err(e.payload)
+        else:
+            emit_md_err(fmt_error(extract_error_message(e.payload)))
+        sys.exit(1)
+    except Exception as e:
+        _emit_err(json_out, f"cannot reach server: {e}")
+        sys.exit(1)
+
+    if json_out:
+        emit_json(result)
+    else:
+        emit_md(fmt_card_delete(result))
+
+
 # ────────── helpers ──────────
 
 def _summarize_filters(

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/provider/storage.py

@@ -5,12 +5,13 @@ domain code. Domain operations like "write a session's meta.json" live
 in ``repository/<kind>.py`` and call into Storage with full keys.
 
 Primitives:
-- ``write_text(key, content)`` — atomic put
-- ``read_text(key)``           — get; None if missing
-- ``append_text(key, content)``— append-only (caller pre-formats lines)
-- ``exists(key)``              — head
-- ``delete(key)``              — best-effort; missing is OK
-- ``list_subkeys(prefix)``     — recursive list of file keys under prefix
+- ``write_text(key, content)``  — atomic put
+- ``read_text(key)``            — get; None if missing
+- ``append_text(key, content)`` — append-only (caller pre-formats lines)
+- ``exists(key)``               — head
+- ``delete(key)``               — best-effort; missing is OK
+- ``delete_prefix(prefix)``     — recursive rmtree; missing prefix is OK
+- ``list_subkeys(prefix)``      — recursive list of file keys under prefix
 
 Keys are forward-slash strings rooted at the data root, e.g.
 ``sessions/claude-code/la/sess_lancedb/meta.json``.
@@ -29,6 +30,7 @@ class Storage(Protocol):
     async def append_text(self, key: str, content: str) -> None: ...
     async def exists(self, key: str) -> bool: ...
     async def delete(self, key: str) -> None: ...
+    async def delete_prefix(self, prefix: str) -> None: ...
     async def list_subkeys(self, prefix: str) -> list[str]: ...
 
 
@@ -76,6 +78,21 @@ class LocalStorage:
         except FileNotFoundError:
             pass
 
+    async def delete_prefix(self, prefix: str) -> None:
+        """Recursively remove the directory at ``prefix``. Missing prefix
+        is OK (no-op). Synchronous ``shutil.rmtree`` is fine here — the
+        IO is one syscall per inode, no fan-out worth offloading."""
+        import shutil
+        p = self._path(prefix)
+        if not p.exists():
+            return
+        if p.is_file():
+            # Defensive — caller probably meant ``delete`` for a single
+            # file; do the obvious thing rather than refuse.
+            p.unlink()
+            return
+        shutil.rmtree(p)
+
     async def list_subkeys(self, prefix: str) -> list[str]:
         base = self._path(prefix)
         if not base.exists():

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/repository/cards.py

@@ -32,6 +32,12 @@ class CardStore:
         raw = card_id[len("card_"):] if card_id.startswith("card_") else card_id
         return (raw[:2] if len(raw) >= 2 else raw).lower()
 
+    def _card_dir_key(self, card_id: str) -> str:
+        """Per-card directory prefix; used by ``delete_files`` to rmtree
+        the whole card footprint (card.json + events.jsonl + reviews.jsonl
+        + tags.json) in one shot."""
+        return f"{self.PREFIX}/{self._bucket(card_id)}/{card_id}"
+
     def _doc_key(self, card_id: str) -> str:
         return f"{self.PREFIX}/{self._bucket(card_id)}/{card_id}/card.json"
 
@@ -229,6 +235,48 @@ class CardStore:
             rows = await cursor.fetchall()
         return [{"card_id": r["source_card_id"], "relation": r["relation"]} for r in rows]
 
+    async def count_inbound_refs(self, card_id: str) -> int:
+        """How many *other* cards reference this card via source_cards
+        (i.e. would be left with a dangling reference if we delete it).
+        Covered by ``idx_csc_source``."""
+        async with self.conn.execute(
+            "SELECT COUNT(*) FROM card_source_cards WHERE source_card_id = ?",
+            (card_id,),
+        ) as cursor:
+            row = await cursor.fetchone()
+        return row[0]
+
+    # ────────── delete (0.9.x) ──────────
+
+    async def delete(self, card_id: str) -> None:
+        """Atomic SQLite tx removing the card row + everything 1:1 with it
+        (``card_stats``, outbound ``card_source_cards``). Caller is
+        responsible for reviews (separate store) + vector + files.
+
+        ``card_source_cards`` rows where ``source_card_id = card_id``
+        (inbound refs) are intentionally LEFT IN PLACE — see
+        ``count_inbound_refs``. The other card's "references this one"
+        link becomes dangling, but cascading deletes upstream would
+        be a destructive surprise."""
+        # Single transaction so a mid-flight failure leaves no
+        # half-state (no orphan card_stats / source_cards rows).
+        await self.conn.execute(
+            "DELETE FROM card_source_cards WHERE card_id = ?", (card_id,),
+        )
+        await self.conn.execute(
+            "DELETE FROM card_stats WHERE card_id = ?", (card_id,),
+        )
+        await self.conn.execute(
+            "DELETE FROM cards WHERE card_id = ?", (card_id,),
+        )
+        await self.conn.commit()
+
+    async def delete_files(self, card_id: str) -> None:
+        """Recursively remove the card's per-card directory (card.json,
+        events.jsonl, reviews.jsonl, tags.json). Best-effort — missing
+        directory is a no-op."""
+        await self.storage.delete_prefix(self._card_dir_key(card_id))
+
     # ─── 0.8.x: list + user-side tags ──────────────────────────────
 
     async def list_cards(

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/repository/reviews.py

@@ -44,6 +44,19 @@ class ReviewStore:
             rows = await cursor.fetchall()
         return [dict(r) for r in rows]
 
+    async def delete_for_card(self, card_id: str) -> int:
+        """Delete all reviews of a card. Returns the number of rows
+        removed (so the service layer can report it in the response).
+
+        Used by ``CardService.delete``; reviews-of-a-deleted-card make
+        no sense and ``reviews.card_id`` FK has no ON DELETE CASCADE."""
+        async with self.conn.execute(
+            "DELETE FROM reviews WHERE card_id = ?", (card_id,),
+        ) as cursor:
+            n = cursor.rowcount
+        await self.conn.commit()
+        return n
+
     async def count(self) -> int:
         async with self.conn.execute("SELECT COUNT(*) FROM reviews") as cursor:
             row = await cursor.fetchone()

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/schemas/__init__.py

@@ -1,7 +1,7 @@
 """Pydantic schemas — request / response shapes for the v3 HTTP API."""
 from memorytalk.schemas.card import Card, CardStats, SourceCard, CardRound
 from memorytalk.schemas.cards import (
-    CardListResponse, CardMeta, CardRoundRef, CardTagResponse,
+    CardDeleteResponse, CardListResponse, CardMeta, CardRoundRef, CardTagResponse,
     CreateCardRequest, CreateCardResponse,
 )
 from memorytalk.schemas.read import ReadRequest, ReadResponse
@@ -34,7 +34,8 @@ from memorytalk.schemas.sync import (
 
 __all__ = [
     "Card", "CardStats", "SourceCard", "CardRound",
-    "CardListResponse", "CardMeta", "CardRoundRef", "CardTagResponse",
+    "CardDeleteResponse", "CardListResponse", "CardMeta", "CardRoundRef",
+    "CardTagResponse",
     "CreateCardRequest", "CreateCardResponse",
     "ReadRequest", "ReadResponse",
     "RecalledCard", "RecallRequest", "RecallResponse",

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/schemas/cards.py

@@ -65,6 +65,21 @@ class CardListResponse(BaseModel):
     cards: list[CardMeta] = Field(default_factory=list)
 
 
+class CardDeleteResponse(BaseModel):
+    """Response for ``DELETE /v3/cards/{card_id}``.
+
+    ``reviews_deleted`` and ``inbound_refs_dangling`` give the caller
+    enough information to surface the blast radius. We don't return a
+    ``files_deleted`` / ``vector_deleted`` because those are
+    best-effort cleanup; from the user's POV the card IS gone."""
+    card_id: str
+    reviews_deleted: int = 0
+    # Number of OTHER cards that referenced this one via source_cards.
+    # Those references now dangle (cards point at a missing card_id).
+    # Not cascaded by design — see docs/structure/v3/talk-card.md.
+    inbound_refs_dangling: int = 0
+
+
 class CardTagResponse(BaseModel):
     """Response of ``PATCH /v3/cards/{cid}/tags`` — full post-merge
     tag dict. Mirrors :class:`TagResponse` in shape; we keep them as

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/service/__init__.py

@@ -1,10 +1,10 @@
 """Service layer — orchestrates repository + provider; one class per noun."""
 from memorytalk.service.cards import (
-    CardConflict, CardService, CardServiceError,
+    CardConflict, CardNotFound, CardService, CardServiceError,
 )
 from memorytalk.service.events import EventWriter
 from memorytalk.service.read import (
-    CardNotFound, ReadService, SessionNotFound, ReadServiceError,
+    ReadService, SessionNotFound, ReadServiceError,
 )
 from memorytalk.service.recall import RecallService, RecallServiceError
 from memorytalk.service.reviews import (

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/service/cards.py

@@ -27,6 +27,7 @@ Append-only & DAG invariants:
 """
 from __future__ import annotations
 import datetime as _dt
+import logging
 
 from memorytalk.provider.embedding import Embedder
 from memorytalk.provider.lancedb import LanceStore
@@ -42,6 +43,8 @@ from memorytalk.util.tags import TagValidationError, validate_tag_dict
 
 _ALLOWED_RELATIONS = {"derives_from", "supersedes"}
 
+_log = logging.getLogger(__name__)
+
 
 class CardServiceError(Exception):
     """4xx-equivalent: validation failed, request rejected."""
@@ -51,6 +54,10 @@ class CardConflict(CardServiceError):
     """409-equivalent: the supplied card_id already exists."""
 
 
+class CardNotFound(CardServiceError):
+    """404-equivalent: card_id doesn't exist."""
+
+
 def _utc_iso() -> str:
     return _dt.datetime.now(_dt.UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
 
@@ -169,6 +176,68 @@ class CardService:
 
         return card_id
 
+    # ──────── delete ────────
+
+    async def delete(self, card_id: str) -> dict:
+        """Remove a card from SQLite + vector + file. Idempotent in the
+        sense that re-calling on an already-deleted id raises CardNotFound
+        (not a silent no-op — callers should not call us twice).
+
+        Order matters:
+
+          1. Read summary (reviews count + inbound refs) for response.
+          2. Delete reviews (separate store, no FK cascade).
+          3. Delete SQLite card rows (cards + card_stats + outbound
+             source_cards, atomic).
+          4. Delete LanceDB vector (best-effort — orphan rows are
+             filtered out at search time by ``card_row is None`` checks).
+          5. Delete filesystem dir (best-effort — orphan dirs are
+             cosmetic, no read path scans them).
+
+        Steps 4 + 5 are best-effort: by the time we get there SQLite has
+        already committed the deletion, and reverting it would leave us
+        with a card the user thinks is gone but vector/files still show
+        up in odd places. Failures get logged; the response still says
+        "deleted" because from the user's POV it IS deleted. Cleanup
+        scripts handle the orphans later.
+        """
+        row = await self.db.cards.get(card_id)
+        if row is None:
+            raise CardNotFound(f"card {card_id} not found")
+
+        inbound = await self.db.cards.count_inbound_refs(card_id)
+
+        # 1. Reviews first — separate store, no FK cascade.
+        reviews_deleted = await self.db.reviews.delete_for_card(card_id)
+
+        # 2. SQLite — atomic across cards / card_stats / outbound source_cards.
+        await self.db.cards.delete(card_id)
+
+        # 3. Vector — best-effort.
+        if self.vectors is not None:
+            try:
+                await self.vectors.delete_cards([card_id])
+            except Exception as e:  # noqa: BLE001
+                _log.warning(
+                    "vector delete failed for %s; card_row is None will "
+                    "filter orphan at search time: %s", card_id, e,
+                )
+
+        # 4. Files — best-effort.
+        try:
+            await self.db.cards.delete_files(card_id)
+        except Exception as e:  # noqa: BLE001
+            _log.warning(
+                "file delete failed for %s; orphan dir is cosmetic: %s",
+                card_id, e,
+            )
+
+        return {
+            "card_id": card_id,
+            "reviews_deleted": reviews_deleted,
+            "inbound_refs_dangling": inbound,
+        }
+
     # ──────── helpers ────────
 
     async def _expand_rounds(self, refs) -> tuple[list[dict], list[tuple[str, str]]]:

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk/service/read.py

@@ -19,6 +19,10 @@ from memorytalk.repository import SQLiteStore
 from memorytalk.schemas import (
     Card, CardRound, CardStats, ContentBlock, Review, Round, Session, SourceCard,
 )
+# CardNotFound is owned by service.cards (the card service is the canonical
+# place for card lifecycle errors); re-exported here for callers that
+# historically imported it from service.read.
+from memorytalk.service.cards import CardNotFound
 from memorytalk.service.events import EventWriter
 
 
@@ -26,10 +30,6 @@ class ReadServiceError(Exception):
     """Base for read service errors."""
 
 
-class CardNotFound(ReadServiceError):
-    pass
-
-
 class SessionNotFound(ReadServiceError):
     pass
 

{memorytalk-0.9.2 → memorytalk-0.9.3}/memorytalk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorytalk
-Version: 0.9.2
+Version: 0.9.3
 Summary: Persistent cross-session memory for AI agents — Talk-Card architecture with forum-dynamics sinking/floating (v3)
 License-Expression: Apache-2.0
 Requires-Python: >=3.10

{memorytalk-0.9.2 → memorytalk-0.9.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memorytalk"
-version = "0.9.2"
+version = "0.9.3"
 description = "Persistent cross-session memory for AI agents — Talk-Card architecture with forum-dynamics sinking/floating (v3)"
 readme = "README.md"
 requires-python = ">=3.10"