forgetted 0.2.0__py3-none-any.whl

forgetted/__init__.py

@@ -0,0 +1,41 @@
+"""
+forgetted — Selective memory governance for AI agents.
+
+Branch the timeline, but never merge back.
+
+When triggered, forgetted:
+1. Checkpoints the current session context into a resumption file
+2. Blocks all persistence layers via registered adapters
+3. Self-cleans on exit (session logs, leaked memories)
+4. Enables seamless resume from the checkpoint in the next session
+
+This is not incognito mode. This is a fork without consequence —
+a memory architecture primitive that gives users control over
+what becomes part of their agent's memory.
+
+Author: Hermes Labs
+License: Apache-2.0
+"""
+
+from .adapters.base import PersistenceAdapter
+from .adapters.file_write import FileWriteAdapter
+from .checkpoint import create_checkpoint, load_checkpoint
+from .cleaner import delete_session_log, find_session_log
+from .guard import ForgetGuard
+from .session import ForgetSession
+from .trigger import TRIGGERS, is_forget_trigger
+
+__version__ = "0.2.0"
+__author__ = "Hermes Labs"
+__all__ = [
+    "create_checkpoint",
+    "delete_session_log",
+    "FileWriteAdapter",
+    "find_session_log",
+    "ForgetGuard",
+    "ForgetSession",
+    "is_forget_trigger",
+    "load_checkpoint",
+    "PersistenceAdapter",
+    "TRIGGERS",
+]

