forgetted 0.2.0__tar.gz

forgetted-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,190 @@
+<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/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-0.2.0/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-0.2.0/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-0.2.0/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