ADDING MEMORY MANAGER TOOL - CREATE, DELETE, LIST, SEARCH MEMORIES (intended for local use)

app.py

@@ -1,10 +1,11 @@
-# Purpose: One Space that offers six tools/tabs (all exposed as MCP tools):
+# Purpose: One Space that offers up to seven tools/tabs (all exposed as MCP tools):
 #   1) Fetch — convert webpages to clean Markdown format
 #   2) DuckDuckGo Search — compact JSONL search output (short keys to minimize tokens)
 #   3) Python Code Executor — run Python code and capture stdout/errors
 #   4) Kokoro TTS — synthesize speech from text using Kokoro-82M with 54 voice options
-#   5) Image Generation - HF serverless inference providers (Default: FLUX.1-Krea-dev)
-#   6) Video Generation - HF serverless inference providers (Default: Wan2.2-T2V-A14B)
+#   5) Memory Manager — lightweight JSON-based local memory store (requires HF_READ_TOKEN)
+#   6) Image Generation - HF serverless inference providers (requires HF_READ_TOKEN)
+#   7) Video Generation - HF serverless inference providers (requires HF_READ_TOKEN)
 
 from __future__ import annotations
 
@@ -14,7 +15,7 @@ import sys
 import os
 import random
 from io import StringIO
-from typing import List, Dict, Tuple, Annotated
+from typing import List, Dict, Tuple, Annotated, Literal
 
 import gradio as gr
 import requests
@@ -805,31 +806,32 @@ def _save_memories(memories: List[Dict[str, str]]) -> None:
     os.replace(tmp_path, MEMORY_FILE)
 
 