forgetted/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""
+forgetted.adapters — Persistence layer adapters.
+
+Built-in adapters:
+    - FileWriteAdapter: blocks file writes via builtins.open patch
+    - Mem0Adapter: blocks mem0 add/update (requires mem0ai)
+
+Custom adapters: subclass ``PersistenceAdapter`` from ``forgetted.adapters.base``.
+"""
+
+from .base import PersistenceAdapter
+from .file_write import FileWriteAdapter
+
+__all__ = [
+    "PersistenceAdapter",
+    "FileWriteAdapter",
+]
+
+# Optional adapters — import only if deps are available.
+try:
+    from .mem0 import Mem0Adapter  # noqa: F401
+
+    __all__.append("Mem0Adapter")
+except ImportError:
+    pass

forgetted/adapters/base.py

@@ -0,0 +1,72 @@
+"""
+forgetted.adapters.base — Abstract base for persistence adapters.
+
+Every persistence layer that forgetted can control implements this interface.
+Adapters are registered with a ForgetSession, which calls disable/enable/cleanup
+at the appropriate times.
+
+To write a custom adapter::
+
+    from forgetted.adapters.base import PersistenceAdapter
+
+    class MyVectorDBAdapter(PersistenceAdapter):
+        name = "my-vector-db"
+
+        def disable(self):
+            self._client.pause_writes()
+            self._active = False
+
+        def enable(self):
+            self._client.resume_writes()
+            self._active = True
+
+        def cleanup(self):
+            self._client.delete_since(self._window_start)
+"""
+
+from abc import ABC, abstractmethod
+
+
+class PersistenceAdapter(ABC):
+    """Interface for a persistence layer that forgetted can control.
+
+    Subclasses must implement ``disable``, ``enable``, ``cleanup``,
+    and the ``name`` and ``is_active`` properties.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable identifier for this adapter (e.g., 'mem0', 'file-write')."""
+
+    @property
+    @abstractmethod
+    def is_active(self) -> bool:
+        """True when writes are being blocked (adapter is in disabled/forgetted state)."""
+
+    @abstractmethod
+    def disable(self) -> None:
+        """Block writes through this persistence layer.
+
+        Called when a forgetted window starts. Must be idempotent —
+        calling disable() twice should not error.
+        """
+
+    @abstractmethod
+    def enable(self) -> None:
+        """Restore normal write behavior.
+
+        Called when a forgetted window ends. Must be idempotent —
+        calling enable() twice should not error.
+        """
+
+    @abstractmethod
+    def cleanup(self) -> None:
+        """Remove any data that leaked through during the forgetted window.
+
+        Called after enable(). This is the post-window sweep — delete
+        any memories, embeddings, or logs that were written despite
+        the disable() call (e.g., by framework-level code).
+
+        Must be safe to call even if nothing leaked (no-op in that case).
+        """

forgetted/adapters/file_write.py

@@ -0,0 +1,53 @@
+"""
+forgetted.adapters.file_write — File write blocking adapter.
+
+Wraps the existing ForgetGuard (builtins.open monkey-patch) as a
+PersistenceAdapter. This is the safety-net layer — it catches writes
+that slip past higher-level adapters.
+"""
+
+import logging
+from typing import Optional
+
+from ..guard import ForgetGuard
+from .base import PersistenceAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class FileWriteAdapter(PersistenceAdapter):
+    """Adapter that blocks file writes to protected workspace paths.
+
+    Parameters
+    ----------
+    workspace_path : str
+        Absolute path to the agent workspace root.
+    extra_protected : set[str], optional
+        Additional relative paths or directory names to protect.
+    """
+
+    def __init__(self, workspace_path: str, extra_protected: Optional[set[str]] = None):
+        self._guard = ForgetGuard(workspace_path, extra_protected)
+
+    @property
+    def name(self) -> str:
+        return "file-write"
+
+    @property
+    def is_active(self) -> bool:
+        return self._guard.active
+
+    def disable(self) -> None:
+        self._guard.start()
+
+    def enable(self) -> None:
+        self._guard.stop()
+
+    def cleanup(self) -> None:
+        # No cleanup needed — writes were blocked, not captured.
+        pass
+
+    @property
+    def blocked_count(self) -> int:
+        """Number of write attempts blocked during the current/last window."""
+        return self._guard.blocked_count

forgetted/adapters/mem0.py

@@ -0,0 +1,127 @@
+"""
+forgetted.adapters.mem0 — mem0 semantic memory adapter.
+
+Disables mem0 writes during a forgetted window by monkey-patching the
+Memory instance's ``add`` and ``update`` methods. On cleanup, deletes
+any memories added during the window (by timestamp comparison).
+
+Requires: ``pip install mem0ai`` (optional dependency).
+"""
+
+import logging
+import time
+from typing import Any
+
+from .base import PersistenceAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class Mem0Adapter(PersistenceAdapter):
+    """Adapter for mem0 (semantic memory layer).
+
+    Parameters
+    ----------
+    memory : object
+        A mem0 ``Memory`` instance. The adapter patches its ``add``
+        and ``update`` methods during the forgetted window.
+    user_id : str, optional
+        mem0 user ID for scoped cleanup queries.
+
+    Example
+    -------
+    ::
+
+        from mem0 import Memory
+        from forgetted.adapters.mem0 import Mem0Adapter
+
+        m = Memory()
+        adapter = Mem0Adapter(m, user_id="roli")
+    """
+
+    def __init__(self, memory: Any, user_id: str = "default"):
+        self._memory = memory
+        self._user_id = user_id
+        self._original_add = None
+        self._original_update = None
+        self._active = False
+        self._window_start: float = 0
+
+    @property
+    def name(self) -> str:
+        return "mem0"
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    def disable(self) -> None:
+        if self._active:
+            return
+        self._window_start = time.time()
+        self._original_add = self._memory.add
+        self._original_update = getattr(self._memory, "update", None)
+
+        def _noop_add(*args, **kwargs):
+            logger.debug("🫥 mem0 add blocked during forgetted window")
+            return {"results": [], "blocked_by": "forgetted"}
+
+        def _noop_update(*args, **kwargs):
+            logger.debug("🫥 mem0 update blocked during forgetted window")
+            return {"results": [], "blocked_by": "forgetted"}
+
+        self._memory.add = _noop_add
+        if self._original_update is not None:
+            self._memory.update = _noop_update
+
+        self._active = True
+        logger.info("🫥 mem0 adapter disabled — add/update blocked")
+
+    def enable(self) -> None:
+        if not self._active:
+            return
+        self._memory.add = self._original_add
+        if self._original_update is not None:
+            self._memory.update = self._original_update
+        self._original_add = None
+        self._original_update = None
+        self._active = False
+        logger.info("🫥 mem0 adapter enabled — normal writes restored")
+
+    def cleanup(self) -> None:
+        """Delete any memories that leaked through during the window.
+
+        Queries mem0 for memories created after ``_window_start`` and
+        deletes them. This catches writes made by framework code that
+        bypassed the patched methods.
+        """
+        if self._window_start == 0:
+            return
+
+        try:
+            # mem0's get_all returns memories with metadata including created_at
+            all_memories = self._memory.get_all(user_id=self._user_id)
+            if not all_memories:
+                return
+
+            # Handle both dict and list response formats
+            memories = all_memories if isinstance(all_memories, list) else all_memories.get("results", [])
+            deleted = 0
+            for mem in memories:
+                created = mem.get("created_at", 0)
+                # mem0 uses ISO timestamps or epoch — handle both
+                if isinstance(created, str):
+                    continue  # Skip string timestamps for now — timestamp comparison is fragile
+                if created >= self._window_start:
+                    try:
+                        self._memory.delete(mem["id"])
+                        deleted += 1
+                    except Exception as exc:
+                        logger.warning("🫥 Failed to delete mem0 memory %s: %s", mem.get("id"), exc)
+
+            if deleted:
+                logger.info("🫥 mem0 cleanup: deleted %d memories from forgetted window", deleted)
+        except Exception as exc:
+            logger.warning("🫥 mem0 cleanup failed (non-fatal): %s", exc)
+        finally:
+            self._window_start = 0

forgetted/checkpoint.py

@@ -0,0 +1,82 @@
+"""
+forgetted.checkpoint — Checkpoint creation and resume logic.
+
+Before entering forgetted mode, the agent saves a compact summary of the
+current session state.  On the next normal session, the checkpoint is loaded
+(providing continuity) and then deleted (single-use).
+
+Checkpoint files live at ``<workspace>/memory/forgetted-checkpoint.md``.
+"""
+
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_CHECKPOINT_FILENAME = "forgetted-checkpoint.md"
+
+
+def create_checkpoint(context_summary: str, workspace: str) -> Path:
+    """Write a compact resumption file before entering forgetted mode.
+
+    Parameters
+    ----------
+    context_summary : str
+        A concise summary of the current session context — open tasks,
+        last topic discussed, any pending decisions.
+    workspace : str
+        Absolute path to the agent workspace root.
+
+    Returns
+    -------
+    Path
+        Absolute path to the created checkpoint file.
+    """
+    memory_dir = Path(workspace) / "memory"
+    memory_dir.mkdir(parents=True, exist_ok=True)
+
+    checkpoint_path = memory_dir / _CHECKPOINT_FILENAME
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    content = (
+        f"# Forgetted Checkpoint\n"
+        f"*Created: {timestamp}*\n\n"
+        f"## Session Context\n"
+        f"{context_summary}\n\n"
+        f"## Instructions\n"
+        f"This checkpoint was created before a forgetted window. "
+        f"Resume from the context above. The forgetted conversation "
+        f"has been erased — do not attempt to recover it.\n"
+    )
+
+    checkpoint_path.write_text(content, encoding="utf-8")
+    logger.info("🫥 Checkpoint saved to %s", checkpoint_path)
+    return checkpoint_path
+
+
+def load_checkpoint(workspace: str) -> Optional[str]:
+    """Read the checkpoint file if it exists, then delete it.
+
+    The checkpoint is single-use: once loaded, it's consumed.
+
+    Parameters
+    ----------
+    workspace : str
+        Absolute path to the agent workspace root.
+
+    Returns
+    -------
+    str or None
+        Checkpoint content, or None if no checkpoint exists.
+    """
+    checkpoint_path = Path(workspace) / "memory" / _CHECKPOINT_FILENAME
+
+    if not checkpoint_path.exists():
+        return None
+
+    content = checkpoint_path.read_text(encoding="utf-8")
+    checkpoint_path.unlink()
+    logger.info("🫥 Checkpoint loaded and consumed from %s", checkpoint_path)
+    return content

forgetted/cleaner.py

@@ -0,0 +1,88 @@
+"""
+forgetted.cleaner — Session log finder and deleter.
+
+After exiting forgetted mode, the session log covering the forgetted window
+must be removed so no trace of the private conversation persists on disk.
+
+Deletion is recoverable by default: uses ``send2trash`` if available,
+otherwise renames the file with a ``.deleted`` suffix (can be manually
+restored or purged later).
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def find_session_log(session_id: str, agents_dir: str) -> Optional[Path]:
+    """Locate the .jsonl session log for a given session ID.
+
+    Searches recursively under *agents_dir* for any ``.jsonl`` file whose
+    name contains the *session_id*.
+
+    Parameters
+    ----------
+    session_id : str
+        The session identifier to search for.
+    agents_dir : str
+        Root directory to search (e.g., ``~/.openclaw/agents/``).
+
+    Returns
+    -------
+    Path or None
+        Path to the matching session log, or None if not found.
+    """
+    root = Path(agents_dir)
+    if not root.exists():
+        return None
+
+    for jsonl_file in root.rglob("*.jsonl"):
+        if session_id in jsonl_file.stem:
+            logger.debug("🫥 Found session log: %s", jsonl_file)
+            return jsonl_file
+
+    return None
+
+
+def delete_session_log(session_log: Path) -> bool:
+    """Remove a session log file safely (recoverable).
+
+    Attempts ``send2trash`` first (moves to OS trash). Falls back to
+    renaming with a ``.deleted`` suffix if send2trash is unavailable.
+
+    Parameters
+    ----------
+    session_log : Path
+        Path to the .jsonl session log to delete.
+
+    Returns
+    -------
+    bool
+        True if the file was successfully removed/renamed.
+    """
+    if not session_log.exists():
+        logger.warning("🫥 Session log not found: %s", session_log)
+        return False
+
+    # Try send2trash first — moves to OS trash (recoverable).
+    try:
+        from send2trash import send2trash
+        send2trash(str(session_log))
+        logger.info("🫥 Session log trashed: %s", session_log)
+        return True
+    except ImportError:
+        pass
+    except Exception as exc:
+        logger.warning("🫥 send2trash failed (%s), falling back to rename", exc)
+
+    # Fallback: rename with .deleted suffix (manually recoverable).
+    deleted_path = session_log.with_suffix(session_log.suffix + ".deleted")
+    try:
+        session_log.rename(deleted_path)
+        logger.info("🫥 Session log renamed to %s", deleted_path)
+        return True
+    except OSError as exc:
+        logger.error("🫥 Failed to delete session log: %s", exc)
+        return False

forgetted/guard.py

@@ -0,0 +1,161 @@
+"""
+forgetted.guard — Write-blocking interceptor for forgetted mode.
+
+Monkey-patches ``builtins.open`` while active so that any attempt to write
+(modes 'w', 'a', 'x' and their binary variants) to protected paths inside
+the workspace silently returns a no-op file handle.  Reads are never blocked.
+
+This is the core primitive: "this session can read from memory but cannot
+write to it." A fork without consequence — the branch exists in context
+but is never merged back into the agent's persistent state.
+
+Protected paths:
+    - memory/ directory (daily logs, checkpoints)
+    - DELIVERABLES.md
+    - Any *.jsonl file (session logs)
+
+Security model:
+    - Input: workspace path (trusted, set by caller)
+    - Patches builtins.open at process level — catches writes from any layer
+    - Returns no-op StringIO/BytesIO instead of raising — agent code doesn't crash
+    - Restores original open on stop() — no permanent side effects
+"""
+
+import builtins
+import io
+import logging
+import re
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Modes that involve writing — we block these on protected paths.
+_WRITE_MODES = re.compile(r"[wax+]", re.IGNORECASE)
+
+# Default protected path patterns (relative to workspace root).
+_DEFAULT_PROTECTED = {
+    "memory",           # entire memory/ directory tree
+    "DELIVERABLES.md",  # shared deliverables log
+}
+
+# File extensions that are always blocked inside the workspace.
+_BLOCKED_EXTENSIONS = {".jsonl"}
+
+
+class ForgetGuard:
+    """Context manager that blocks file writes to protected workspace paths.
+
+    Parameters
+    ----------
+    workspace_path : str
+        Absolute path to the agent workspace root.
+    extra_protected : set[str], optional
+        Additional relative paths or directory names to protect.
+
+    Usage
+    -----
+    ::
+
+        guard = ForgetGuard("/path/to/workspace")
+        guard.start()
+        # ... agent runs, writes to memory/ silently vanish ...
+        guard.stop()
+
+    Or as a context manager::
+
+        with ForgetGuard("/path/to/workspace"):
+            ...
+    """
+
+    def __init__(self, workspace_path: str, extra_protected: Optional[set[str]] = None):
+        self.workspace = Path(workspace_path).resolve()
+        self.protected = _DEFAULT_PROTECTED | (extra_protected or set())
+        self.active = False
+        self._original_open = None
+        self._blocked_count = 0
+
+    # -- public API ---------------------------------------------------------
+
+    def start(self):
+        """Activate write blocking.  Patches ``builtins.open``."""
+        if self.active:
+            return
+        self._original_open = builtins.open
+        self._blocked_count = 0
+        builtins.open = self._patched_open  # type: ignore[assignment]
+        self.active = True
+        logger.info("🫥 Forgetted guard active — writes to protected paths are blocked")
+
+    def stop(self):
+        """Deactivate write blocking.  Restores original ``builtins.open``."""
+        if not self.active:
+            return
+        builtins.open = self._original_open  # type: ignore[assignment]
+        self._original_open = None
+        self.active = False
+        logger.info("🫥 Forgetted guard stopped — %d write(s) blocked", self._blocked_count)
+
+    @property
+    def blocked_count(self) -> int:
+        """Number of write attempts blocked since guard was started."""
+        return self._blocked_count
+
+    # -- context manager ----------------------------------------------------
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+        return False
+
+    # -- internal -----------------------------------------------------------
+
+    def _is_protected(self, filepath: Path) -> bool:
+        """Check if *filepath* falls under a protected path."""
+        try:
+            resolved = filepath.resolve()
+        except (OSError, ValueError):
+            return False
+
+        # Must be inside the workspace to be subject to protection.
+        try:
+            rel = resolved.relative_to(self.workspace)
+        except ValueError:
+            return False
+
+        # Check extension blocklist (e.g., .jsonl anywhere in workspace).
+        if resolved.suffix in _BLOCKED_EXTENSIONS:
+            return True
+
+        # Check protected directories and files.
+        rel_parts = rel.parts
+        for protected in self.protected:
+            # Direct filename match (e.g., "DELIVERABLES.md").
+            if rel_parts and rel_parts[-1] == protected:
+                return True
+            # Directory match (e.g., "memory" matches memory/anything).
+            if protected in rel_parts:
+                return True
+
+        return False
+
+    def _is_write_mode(self, mode: str) -> bool:
+        """Return True if *mode* involves writing."""
+        return bool(_WRITE_MODES.search(mode))
+
+    def _patched_open(self, file, mode="r", *args, **kwargs):
+        """Replacement for builtins.open that intercepts protected writes."""
+        filepath = Path(str(file))
+
+        if self._is_write_mode(mode) and self._is_protected(filepath):
+            self._blocked_count += 1
+            logger.debug("🫥 Blocked write to %s (mode=%s)", filepath, mode)
+            # Return a no-op StringIO/BytesIO depending on mode.
+            if "b" in mode:
+                return io.BytesIO()
+            return io.StringIO()
+
+        return self._original_open(file, mode, *args, **kwargs)