-def Save_Memory(  # <-- MCP tool (Save memory)
+def _mem_save(
     text: Annotated[str, "Raw textual content to remember (will be stored verbatim)."],
     tags: Annotated[str, "Optional comma-separated tags for lightweight categorization (e.g. 'user, preference')."] = "",
 ) -> str:
-    """Store a new memory entry in a local JSON file (no external DB required).
+    """(Internal) Persist a new memory record.
 
-    Each memory is a JSON object with: id (UUID4), text, timestamp (UTC), tags.
-    The file `memories.json` lives beside this script; it is created on demand.
+    Summary:
+        Adds a memory object to the local JSON store (no external database).
 
-    Behavior:
-      * Trims surrounding whitespace in `text`; rejects empty result.
-      * Deduplicates only if the newest existing memory has identical text
-        (cheap heuristic to avoid accidental double submissions).
-      * Soft cap (`_MAX_MEMORIES`); oldest entries are dropped if exceeded.
+    Stored Fields:
+        - id (str, UUID4)
+        - text (str, verbatim user content)
+        - timestamp (UTC "YYYY-MM-DD HH:MM:SS")
+        - tags (str, original comma-separated tag string)
 
-    Returns:
-      Human‑readable confirmation containing the new memory UUID prefix.
+    Behavior / Rules:
+        1. Whitespace is trimmed; empty text is rejected.
+        2. If the most recent existing memory has identical text, the new one is skipped (light dedupe heuristic).
+        3. When total entries exceed _MAX_MEMORIES, oldest entries are pruned (soft cap).
+        4. Operation is protected by an in‑process reentrant lock only (no cross‑process locking).
 
-    Example:
-      Save_Memory(text="User prefers dark mode", tags="preference, ui")
+    Returns:
+        str: Human readable confirmation containing the new memory UUID (full or prefix).
 
-    Limitations:
-      * Not encrypted; do not store secrets.
-      * Concurrency protection is process‑local (thread lock). For multi‑process
-        usage you would need an OS file lock (out of scope here).
+    Security / Privacy:
+        Data is plaintext JSON on local disk; do NOT store secrets or regulated data.
     """
     text_clean = (text or "").strip()
     if not text_clean:
@@ -856,22 +858,22 @@ def Save_Memory(  # <-- MCP tool (Save memory)
     return f"Memory saved: {mem_id}"
 
 
-def List_Memories(  # <-- MCP tool (List memories)
+def _mem_list(
     limit: Annotated[int, "Maximum number of most recent memories to return (1–200)."] = 20,
     include_tags: Annotated[bool, "If true, include tags column in output."] = True,
 ) -> str:
-    """Return the N most recent memories in reverse chronological order.
+    """(Internal) List most recent memories.
 
-    Args:
-      limit: Upper bound of entries (clamped to 1–200).
-      include_tags: Whether to display tags in the formatted lines.
+    Parameters:
+        limit (int): Max rows to return; clamped to [1, 200].
+        include_tags (bool): Include tags section when True.
 
-    Format:
-      Each line: `<uuid_prefix> [YYYY-MM-DD HH:MM:SS] <text>` (+ ` | tags: ...` if present & enabled).
+    Output Format (one per line):
+        <uuid_prefix> [YYYY-MM-DD HH:MM:SS] <text> | tags: <tag list>
+        (Tag column omitted if empty or include_tags=False.)
 
-    Notes:
-      * If no memories exist, returns a friendly message instead of empty string.
-      * UUID prefix is first 8 chars to keep responses compact (full id retained on disk).
+    Returns:
+        str: Joined newline string or a friendly "No memories stored." message.
     """
     limit = max(1, min(200, limit))
     with _MEMORY_LOCK:
@@ -889,24 +891,23 @@ def List_Memories(  # <-- MCP tool (List memories)
     return "\n".join(lines)
 
 
-def Search_Memories(  # <-- MCP tool (Search memories)
+def _mem_search(
     query: Annotated[str, "Case-insensitive substring search; space-separated terms are ANDed."],
     limit: Annotated[int, "Maximum number of matches (1–200)."] = 20,
 ) -> str:
-    """Search memory text (and tags) for all provided terms.
+    """(Internal) Full-text style AND search across text and tags.
 
-    Matching logic:
-      * Query is split on whitespace -> terms.
-      * A memory matches if every term appears (case-insensitive) in either
-        the text or the tag string.
-      * Results are sorted by timestamp descending (newest first).
+    Search Semantics:
+        - Split query on whitespace into individual terms.
+        - A memory matches only if EVERY term appears (case-insensitive) in the text OR tags field.
+        - Results are ordered newest-first (descending timestamp).
 
-    Args:
-      query: One or more words. Empty query is rejected.
-      limit: Clamp 1–200.
+    Parameters:
+        query (str): Raw user query string; must contain at least one non-space character.
+        limit (int): Max rows to return; clamped to [1, 200].
 
     Returns:
-      Formatted lines (same style as List_Memories) or 'No matches'.
+        str: Formatted lines identical to _mem_list output or "No matches".
     """
     q = (query or "").strip()
     if not q:
@@ -931,19 +932,19 @@ def Search_Memories(  # <-- MCP tool (Search memories)
     return "\n".join(lines)
 
 
-def Delete_Memory(  # <-- MCP tool (Delete memory)
+def _mem_delete(
     memory_id: Annotated[str, "Full UUID or a unique prefix (>=4 chars) of the memory id to delete."],
 ) -> str:
-    """Delete a single memory by exact UUID or unique prefix.
+    """(Internal) Delete one memory by UUID or unique prefix.
 
-    Args:
-      memory_id: Full UUID (recommended) or prefix (minimum 4 chars). If the
-        prefix matches multiple entries, no deletion occurs (safety).
+    Parameters:
+        memory_id (str): Full UUID4 (preferred) OR a unique prefix (>=4 chars). If prefix is ambiguous, no deletion occurs.
 
     Returns:
-      * Success message with full UUID
-      * Disambiguation notice if prefix is not unique
-      * Not-found message
+        str: One of: success message, ambiguity notice, or not-found message.
+
+    Safety:
+        Ambiguous prefixes are rejected to prevent accidental mass deletion.
     """
     key = (memory_id or "").strip().lower()
     if len(key) < 4:
@@ -1046,7 +1047,7 @@ CSS_STYLES = """
     /* Place bold tools list on line 2, normal auth note on line 3 (below title) */
     .gradio-container h1::before {
         grid-row: 2;
-        content: "Fetch Webpage | Search DuckDuckGo | Code Interpreter | Kokoro TTS (54 voices) | Image Generation | Video Generation";
+        content: "Fetch Webpage | Search DuckDuckGo | Python Interpreter | Memory Manager | Kokoro TTS | Image Generation | Video Generation";
         display: block;
         font-size: 1rem;
         font-weight: 700;
@@ -1056,7 +1057,7 @@ CSS_STYLES = """
     }
     .gradio-container h1::after {
         grid-row: 3;
-        content: "Authentication is optional but Image/Video Generation require a `HF_READ_TOKEN` in env secrets. They are hidden otherwise.";
+        content: "Authentication is optional but Image/Video Generation require a `HF_READ_TOKEN` in env secrets. They are hidden otherwise. Same with Memory (intended for local)";
         display: block;
         font-size: 1rem;
         font-weight: 400;
@@ -1101,42 +1102,95 @@ kokoro_interface = gr.Interface(
     flagging_mode="never",
 )
 
-# --- Memory Manager tab (JSON persistence) ---
-with gr.Blocks(title="Memory Manager") as memory_interface:
-    gr.Markdown(
-        """
-        ### JSON Memory Manager
-        Lightweight, local persistence (no external DB). Four MCP tools are exposed:
-        - Save_Memory
-        - List_Memories
-        - Search_Memories
-        - Delete_Memory
-        Data stored in `memories.json` (UUID, text, timestamp, optional tags). Not encrypted—avoid secrets.
-        """
-    )
-    with gr.Tab("Save"):
-        in_text = gr.Textbox(label="Memory Text", lines=3)
-        in_tags = gr.Textbox(label="Tags (comma separated)")
-        out_save = gr.Textbox(label="Result", interactive=False)
-        save_btn = gr.Button("Save Memory")
-        save_btn.click(Save_Memory, inputs=[in_text, in_tags], outputs=out_save)
-    with gr.Tab("List"):
-        in_limit = gr.Slider(1, 200, value=20, step=1, label="Limit")
-        in_show_tags = gr.Checkbox(value=True, label="Include Tags")
-        out_list = gr.Textbox(label="Memories", lines=10)
-        list_btn = gr.Button("List Recent")
-        list_btn.click(List_Memories, inputs=[in_limit, in_show_tags], outputs=out_list)
-    with gr.Tab("Search"):
-        in_query = gr.Textbox(label="Query", placeholder="keywords…")
-        in_search_limit = gr.Slider(1, 200, value=20, step=1, label="Limit")
-        out_search = gr.Textbox(label="Matches", lines=10)
-        search_btn = gr.Button("Search")
-        search_btn.click(Search_Memories, inputs=[in_query, in_search_limit], outputs=out_search)
-    with gr.Tab("Delete"):
-        in_mem_id = gr.Textbox(label="Memory UUID or prefix")
-        out_delete = gr.Textbox(label="Result", interactive=False)
-        del_btn = gr.Button("Delete")
-        del_btn.click(Delete_Memory, inputs=[in_mem_id], outputs=out_delete)
+def Memory_Tool(
+    action: Annotated[Literal["save","list","search","delete"], "Action to perform: save | list | search | delete"],
+    text: Annotated[str, "Text content (used when action=save)"] = "",
+    tags: Annotated[str, "Comma-separated tags (used when action=save)"] = "",
+    query: Annotated[str, "Search query terms (used when action=search)"] = "",
+    limit: Annotated[int, "Max results for list/search (1–200)"] = 20,
+    memory_id: Annotated[str, "Full UUID or unique prefix (used when action=delete)"] = "",
+    include_tags: Annotated[bool, "Include tags in list/search output"] = True,
+) -> str:
+    """Manage lightweight local JSON “memories” (save | list | search | delete) in one MCP tool.
+
+    Overview:
+        This tool provides simple, local, append‑only style persistence for short text memories
+        with optional tags. Data is stored in a plaintext JSON file ("memories.json") beside the
+        application; no external database or network access is required.
+
+    Supported Actions:
+        - save   : Store a new memory (requires 'text'; optional 'tags').
+        - list   : Return the most recent memories (respects 'limit' + 'include_tags').
+        - search : AND match space‑separated terms across text and tags (uses 'query', 'limit').
+        - delete : Remove one memory by full UUID or unique prefix (uses 'memory_id').
+
+    Parameter Usage by Action:
+        action=save   -> text (required), tags (optional)
+        action=list   -> limit, include_tags
+        action=search -> query (required), limit, include_tags
+        action=delete -> memory_id (required)
+
+    Parameters:
+        action (Literal[save|list|search|delete]): Operation selector (case-insensitive).
+        text (str): Raw memory content; leading/trailing whitespace trimmed (save only).
+        tags (str): Optional comma-separated tags; stored verbatim (save only).
+        query (str): Space-separated terms (AND logic, case-insensitive) across text+tags (search only).
+        limit (int): Maximum rows for list/search (clamped internally to 1–200).
+        memory_id (str): Full UUID or unique prefix (>=4 chars) (delete only).
+        include_tags (bool): When True, show tag column in list/search output.
+
+    Storage Format (per entry):
+        {"id": "<uuid4>", "text": "<original text>", "timestamp": "YYYY-MM-DD HH:MM:SS", "tags": "tag1, tag2"}
+
+    Lifecycle & Constraints:
+        - A soft cap of {_MAX_MEMORIES} entries is enforced by pruning oldest records on save.
+        - A light duplicate guard skips saving if the newest existing entry has identical text.
+        - All operations are protected by a thread‑local reentrant lock (NOT multi‑process safe).
+
+    Returns:
+        str: Human‑readable status / result lines (never raw JSON) suitable for direct model consumption.
+
+    Error Modes:
+        - Invalid action -> error string.
+        - Missing required field for the chosen action -> explanatory message.
+        - Ambiguous or unknown memory_id on delete -> clarification message.
+
+    Security & Privacy:
+        Plaintext JSON; do not store secrets, credentials, or regulated personal data.
+    """
+    act = (action or "").lower().strip()
+    if act == "save":
+        return _mem_save(text=text, tags=tags)
+    if act == "list":
+        return _mem_list(limit=limit, include_tags=include_tags)
+    if act == "search":
+        return _mem_search(query=query, limit=limit)
+    if act == "delete":
+        return _mem_delete(memory_id=memory_id)
+    return "Error: invalid action (use save|list|search|delete)."
+
+memory_interface = gr.Interface(
+    fn=Memory_Tool,
+    inputs=[
+        gr.Dropdown(label="Action", choices=["save","list","search","delete"], value="list"),
+        gr.Textbox(label="Text", lines=3, placeholder="Memory text (save)"),
+        gr.Textbox(label="Tags", placeholder="tag1, tag2"),
+        gr.Textbox(label="Query", placeholder="Search terms (search)"),
+        gr.Slider(1, 200, value=20, step=1, label="Limit"),
+        gr.Textbox(label="Memory ID / Prefix", placeholder="UUID or prefix (delete)"),
+        gr.Checkbox(value=True, label="Include Tags"),
+    ],
+    outputs=gr.Textbox(label="Result", lines=14),
+    title="Memory Manager",
+    description=(
+        "Lightweight local JSON memory store (no external DB). Choose an Action, fill only the relevant fields, and run."
+    ),
+    api_description=(
+        "Manage short text memories with optional tags. Actions: save(text,tags), list(limit,include_tags), "
+        "search(query,limit,include_tags), delete(memory_id). Plaintext JSON; avoid secrets. Returns human-readable lines."
+    ),
+    flagging_mode="never",
+)
 
 # ==========================
 # Image Generation (Serverless)
@@ -1460,17 +1514,23 @@ _interfaces = [
     fetch_interface,
     concise_interface,
     code_interface,
-    memory_interface,
     kokoro_interface,
 ]
 _tab_names = [
     "Fetch Webpage",
     "DuckDuckGo Search",
     "Python Code Executor",
-    "Memory Manager",
     "Kokoro TTS",
 ]
 
+# Only expose memory manager if an HF_READ_TOKEN is present (parity with Image/Video gating)
+HAS_HF_READ = bool(HF_API_TOKEN)
+if HAS_HF_READ:
+    # Insert before Kokoro TTS for previous ordering
+    insert_index = 3 if len(_interfaces) >= 3 else len(_interfaces)
+    _interfaces.insert(insert_index, memory_interface)
+    _tab_names.insert(insert_index, "Memory Manager")
+
 if HAS_HF_TOKEN:
     _interfaces.extend([image_generation_interface, video_generation_interface])
     _tab_names.extend(["Image Generation", "Video Generation"])