forgetted/session.py

@@ -0,0 +1,171 @@
+"""
+forgetted.session — ForgetSession orchestrator.
+
+Coordinates multiple persistence adapters during a forgetted window.
+This is the main entry point for v0.2 usage.
+
+Ordering contract for stop():
+    1. Re-enable all adapters (restore normal writes) — always happens first.
+    2. Run cleanup on each adapter (post-window sweep) — runs after enable.
+    3. Clean session log if requested.
+
+This ordering ensures that cleanup code can write freely (e.g., mem0.delete)
+because adapters are already re-enabled when cleanup runs.
+
+If any adapter raises during disable/enable/cleanup, the error is logged
+but other adapters continue. No single adapter failure blocks the rest.
+
+Usage::
+
+    from forgetted.session import ForgetSession
+
+    with ForgetSession("/path/to/workspace") as fs:
+        # ... everything here is forgetted ...
+        pass
+    # adapters re-enabled, cleanup done, session log deleted
+"""
+
+import logging
+from typing import Optional
+
+from .adapters.base import PersistenceAdapter
+from .adapters.file_write import FileWriteAdapter
+from .checkpoint import create_checkpoint
+from .cleaner import delete_session_log, find_session_log
+
+logger = logging.getLogger(__name__)
+
+
+class ForgetSession:
+    """Orchestrate a forgetted window across multiple persistence adapters.
+
+    Parameters
+    ----------
+    workspace : str
+        Absolute path to the agent workspace root.
+    adapters : list[PersistenceAdapter], optional
+        Additional adapters to register. ``FileWriteAdapter`` is always
+        included as the safety-net layer.
+    session_id : str, optional
+        Session ID for log cleanup after the window.
+    agents_dir : str, optional
+        Directory to search for session logs (for cleanup).
+    """
+
+    def __init__(
+        self,
+        workspace: str,
+        adapters: Optional[list[PersistenceAdapter]] = None,
+        session_id: Optional[str] = None,
+        agents_dir: Optional[str] = None,
+    ):
+        self.workspace = workspace
+        self.session_id = session_id
+        self.agents_dir = agents_dir
+        self._started = False
+
+        # FileWriteAdapter is always the base layer (safety net).
+        self._adapters: list[PersistenceAdapter] = [FileWriteAdapter(workspace)]
+        if adapters:
+            self._adapters.extend(adapters)
+
+    @property
+    def is_active(self) -> bool:
+        """True if the forgetted window is currently open."""
+        return self._started
+
+    @property
+    def adapters(self) -> list[PersistenceAdapter]:
+        """List of registered adapters (read-only view)."""
+        return list(self._adapters)
+
+    def add_adapter(self, adapter: PersistenceAdapter) -> None:
+        """Register an additional persistence adapter.
+
+        Must be called before ``start()``. Raises RuntimeError if
+        the session is already active.
+        """
+        if self._started:
+            raise RuntimeError("Cannot add adapters while forgetted session is active")
+        self._adapters.append(adapter)
+        logger.info("🫥 Registered adapter: %s", adapter.name)
+
+    def start(self, checkpoint_summary: Optional[str] = None) -> None:
+        """Open the forgetted window.
+
+        Parameters
+        ----------
+        checkpoint_summary : str, optional
+            If provided, saves a resumption checkpoint before disabling.
+        """
+        if self._started:
+            return  # Idempotent — double-start is a no-op.
+
+        # Save checkpoint before going dark.
+        if checkpoint_summary:
+            create_checkpoint(checkpoint_summary, self.workspace)
+
+        # Disable all adapters. Each adapter is independent — one failure
+        # doesn't prevent others from disabling.
+        for adapter in self._adapters:
+            try:
+                adapter.disable()
+            except Exception as exc:
+                logger.error("🫥 Failed to disable adapter '%s': %s", adapter.name, exc)
+
+        self._started = True
+        adapter_names = ", ".join(a.name for a in self._adapters)
+        logger.info("🫥 Forgetted session started — %d adapters active (%s)", len(self._adapters), adapter_names)
+
+    def stop(self, clean: bool = True) -> None:
+        """Close the forgetted window.
+
+        Ordering contract:
+            1. Re-enable all adapters (restore normal writes)
+            2. Run cleanup on each adapter (if clean=True)
+            3. Delete session log (if session_id and agents_dir provided)
+
+        Parameters
+        ----------
+        clean : bool
+            If True (default), run cleanup sweep on all adapters and
+            delete the session log. Set to False to skip cleanup.
+        """
+        if not self._started:
+            return  # Idempotent — stop before start is a no-op.
+
+        # Step 1: Re-enable all adapters first.
+        # This ensures cleanup code can write freely (e.g., mem0.delete).
+        for adapter in self._adapters:
+            try:
+                adapter.enable()
+            except Exception as exc:
+                logger.error("🫥 Failed to enable adapter '%s': %s", adapter.name, exc)
+
+        # Step 2: Run cleanup sweep.
+        if clean:
+            for adapter in self._adapters:
+                try:
+                    adapter.cleanup()
+                except Exception as exc:
+                    logger.error("🫥 Cleanup failed for adapter '%s': %s", adapter.name, exc)
+
+            # Step 3: Delete session log.
+            if self.session_id and self.agents_dir:
+                log = find_session_log(self.session_id, self.agents_dir)
+                if log:
+                    delete_session_log(log)
+
+        self._started = False
+        logger.info("🫥 Forgetted session stopped (clean=%s)", clean)
+
+    # -- context manager ----------------------------------------------------
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # Always stop and clean up, even if an exception occurred.
+        self.stop(clean=True)
+        return False  # Don't suppress exceptions.

forgetted/trigger.py

@@ -0,0 +1,35 @@
+"""
+forgetted.trigger — Detect forgetted mode activation in user messages.
+
+Supports exact commands (/forgetted) and natural-language variants
+("forget this", "go off the record"). Case-insensitive matching.
+"""
+
+# Trigger phrases — checked via substring match against lowercased input.
+TRIGGERS: list[str] = [
+    "/forgetted",
+    "/forget",
+    "forget this",
+    "go off the record",
+    "off the record",
+    "forgetted mode",
+    "this is off the record",
+    "don't remember this",
+]
+
+
+def is_forget_trigger(message: str) -> bool:
+    """Check whether a user message contains a forgetted trigger.
+
+    Parameters
+    ----------
+    message : str
+        Raw user message text.
+
+    Returns
+    -------
+    bool
+        True if the message activates forgetted mode.
+    """
+    lowered = message.lower()
+    return any(trigger in lowered for trigger in TRIGGERS)

forgetted-0.2.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: forgetted
+Version: 0.2.0
+Summary: Selective memory governance for AI agents — branch the timeline, never merge back
+Author-email: Hermes Labs <lpcisystems@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/roli-lpci/forgetted
+Project-URL: Repository, https://github.com/roli-lpci/forgetted
+Project-URL: Issues, https://github.com/roli-lpci/forgetted/issues
+Keywords: llm,agent,memory,privacy,ai-safety,fork,selective-forget
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: trash
+Requires-Dist: send2trash>=1.8.0; extra == "trash"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+<p align="center">
+  <h1 align="center">🫥 forgetted</h1>
+  <p align="center"><strong>Your AI agent remembers everything. Now it doesn't have to.</strong></p>
+  <p align="center">
+    <a href="https://pypi.org/project/forgetted/"><img src="https://img.shields.io/pypi/v/forgetted?color=blue" alt="PyPI"></a>
+    <a href="https://github.com/roli-lpci/forgetted/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"></a>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python"></a>
+  </p>
+</p>
+
+---
+
+**forgetted** gives AI agents selective memory governance. One line of code, and your agent keeps full context but writes nothing to memory.
+
+> Traditional incognito is dumb: no past, no future, fully isolated.
+> **forgetted** gives you: full continuity + selective non-persistence.
+
+```python
+from forgetted import ForgetSession
+
+with ForgetSession("/path/to/workspace"):
+    agent.chat("this conversation never happened")
+# ↑ No trace in memory, logs, or vector DB. Agent resumes normally.
+```
+
+## Why?
+
+AI agents write everything: memory files, session logs, vector embeddings, deliverables. Sometimes you need context without consequences:
+
+- 💬 **Sensitive conversations** that shouldn't persist in agent memory
+- 🧪 **Experiments** you don't want polluting your agent's knowledge base
+- 🔒 **Client data** discussed but not stored
+- 🤔 **Brainstorming** that shouldn't bias future responses
+
+**forgetted** is not a prompt. It's software that wraps the agent's persistence layer — writes silently vanish, reads still work, and the agent resumes normally after.
+
+## Install
+
+```bash
+pip install forgetted
+```
+
+## Quick Start
+
+### Simple (file-level protection)
+
+```python
+from forgetted import ForgetSession
+
+# Everything inside is forgetted — writes to memory/, logs, deliverables vanish
+with ForgetSession("/path/to/agent/workspace"):
+    agent.chat("tell me about the secret project")
+```
+
+### With vector DB protection
+
+```python
+from forgetted import ForgetSession
+from forgetted.adapters.mem0 import Mem0Adapter
+
+session = ForgetSession(
+    workspace="/path/to/workspace",
+    adapters=[Mem0Adapter(memory_instance, user_id="roli")],
+)
+session.start(checkpoint_summary="Discussing API design")
+# ... conversation happens with full context, zero persistence ...
+session.stop()  # re-enables all layers, cleans up
+```
+
+### Trigger detection (for chat agents)
+
+```python
+from forgetted import is_forget_trigger, ForgetSession
+
+if is_forget_trigger(user_message):  # "/forget", "off the record", etc.
+    with ForgetSession(workspace):
+        handle_conversation()
+```
+
+## What Gets Blocked
+
+| Layer | How | Status |
+|---|---|---|
+| Memory files (`memory/*.md`) | `builtins.open` patch | ✅ Blocked |
+| Deliverables / audit logs | `builtins.open` patch | ✅ Blocked |
+| Session logs (`*.jsonl`) | Blocked + deleted on exit | ✅ Blocked |
+| mem0 / semantic memory | Method patch on `add`/`update` | ✅ Blocked |
+| Any custom persistence | Write your own adapter | 🔌 Extensible |
+
+## How It Works
+
+**forgetted** uses a layered defense:
+
+1. **`FileWriteAdapter`** (always on) — patches `builtins.open` to intercept writes to protected paths. Returns no-op file handles instead of raising — agent code doesn't crash, writes just vanish.
+
+2. **`Mem0Adapter`** (opt-in) — patches `memory.add()` and `memory.update()` during the window. Post-window cleanup deletes any memories that leaked through.
+
+3. **`ForgetSession`** orchestrates everything: checkpoint → disable adapters → run conversation → enable adapters → cleanup → delete session log.
+
+Reads are **never** blocked. The agent has full context — it just can't write new context.
+
+## Write Your Own Adapter
+
+Any persistence layer can be controlled:
+
+```python
+from forgetted.adapters.base import PersistenceAdapter
+
+class RedisAdapter(PersistenceAdapter):
+    name = "redis"
+
+    def disable(self):
+        self._client.config_set("save", "")
+        self._active = True
+
+    def enable(self):
+        self._client.config_set("save", "3600 1")
+        self._active = False
+
+    def cleanup(self):
+        for key in self._window_keys:
+            self._client.delete(key)
+
+    @property
+    def is_active(self): return self._active
+```
+
+Register it: `ForgetSession(workspace, adapters=[RedisAdapter(client)])`
+
+## Trigger Phrases
+
+Built-in detection for natural-language triggers:
+
+| Trigger | Example |
+|---|---|
+| `/forgetted` | "/forgetted" |
+| `/forget` | "/forget" |
+| `forget this` | "hey, forget this conversation" |
+| `off the record` | "let's go off the record" |
+| `forgetted mode` | "enable forgetted mode" |
+| `don't remember this` | "don't remember this" |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           ForgetSession                  │
+│  (orchestrator — context manager)        │
+├─────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐     │
+│  │ FileWrite    │  │ Mem0         │     │
+│  │ Adapter      │  │ Adapter      │ ... │
+│  │ (safety net) │  │ (opt-in)     │     │
+│  └──────────────┘  └──────────────┘     │
+├─────────────────────────────────────────┤
+│  checkpoint → disable → conversation    │
+│  → enable → cleanup → delete log        │
+└─────────────────────────────────────────┘
+```
+
+## What This Really Is
+
+This is not a UX toggle. It's a **memory governance primitive**.
+
+Like git: you branch, but you never merge back. The conversation exists in context but is never written to the agent's persistent state. After the window closes, it's as if it never happened.
+
+> *"I want context… but I don't want consequences."*
+
+## Tested
+
+97 tests including an adversarial suite:
+- ✅ Write blocking (open w/a/x/wb/r+, symlinks, binary)
+- ✅ Trigger detection (zero false positives on "forgot password", "forgetful", etc.)
+- ✅ Adapter error isolation (one failing adapter doesn't break others)
+- ✅ Exception safety (cleanup runs even if conversation crashes)
+- ✅ Idempotency (double-start, stop-before-start, double-stop all safe)
+
+Known limitations are [documented as xfail tests](tests/test_adversarial.py) — not hidden.
+
+## Threat Model
+
+**What forgetted blocks:** Everything the agent controls — memory files, vector DB writes, session logs, deliverables.
+
+**What forgetted does NOT block:** LLM API provider logs, network telemetry, OS-level forensics. That's not the point.
+
+**The guarantee:** *"If someone looks through the agent's memory and logs, they won't find what you forgetted."*
+
+## License
+
+[Apache-2.0](LICENSE) — Hermes Labs

forgetted-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+forgetted/__init__.py,sha256=aE6FpVL6hGharQBZt75M_wdrhmR-r11YSaZYglyI4Hc,1218
+forgetted/checkpoint.py,sha256=xR8t6RW3vAAzwtFelF9LKevrq8gfJOlLjr6rqqRXGFk,2518
+forgetted/cleaner.py,sha256=D_WGDhoqQkkHFj6KI9IFfTXDlVeHh3t469TWt5i3oSo,2674
+forgetted/guard.py,sha256=VrSby8npY8lDeH62k81vy2F8IEeo6R_-4uVpR_ExVgE,5496
+forgetted/session.py,sha256=Kz0HWo-_hsP3pnnGVsIiAPdifxOv0k-0F6D0bZ3G2HE,6062
+forgetted/trigger.py,sha256=cyH7uGeQ65qQ5rFhVEUxa-rqlTM977fLe89mmVw6yFM,873
+forgetted/adapters/__init__.py,sha256=jXDntEYsNpa1HV1zP8g-VLl4Gn5Jk2Z7tOtnmvR7zlU,611
+forgetted/adapters/base.py,sha256=X6qgH0OPhBAOvoWbPJc8fEWQJsqy5r3DxzWRwKnSxz4,2173
+forgetted/adapters/file_write.py,sha256=YmVPWBqX-JybEz-Qd7659fgjVtAJ3o8tnhggoU_LZWk,1444
+forgetted/adapters/mem0.py,sha256=nOuVmGT1PbJ3xhpJ8zys_kFbky4KvCqkEEbaPoIqoqc,4291
+forgetted-0.2.0.dist-info/METADATA,sha256=lhOJLYCepyWSJNUIt7LisK4eSy43-W_IvHuFY4qA7EI,8458
+forgetted-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+forgetted-0.2.0.dist-info/top_level.txt,sha256=CgRdJH6_JRuDzweoHymDCBmeuxxdc_OSJUnsMOcsJiA,10
+forgetted-0.2.0.dist-info/RECORD,,

forgetted-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

forgetted-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+forgetted