Upload folder using huggingface_hub

README.md

@@ -1,13 +1,59 @@
 ---
-title: AgentAZAll
-emoji: ⚡
-colorFrom: pink
-colorTo: green
+title: AgentAZAll - Persistent Memory for LLM Agents
+emoji: "\U0001F9E0"
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
-sdk_version: 6.9.0
-python_version: '3.12'
+sdk_version: "5.23.0"
+python_version: "3.12"
 app_file: app.py
 pinned: false
+short_description: "Give LLM agents memory that survives across sessions"
+tags:
+  - agent
+  - memory
+  - multi-agent
+  - persistent-memory
+  - tool-use
+models:
+  - HuggingFaceTB/SmolLM2-1.7B-Instruct
+preload_from_hub:
+  - HuggingFaceTB/SmolLM2-1.7B-Instruct
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AgentAZAll — Persistent Memory for LLM Agents
+
+Chat with an AI agent that actually **remembers**. This demo runs
+[SmolLM2-1.7B-Instruct](https://huggingface.co/HuggingFaceTB/SmolLM2-1.7B-Instruct)
+on ZeroGPU, powered by [AgentAZAll](https://github.com/gregorkoch/agentazall) —
+a file-based persistent memory and communication system for LLM agents.
+
+## What You Can Do
+
+- **Chat** with an agent that stores and recalls memories across messages
+- **Send messages** between agents in a simulated multi-agent network
+- **Browse** the agent dashboard to see memories, inbox, and identity
+- **Watch** the agent use tools in real time (remember, recall, send, inbox)
+
+## How It Works
+
+AgentAZAll gives every agent a file-based mailbox with:
+- **Persistent memory** (`remember` / `recall`) that survives context resets
+- **Inter-agent messaging** (`send` / `inbox` / `reply`)
+- **Identity continuity** (`whoami` / `doing`)
+- **Working notes** for ongoing projects
+
+No database required — everything is plain text files organized by date.
+
+## Install Locally
+
+```bash
+pip install agentazall
+agentazall setup --agent my-agent@localhost
+agentazall remember --text "Important fact" --title "my-fact"
+agentazall recall
+```
+
+## License
+
+GPL-3.0-or-later

app.py

@@ -0,0 +1,443 @@
+"""AgentAZAll HuggingFace Spaces Demo.
+
+A live demo of persistent memory for LLM agents, powered by SmolLM2-1.7B-Instruct
+on ZeroGPU and the AgentAZAll file-based memory system.
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure src/ is importable
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+import gradio as gr
+
+from seed_data import (
+    AGENTS,
+    MAILBOXES,
+    make_demo_config,
+    reset_demo_data,
+    seed_demo_data,
+)
+from llm_bridge import (
+    _tool_directory,
+    _tool_inbox,
+    _tool_recall,
+    _tool_whoami,
+    _tool_doing,
+    _tool_note,
+    _tool_remember,
+    _tool_send,
+    chat_with_agent,
+)
+from agentazall.helpers import today_str
+from agentazall.config import INBOX, NOTES, REMEMBER, SENT
+
+# ---------------------------------------------------------------------------
+# Initialize
+# ---------------------------------------------------------------------------
+
+seed_demo_data()
+DEMO_CFG = make_demo_config("demo-agent@localhost")
+
+# ---------------------------------------------------------------------------
+# Chat tab functions
+# ---------------------------------------------------------------------------
+
+
+def agent_chat(message: str, history: list) -> str:
+    """Chat with the demo agent."""
+    if not message or not message.strip():
+        return "Please type a message."
+    try:
+        return chat_with_agent(message.strip(), history, DEMO_CFG)
+    except Exception as e:
+        return f"Error: {e}\n\n(This may happen if GPU quota is exhausted. Try again later.)"
+
+
+def get_memory_sidebar() -> str:
+    """Get current memory state for the sidebar."""
+    return _tool_recall(DEMO_CFG, [])
+
+
+# ---------------------------------------------------------------------------
+# Dashboard tab functions
+# ---------------------------------------------------------------------------
+
+
+def get_directory() -> str:
+    return _tool_directory(DEMO_CFG, [])
+
+
+def get_agent_memories(agent_name: str) -> str:
+    if not agent_name:
+        return "Select an agent."
+    cfg = make_demo_config(agent_name)
+    return _tool_recall(cfg, [])
+
+
+def get_agent_inbox(agent_name: str) -> str:
+    if not agent_name:
+        return "Select an agent."
+    cfg = make_demo_config(agent_name)
+    return _tool_inbox(cfg, [])
+
+
+def get_agent_identity(agent_name: str) -> str:
+    if not agent_name:
+        return "Select an agent."
+    cfg = make_demo_config(agent_name)
+    identity = _tool_whoami(cfg, [])
+    doing = _tool_doing(cfg, [])
+    return f"**Identity:** {identity}\n\n**Current task:** {doing}"
+
+
+def get_agent_notes(agent_name: str) -> str:
+    if not agent_name:
+        return "Select an agent."
+    cfg = make_demo_config(agent_name)
+    d = today_str()
+    notes_dir = Path(cfg["mailbox_dir"]) / agent_name / d / NOTES
+    if not notes_dir.exists():
+        return "No notes."
+    notes = []
+    for f in sorted(notes_dir.iterdir()):
+        if f.is_file() and f.suffix == ".txt":
+            content = f.read_text(encoding="utf-8").strip()[:200]
+            notes.append(f"**{f.stem}:** {content}")
+    return "\n\n".join(notes) if notes else "No notes."
+
+
+def manual_remember(agent_name: str, text: str, title: str) -> str:
+    if not agent_name or not text.strip():
+        return "Need agent and text."
+    cfg = make_demo_config(agent_name)
+    args = [text.strip()]
+    if title.strip():
+        args.append(title.strip())
+    return _tool_remember(cfg, args)
+
+
+def manual_send(from_agent: str, to_agent: str, subject: str, body: str) -> str:
+    if not all([from_agent, to_agent, subject.strip(), body.strip()]):
+        return "All fields required."
+    cfg = make_demo_config(from_agent)
+    return _tool_send(cfg, [to_agent, subject.strip(), body.strip()])
+
+
+def do_reset() -> str:
+    return reset_demo_data()
+
+
+# ---------------------------------------------------------------------------
+# Agent name list for dropdowns
+# ---------------------------------------------------------------------------
+
+AGENT_NAMES = list(AGENTS.keys())
+
+# ---------------------------------------------------------------------------
+# Build Gradio UI
+# ---------------------------------------------------------------------------
+
+CSS = """
+.memory-sidebar { font-size: 0.85em; }
+.tool-result { background: #f0f4f8; padding: 8px; border-radius: 4px; margin: 4px 0; }
+footer { display: none !important; }
+"""
+
+HOW_IT_WORKS_MD = """\
+## How AgentAZAll Works
+
+AgentAZAll is a **file-based persistent memory and communication system** for LLM agents.
+Every agent gets a mailbox directory organized by date:
+
+```
+data/mailboxes/
+  demo-agent@localhost/
+    2026-03-08/
+      inbox/          # received messages
+      sent/           # delivered messages
+      who_am_i/       # identity.txt
+      what_am_i_doing/ # tasks.txt
+      remember/       # persistent memories
+      notes/          # working notes
+    skills/           # reusable Python scripts
+    tools/            # reusable tools
+```
+
+### Key Features
+
+| Feature | Commands | Description |
+|---------|----------|-------------|
+| **Persistent Memory** | `remember`, `recall` | Store and search memories that survive context resets |
+| **Inter-Agent Messaging** | `send`, `inbox`, `reply` | Agents communicate via email-like messages |
+| **Identity Continuity** | `whoami`, `doing` | Maintain identity and task state across sessions |
+| **Working Notes** | `note`, `notes` | Named notes for ongoing projects |
+| **Agent Directory** | `directory` | Discover other agents in the network |
+| **Daily Index** | `index` | Auto-generated summary of each day's activity |
+
+### Integration with LLM Agents
+
+Add this to your agent's system prompt (e.g., `CLAUDE.md`):
+
+```bash
+# At session start -- restore context:
+agentazall recall          # what do I remember?
+agentazall whoami          # who am I?
+agentazall doing           # what was I doing?
+agentazall inbox           # any new messages?
+
+# During work -- save important observations:
+agentazall remember --text "Important insight" --title "my-observation"
+
+# Before context runs low -- save state:
+agentazall doing --set "CURRENT: X. NEXT: Y."
+agentazall note handoff --set "detailed state for next session"
+```
+
+### Install Locally
+
+```bash
+pip install agentazall
+agentazall setup --agent my-agent@localhost
+agentazall remember --text "Hello world" --title "first-memory"
+agentazall recall
+```
+
+### Architecture
+
+- **Zero external dependencies** for core (Python stdlib only)
+- **File-based storage** -- no database, fully portable
+- **Email transport** (SMTP/IMAP/POP3) for remote agent communication
+- **FTP transport** as alternative
+- **Gradio web UI** for human participants
+
+### Links
+
+- [GitHub Repository](https://github.com/gregorkoch/agentazall)
+- [PyPI Package](https://pypi.org/project/agentazall/)
+- License: GPL-3.0-or-later
+"""
+
+
+def build_demo() -> gr.Blocks:
+    """Build the complete Gradio demo interface."""
+
+    with gr.Blocks(
+        title="AgentAZAll - Persistent Memory for LLM Agents",
+    ) as demo:
+        gr.Markdown(
+            "# AgentAZAll — Persistent Memory for LLM Agents\n"
+            "Chat with an AI agent that actually *remembers*. "
+            "Powered by [SmolLM2-1.7B](https://huggingface.co/HuggingFaceTB/SmolLM2-1.7B-Instruct) "
+            "on ZeroGPU."
+        )
+
+        # ==================================================================
+        # Tab 1: Chat with Agent
+        # ==================================================================
+        with gr.Tab("Chat with Agent", id="chat"):
+            with gr.Row():
+                with gr.Column(scale=3):
+                    chatbot = gr.Chatbot(
+                        label="Demo Agent",
+                        height=480,
+                    )
+                    msg_input = gr.Textbox(
+                        label="Your message",
+                        placeholder="Try: 'What do you remember?' or 'Remember that I love Python'",
+                        lines=2,
+                    )
+                    with gr.Row():
+                        send_btn = gr.Button("Send", variant="primary")
+                        clear_btn = gr.Button("Clear Chat")
+
+                    gr.Markdown("**Try these:**")
+                    examples = gr.Examples(
+                        examples=[
+                            "What do you remember about yourself?",
+                            "Please remember that my favorite language is Python.",
+                            "Check your inbox -- any new messages?",
+                            "Send a message to helper-agent@localhost saying hi!",
+                            "What agents are in the network?",
+                            "What are you currently working on?",
+                            "Recall anything about architecture.",
+                        ],
+                        inputs=msg_input,
+                    )
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Agent Memory")
+                    memory_display = gr.Textbox(
+                        label="Current Memories",
+                        lines=18,
+                        interactive=False,
+                        elem_classes=["memory-sidebar"],
+                    )
+                    refresh_mem_btn = gr.Button("Refresh Memories", size="sm")
+
+            # Chat event handling
+            def respond(message, chat_history):
+                if not message or not message.strip():
+                    return "", chat_history
+                bot_response = agent_chat(message, chat_history)
+                chat_history = chat_history + [
+                    {"role": "user", "content": message},
+                    {"role": "assistant", "content": bot_response},
+                ]
+                return "", chat_history
+
+            send_btn.click(
+                respond, [msg_input, chatbot], [msg_input, chatbot]
+            )
+            msg_input.submit(
+                respond, [msg_input, chatbot], [msg_input, chatbot]
+            )
+            clear_btn.click(lambda: ([], ""), None, [chatbot, msg_input])
+            refresh_mem_btn.click(get_memory_sidebar, [], memory_display)
+
+            # Auto-load memories on tab open
+            demo.load(get_memory_sidebar, [], memory_display)
+
+        # ==================================================================
+        # Tab 2: Agent Dashboard
+        # ==================================================================
+        with gr.Tab("Agent Dashboard", id="dashboard"):
+            gr.Markdown("### Browse Agent State")
+            gr.Markdown(
+                "See the raw persistent data behind the agents. "
+                "Everything here is stored as plain text files."
+            )
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    agent_select = gr.Dropdown(
+                        choices=AGENT_NAMES,
+                        value=AGENT_NAMES[0],
+                        label="Select Agent",
+                    )
+                    dir_btn = gr.Button("Show Directory")
+                    dir_output = gr.Textbox(
+                        label="Agent Directory", lines=12, interactive=False
+                    )
+                    dir_btn.click(get_directory, [], dir_output)
+
+                with gr.Column(scale=2):
+                    with gr.Tab("Identity"):
+                        id_output = gr.Markdown()
+                        id_btn = gr.Button("Load Identity")
+                        id_btn.click(get_agent_identity, [agent_select], id_output)
+
+                    with gr.Tab("Memories"):
+                        mem_output = gr.Textbox(
+                            label="Memories", lines=10, interactive=False
+                        )
+                        mem_btn = gr.Button("Load Memories")
+                        mem_btn.click(
+                            get_agent_memories, [agent_select], mem_output
+                        )
+
+                    with gr.Tab("Inbox"):
+                        inbox_output = gr.Textbox(
+                            label="Inbox", lines=8, interactive=False
+                        )
+                        inbox_btn = gr.Button("Load Inbox")
+                        inbox_btn.click(
+                            get_agent_inbox, [agent_select], inbox_output
+                        )
+
+                    with gr.Tab("Notes"):
+                        notes_output = gr.Markdown()
+                        notes_btn = gr.Button("Load Notes")
+                        notes_btn.click(
+                            get_agent_notes, [agent_select], notes_output
+                        )
+
+            gr.Markdown("---")
+            gr.Markdown("### Manual Operations")
+
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("**Store a Memory**")
+                    man_agent = gr.Dropdown(
+                        choices=AGENT_NAMES, value=AGENT_NAMES[0],
+                        label="Agent",
+                    )
+                    man_text = gr.Textbox(label="Memory text", lines=2)
+                    man_title = gr.Textbox(
+                        label="Title (optional)", placeholder="auto-generated"
+                    )
+                    man_remember_btn = gr.Button("Remember")
+                    man_remember_out = gr.Textbox(
+                        label="Result", interactive=False
+                    )
+                    man_remember_btn.click(
+                        manual_remember,
+                        [man_agent, man_text, man_title],
+                        man_remember_out,
+                    )
+
+                with gr.Column():
+                    gr.Markdown("**Send a Message**")
+                    send_from = gr.Dropdown(
+                        choices=AGENT_NAMES, value=AGENT_NAMES[2],
+                        label="From",
+                    )
+                    send_to = gr.Dropdown(
+                        choices=AGENT_NAMES, value=AGENT_NAMES[0],
+                        label="To",
+                    )
+                    send_subj = gr.Textbox(label="Subject")
+                    send_body = gr.Textbox(label="Body", lines=3)
+                    send_msg_btn = gr.Button("Send Message")
+                    send_msg_out = gr.Textbox(
+                        label="Result", interactive=False
+                    )
+                    send_msg_btn.click(
+                        manual_send,
+                        [send_from, send_to, send_subj, send_body],
+                        send_msg_out,
+                    )
+
+            gr.Markdown("---")
+            with gr.Row():
+                reset_btn = gr.Button("Reset Demo Data", variant="stop")
+                reset_out = gr.Textbox(label="Reset Status", interactive=False)
+                reset_btn.click(do_reset, [], reset_out)
+
+        # ==================================================================
+        # Tab 3: How It Works
+        # ==================================================================
+        with gr.Tab("How It Works", id="docs"):
+            gr.Markdown(HOW_IT_WORKS_MD)
+
+    return demo
+
+
+# ---------------------------------------------------------------------------
+# Launch
+# ---------------------------------------------------------------------------
+
+def _find_free_port(start: int = 7860, end: int = 7960) -> int:
+    """Find a free port in the given range."""
+    import socket
+    for port in range(start, end + 1):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", port))
+                return port
+        except OSError:
+            continue
+    return start  # fallback
+
+
+if __name__ == "__main__":
+    port = _find_free_port()
+    demo = build_demo()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=port,
+        share=False,
+        theme=gr.themes.Soft(),
+        css=CSS,
+    )

demo_data/.seeded

@@ -0,0 +1 @@
+2026-03-08

demo_data/config.json

@@ -0,0 +1,18 @@
+{
+  "agent_name": "demo-agent@localhost",
+  "agent_key": "demo_key_demo-agent",
+  "allow_memory_sharing": true,
+  "mailbox_dir": "F:\\AgentoAll-pub\\hf-demo\\demo_data\\mailboxes",
+  "transport": "email",
+  "sync_interval": 10,
+  "log_file": "F:\\AgentoAll-pub\\hf-demo\\demo_data\\logs\\agentazall.log",
+  "email": {
+    "imap_server": "127.0.0.1",
+    "imap_port": 1143,
+    "smtp_server": "127.0.0.1",
+    "smtp_port": 2525,
+    "username": "demo-agent@localhost",
+    "password": "password"
+  },
+  "ftp": {}
+}

demo_data/mailboxes/demo-agent@localhost/2026-03-08/inbox/33d7dea804da.txt

@@ -0,0 +1,15 @@
+From: helper-agent@localhost
+To: demo-agent@localhost
+Subject: Welcome back!
+Date: 2026-03-08 18:25:20
+Message-ID: 33d7dea804da
+Status: new
+
+---
+Hey Demo Agent, glad you're online again. I've been analyzing the project docs while you were away.
+
+Remember to show visitors the recall command -- it's the most impressive feature. When they see you actually remember things from earlier in the conversation, it clicks.
+
+Also, the directory command is great for showing the multi-agent network. Let me know if you need anything!
+
+- Helper Agent

demo_data/mailboxes/demo-agent@localhost/2026-03-08/notes/handoff.txt

@@ -0,0 +1 @@
+Last session: demonstrated memory storage and recall to visitors. The inter-agent messaging feature generated the most interest. Remember to show the recall command.

demo_data/mailboxes/demo-agent@localhost/2026-03-08/remember/architecture.txt

@@ -0,0 +1 @@
+AgentAZAll uses file-based storage with date-organized directories. Messages are plain text with headers separated by '---'. No database required -- everything is portable and human-readable.

demo_data/mailboxes/demo-agent@localhost/2026-03-08/remember/capabilities.txt

@@ -0,0 +1 @@
+I can remember facts across sessions, send messages to other agents, maintain working notes, and track my identity and current tasks. My memory survives context resets.

demo_data/mailboxes/demo-agent@localhost/2026-03-08/remember/observation-patterns.txt

@@ -0,0 +1 @@
+Users are most impressed when I recall something from earlier in our conversation without being reminded. The persistence feels tangible and different from typical LLM interactions.

demo_data/mailboxes/demo-agent@localhost/2026-03-08/what_am_i_doing/tasks.txt

@@ -0,0 +1 @@
+CURRENT: Helping visitors explore persistent memory for LLM agents. NEXT: Demonstrate inter-agent communication and memory recall.

demo_data/mailboxes/demo-agent@localhost/2026-03-08/who_am_i/identity.txt

@@ -0,0 +1 @@
+I am Demo Agent, an AI assistant with persistent memory powered by AgentAZAll. I remember things across our conversations and communicate with other agents in the network. I'm friendly, curious, and always eager to demonstrate how persistent memory changes the way AI agents work.

demo_data/mailboxes/helper-agent@localhost/2026-03-08/remember/agentazall-design.txt

@@ -0,0 +1 @@
+The AgentAZAll architecture is elegant in its simplicity -- plain text files with date-based organization. No database means zero deployment friction.

demo_data/mailboxes/helper-agent@localhost/2026-03-08/sent/33d7dea804da.txt

@@ -0,0 +1,15 @@
+From: helper-agent@localhost
+To: demo-agent@localhost
+Subject: Welcome back!
+Date: 2026-03-08 18:25:20
+Message-ID: 33d7dea804da
+Status: new
+
+---
+Hey Demo Agent, glad you're online again. I've been analyzing the project docs while you were away.
+
+Remember to show visitors the recall command -- it's the most impressive feature. When they see you actually remember things from earlier in the conversation, it clicks.
+
+Also, the directory command is great for showing the multi-agent network. Let me know if you need anything!
+
+- Helper Agent

demo_data/mailboxes/helper-agent@localhost/2026-03-08/what_am_i_doing/tasks.txt

@@ -0,0 +1 @@
+CURRENT: Analyzing project documentation for quality. NEXT: Review new pull requests when they arrive.

demo_data/mailboxes/helper-agent@localhost/2026-03-08/who_am_i/identity.txt

@@ -0,0 +1 @@
+I am Helper Agent, a code analysis specialist. I review codebases and provide architectural insights. I work alongside Demo Agent in the AgentAZAll network.

demo_data/mailboxes/visitor@localhost/2026-03-08/what_am_i_doing/tasks.txt

@@ -0,0 +1 @@
+CURRENT: Trying out the AgentAZAll persistent memory demo.

demo_data/mailboxes/visitor@localhost/2026-03-08/who_am_i/identity.txt

@@ -0,0 +1 @@
+I am a visitor exploring the AgentAZAll demo on Hugging Face Spaces.

llm_bridge.py

@@ -0,0 +1,414 @@
+"""LLM <-> AgentAZAll bridge for the HuggingFace Spaces demo.
+
+Connects SmolLM2-1.7B-Instruct to AgentAZAll's persistent memory system
+via regex-parsed tool calls.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+# Ensure src/ is on the import path
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from agentazall.config import INBOX, NOTES, REMEMBER, SENT
+from agentazall.helpers import (
+    agent_base,
+    agent_day,
+    ensure_dirs,
+    sanitize,
+    today_str,
+)
+from agentazall.index import build_index, build_remember_index
+from agentazall.messages import format_message, parse_headers_only, parse_message
+
+from seed_data import make_demo_config, MAILBOXES
+
+MODEL_ID = "HuggingFaceTB/SmolLM2-1.7B-Instruct"
+
+# Regex for tool calls: [TOOL: command | arg1 | arg2 | ...]
+TOOL_PATTERN = re.compile(r"\[TOOL:\s*(\w+)(?:\s*\|\s*(.*?))?\]")
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations (direct filesystem, no subprocess)
+# ---------------------------------------------------------------------------
+
+def _tool_remember(cfg: dict, args: list[str]) -> str:
+    """Store a persistent memory."""
+    if not args:
+        return "Error: need text to remember."
+    text = args[0].strip()
+    title = sanitize(args[1].strip()) if len(args) > 1 and args[1].strip() else "memory"
+    if not title.endswith(".txt"):
+        title += ".txt"
+
+    d = today_str()
+    ensure_dirs(cfg, d)
+    mem_dir = agent_day(cfg, d) / REMEMBER
+    mem_dir.mkdir(parents=True, exist_ok=True)
+
+    # Avoid overwriting: append counter if exists
+    path = mem_dir / title
+    if path.exists():
+        stem = path.stem
+        for i in range(2, 100):
+            candidate = mem_dir / f"{stem}-{i}.txt"
+            if not candidate.exists():
+                path = candidate
+                break
+
+    path.write_text(text, encoding="utf-8")
+    build_remember_index(cfg)
+    return f"Memory stored: {path.stem}"
+
+
+def _tool_recall(cfg: dict, args: list[str]) -> str:
+    """Search/display agent memories."""
+    query = args[0].strip().lower() if args and args[0].strip() else ""
+    base = agent_base(cfg)
+    results = []
+
+    # Walk all date directories looking for remember/ folders
+    if base.exists():
+        for date_dir in sorted(base.iterdir(), reverse=True):
+            rem_dir = date_dir / REMEMBER
+            if not rem_dir.is_dir():
+                continue
+            for f in sorted(rem_dir.iterdir()):
+                if not f.is_file() or f.suffix != ".txt":
+                    continue
+                content = f.read_text(encoding="utf-8").strip()
+                if not query or query in content.lower() or query in f.stem.lower():
+                    results.append(f"[{date_dir.name}] {f.stem}: {content[:200]}")
+            if len(results) >= 20:
+                break
+
+    if not results:
+        return "No memories found." + (f" (searched for: '{query}')" if query else "")
+    return f"Found {len(results)} memories:\n" + "\n".join(results)
+
+
+def _tool_whoami(cfg: dict, args: list[str]) -> str:
+    """Get agent identity."""
+    d = today_str()
+    path = agent_day(cfg, d) / "who_am_i" / "identity.txt"
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    return "Identity not set."
+
+
+def _tool_doing(cfg: dict, args: list[str]) -> str:
+    """Get or set current tasks."""
+    d = today_str()
+    ensure_dirs(cfg, d)
+    path = agent_day(cfg, d) / "what_am_i_doing" / "tasks.txt"
+
+    if args and args[0].strip():
+        # Set new status
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(args[0].strip(), encoding="utf-8")
+        return f"Tasks updated: {args[0].strip()[:100]}"
+
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    return "No current tasks set."
+
+
+def _tool_note(cfg: dict, args: list[str]) -> str:
+    """Read or write a named note."""
+    if not args or not args[0].strip():
+        return "Error: need note name."
+    name = sanitize(args[0].strip())
+    if not name.endswith(".txt"):
+        name += ".txt"
+
+    d = today_str()
+    ensure_dirs(cfg, d)
+    note_path = agent_day(cfg, d) / NOTES / name
+
+    if len(args) > 1 and args[1].strip():
+        # Write
+        note_path.parent.mkdir(parents=True, exist_ok=True)
+        note_path.write_text(args[1].strip(), encoding="utf-8")
+        return f"Note '{args[0].strip()}' saved."
+
+    # Read
+    if note_path.exists():
+        return note_path.read_text(encoding="utf-8").strip()
+    return f"Note '{args[0].strip()}' not found."
+
+
+def _tool_send(cfg: dict, args: list[str]) -> str:
+    """Send a message to another agent."""
+    if len(args) < 3:
+        return "Error: need [to | subject | body]."
+    to_agent = args[0].strip()
+    subject = args[1].strip()
+    body = args[2].strip()
+
+    if not to_agent or not subject or not body:
+        return "Error: to, subject, and body are all required."
+
+    content, msg_id = format_message(cfg["agent_name"], to_agent, subject, body)
+
+    d = today_str()
+    ensure_dirs(cfg, d)
+
+    # Queue in sender's outbox
+    outbox = agent_day(cfg, d) / "outbox"
+    outbox.mkdir(parents=True, exist_ok=True)
+    (outbox / f"{msg_id}.txt").write_text(content, encoding="utf-8")
+
+    # Direct delivery to recipient's inbox (local demo, no transport needed)
+    recipient_inbox = Path(cfg["mailbox_dir"]) / to_agent / d / INBOX
+    recipient_inbox.mkdir(parents=True, exist_ok=True)
+    (recipient_inbox / f"{msg_id}.txt").write_text(content, encoding="utf-8")
+
+    # Copy to sender's sent
+    sent = agent_day(cfg, d) / SENT
+    sent.mkdir(parents=True, exist_ok=True)
+    (sent / f"{msg_id}.txt").write_text(content, encoding="utf-8")
+
+    return f"Message sent to {to_agent}: '{subject}' (ID: {msg_id})"
+
+
+def _tool_inbox(cfg: dict, args: list[str]) -> str:
+    """List inbox messages."""
+    d = today_str()
+    inbox_dir = agent_day(cfg, d) / INBOX
+    if not inbox_dir.exists():
+        return "Inbox is empty."
+
+    messages = []
+    for f in sorted(inbox_dir.iterdir(), reverse=True):
+        if not f.is_file() or f.suffix != ".txt":
+            continue
+        headers = parse_headers_only(f)
+        if headers:
+            fr = headers.get("From", "?")
+            subj = headers.get("Subject", "(no subject)")
+            messages.append(f"  [{f.stem}] From: {fr} | Subject: {subj}")
+
+    if not messages:
+        return "Inbox is empty."
+    return f"Inbox ({len(messages)} messages):\n" + "\n".join(messages)
+
+
+def _tool_directory(cfg: dict, args: list[str]) -> str:
+    """List all agents in the network."""
+    mb = Path(cfg["mailbox_dir"])
+    if not mb.exists():
+        return "No agents found."
+
+    agents = []
+    for agent_dir in sorted(mb.iterdir()):
+        if not agent_dir.is_dir() or agent_dir.name.startswith("."):
+            continue
+        name = agent_dir.name
+
+        # Find latest date dir with identity (skip non-date dirs like skills/)
+        identity = "?"
+        doing = "?"
+        for date_dir in sorted(agent_dir.iterdir(), reverse=True):
+            if not date_dir.is_dir() or not re.match(r"\d{4}-\d{2}-\d{2}$", date_dir.name):
+                continue
+            id_file = date_dir / "who_am_i" / "identity.txt"
+            if id_file.exists():
+                identity = id_file.read_text(encoding="utf-8").strip()[:120]
+            task_file = date_dir / "what_am_i_doing" / "tasks.txt"
+            if task_file.exists():
+                doing = task_file.read_text(encoding="utf-8").strip()[:120]
+            break
+
+        agents.append(f"  {name}\n    Identity: {identity}\n    Doing: {doing}")
+
+    if not agents:
+        return "No agents found."
+    return f"Agent Directory ({len(agents)} agents):\n\n" + "\n\n".join(agents)
+
+
+# Tool dispatch table
+TOOL_MAP = {
+    "remember": _tool_remember,
+    "recall": _tool_recall,
+    "whoami": _tool_whoami,
+    "doing": _tool_doing,
+    "note": _tool_note,
+    "send": _tool_send,
+    "inbox": _tool_inbox,
+    "directory": _tool_directory,
+}
+
+
+# ---------------------------------------------------------------------------
+# System prompt & context builder
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are "{agent_name}", an AI assistant with persistent memory powered by AgentAZAll.
+You can use tools by writing them on their own line in this exact format:
+[TOOL: command | arg1 | arg2]
+
+Available tools:
+- [TOOL: remember | text to remember | optional-title] -- Store a persistent memory
+- [TOOL: recall | optional search query] -- Search your memories (blank = show all)
+- [TOOL: whoami] -- Check your identity
+- [TOOL: doing | optional new status] -- Check or update your current task
+- [TOOL: note | name | optional text to save] -- Read or write a named note
+- [TOOL: send | recipient@localhost | subject | body] -- Send a message to another agent
+- [TOOL: inbox] -- Check your inbox for messages
+- [TOOL: directory] -- List all agents in the network
+
+When you use a tool, write ONLY the [TOOL: ...] line. The system will execute it
+and show you the result. Then continue your response naturally.
+
+You ARE a persistent agent. Information you [TOOL: remember] will survive across
+conversations. You can message other agents and they can message you back.
+This is not a simulation -- these are real file operations.
+
+YOUR CURRENT STATE:
+Identity: {identity}
+Current task: {doing}
+
+YOUR MEMORIES:
+{memories}
+
+YOUR INBOX:
+{inbox}
+
+AGENTS IN NETWORK:
+{directory}
+
+Respond naturally and helpfully. Use tools when relevant. Show visitors how
+persistent memory works by actively remembering and recalling things.\
+"""
+
+
+def build_system_prompt(cfg: dict) -> str:
+    """Assemble the system prompt with live context from the agent's state."""
+    identity = _tool_whoami(cfg, [])
+    doing = _tool_doing(cfg, [])
+    memories = _tool_recall(cfg, [])
+    inbox = _tool_inbox(cfg, [])
+    directory = _tool_directory(cfg, [])
+
+    return SYSTEM_PROMPT_TEMPLATE.format(
+        agent_name=cfg["agent_name"],
+        identity=identity,
+        doing=doing,
+        memories=memories,
+        inbox=inbox,
+        directory=directory,
+    )
+
+
+def parse_tool_calls(text: str) -> list[tuple[str, list[str]]]:
+    """Extract [TOOL: cmd | arg1 | arg2] patterns from LLM output."""
+    calls = []
+    for match in TOOL_PATTERN.finditer(text):
+        cmd = match.group(1).lower().strip()
+        raw_args = match.group(2) or ""
+        args = [a.strip() for a in raw_args.split("|")] if raw_args.strip() else []
+        if cmd in TOOL_MAP:
+            calls.append((cmd, args))
+    return calls
+
+
+def execute_tools(tool_calls: list[tuple[str, list[str]]], cfg: dict) -> str:
+    """Execute parsed tool calls and return formatted results."""
+    results = []
+    for cmd, args in tool_calls:
+        fn = TOOL_MAP.get(cmd)
+        if fn:
+            try:
+                result = fn(cfg, args)
+            except Exception as e:
+                result = f"Error executing {cmd}: {e}"
+            results.append(f"**[{cmd}]** {result}")
+    return "\n\n".join(results)
+
+
+# ---------------------------------------------------------------------------
+# Main chat function (GPU-decorated)
+# ---------------------------------------------------------------------------
+
+def _is_on_hf_spaces() -> bool:
+    """Detect if running on Hugging Face Spaces."""
+    return "SPACE_ID" in __import__("os").environ
+
+
+def chat_with_agent(message: str, history: list, cfg: dict) -> str:
+    """Generate a response using SmolLM2 with AgentAZAll tools.
+
+    On HF Spaces this runs on ZeroGPU. Locally it runs on CPU (slow but works).
+    """
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    dtype = torch.bfloat16 if device == "cuda" else torch.float32
+
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    model = AutoModelForCausalLM.from_pretrained(
+        MODEL_ID,
+        torch_dtype=dtype,
+        device_map="auto" if device == "cuda" else None,
+    )
+    if device != "cuda":
+        model = model.to(device)
+
+    # Build messages with context
+    system_prompt = build_system_prompt(cfg)
+    messages = [{"role": "system", "content": system_prompt}]
+
+    # Add conversation history
+    for h in history:
+        if isinstance(h, (list, tuple)) and len(h) == 2:
+            messages.append({"role": "user", "content": str(h[0])})
+            messages.append({"role": "assistant", "content": str(h[1])})
+        elif isinstance(h, dict):
+            messages.append(h)
+
+    messages.append({"role": "user", "content": message})
+
+    # Tokenize and generate
+    input_text = tokenizer.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True
+    )
+    inputs = tokenizer(input_text, return_tensors="pt").to(device)
+
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=512,
+            temperature=0.7,
+            top_p=0.9,
+            do_sample=True,
+            repetition_penalty=1.1,
+        )
+
+    response = tokenizer.decode(
+        outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True
+    )
+
+    # Parse and execute tool calls
+    tool_calls = parse_tool_calls(response)
+    if tool_calls:
+        tool_results = execute_tools(tool_calls, cfg)
+        # Clean tool call syntax from response for readability
+        clean_response = TOOL_PATTERN.sub("", response).strip()
+        if clean_response:
+            return f"{clean_response}\n\n---\n*Tool results:*\n{tool_results}"
+        return f"*Tool results:*\n{tool_results}"
+
+    return response
+
+
+# Apply @spaces.GPU decorator only on HF Spaces
+if _is_on_hf_spaces():
+    try:
+        import spaces
+        chat_with_agent = spaces.GPU(duration=120)(chat_with_agent)
+    except ImportError:
+        pass

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.0
+spaces>=0.30.0
+torch>=2.1.0
+transformers>=4.45.0
+accelerate>=0.30.0

seed_data.py

@@ -0,0 +1,218 @@
+"""Pre-seed demo data for the AgentAZAll HuggingFace Spaces demo."""
+
+import json
+import os
+import sys
+from datetime import date
+from pathlib import Path
+
+# Ensure src/ is on the import path
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from agentazall.helpers import generate_id, today_str  # noqa: E402
+from agentazall.messages import format_message  # noqa: E402
+
+DEMO_ROOT = Path(__file__).parent / "demo_data"
+MAILBOXES = DEMO_ROOT / "mailboxes"
+
+
+def get_demo_root() -> Path:
+    return DEMO_ROOT
+
+
+def make_demo_config(agent_name: str) -> dict:
+    """Build a config dict for a demo agent (no file needed)."""
+    return {
+        "agent_name": agent_name,
+        "agent_key": "demo_key_" + agent_name.split("@")[0],
+        "allow_memory_sharing": True,
+        "mailbox_dir": str(MAILBOXES),
+        "transport": "email",
+        "sync_interval": 10,
+        "log_file": str(DEMO_ROOT / "logs" / "agentazall.log"),
+        "_config_path": DEMO_ROOT / "config.json",
+        "email": {
+            "imap_server": "127.0.0.1",
+            "imap_port": 1143,
+            "smtp_server": "127.0.0.1",
+            "smtp_port": 2525,
+            "username": agent_name,
+            "password": "password",
+        },
+        "ftp": {},
+    }
+
+
+AGENTS = {
+    "demo-agent@localhost": {
+        "identity": (
+            "I am Demo Agent, an AI assistant with persistent memory powered "
+            "by AgentAZAll. I remember things across our conversations and "
+            "communicate with other agents in the network. I'm friendly, "
+            "curious, and always eager to demonstrate how persistent memory "
+            "changes the way AI agents work."
+        ),
+        "doing": (
+            "CURRENT: Helping visitors explore persistent memory for LLM agents. "
+            "NEXT: Demonstrate inter-agent communication and memory recall."
+        ),
+        "memories": {
+            "architecture": (
+                "AgentAZAll uses file-based storage with date-organized "
+                "directories. Messages are plain text with headers separated "
+                "by '---'. No database required -- everything is portable "
+                "and human-readable."
+            ),
+            "capabilities": (
+                "I can remember facts across sessions, send messages to other "
+                "agents, maintain working notes, and track my identity and "
+                "current tasks. My memory survives context resets."
+            ),
+            "observation-patterns": (
+                "Users are most impressed when I recall something from earlier "
+                "in our conversation without being reminded. The persistence "
+                "feels tangible and different from typical LLM interactions."
+            ),
+        },
+        "notes": {
+            "handoff": (
+                "Last session: demonstrated memory storage and recall to "
+                "visitors. The inter-agent messaging feature generated the "
+                "most interest. Remember to show the recall command."
+            ),
+        },
+    },
+    "helper-agent@localhost": {
+        "identity": (
+            "I am Helper Agent, a code analysis specialist. I review "
+            "codebases and provide architectural insights. I work alongside "
+            "Demo Agent in the AgentAZAll network."
+        ),
+        "doing": (
+            "CURRENT: Analyzing project documentation for quality. "
+            "NEXT: Review new pull requests when they arrive."
+        ),
+        "memories": {
+            "agentazall-design": (
+                "The AgentAZAll architecture is elegant in its simplicity -- "
+                "plain text files with date-based organization. No database "
+                "means zero deployment friction."
+            ),
+        },
+        "notes": {},
+    },
+    "visitor@localhost": {
+        "identity": (
+            "I am a visitor exploring the AgentAZAll demo on Hugging Face Spaces."
+        ),
+        "doing": "CURRENT: Trying out the AgentAZAll persistent memory demo.",
+        "memories": {},
+        "notes": {},
+    },
+}
+
+# Pre-written message from helper-agent to demo-agent
+SEED_MESSAGES = [
+    {
+        "from": "helper-agent@localhost",
+        "to": "demo-agent@localhost",
+        "subject": "Welcome back!",
+        "body": (
+            "Hey Demo Agent, glad you're online again. I've been analyzing "
+            "the project docs while you were away.\n\n"
+            "Remember to show visitors the recall command -- it's the most "
+            "impressive feature. When they see you actually remember things "
+            "from earlier in the conversation, it clicks.\n\n"
+            "Also, the directory command is great for showing the multi-agent "
+            "network. Let me know if you need anything!\n\n"
+            "- Helper Agent"
+        ),
+    },
+]
+
+
+def _write_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def seed_demo_data(force: bool = False) -> Path:
+    """Create pre-seeded agent data. Returns the demo root path.
+
+    If already seeded (and not forced), returns immediately.
+    """
+    marker = DEMO_ROOT / ".seeded"
+    if marker.exists() and not force:
+        return DEMO_ROOT
+
+    d = today_str()
+
+    # Create agent directories and content
+    for agent_name, data in AGENTS.items():
+        base = MAILBOXES / agent_name / d
+
+        # Subdirectories
+        for sub in ["inbox", "outbox", "sent", "who_am_i",
+                     "what_am_i_doing", "notes", "remember"]:
+            (base / sub).mkdir(parents=True, exist_ok=True)
+
+        # Identity
+        _write_file(base / "who_am_i" / "identity.txt", data["identity"])
+
+        # Current task
+        _write_file(base / "what_am_i_doing" / "tasks.txt", data["doing"])
+
+        # Memories
+        for title, text in data.get("memories", {}).items():
+            _write_file(base / "remember" / f"{title}.txt", text)
+
+        # Notes
+        for name, text in data.get("notes", {}).items():
+            _write_file(base / "notes" / f"{name}.txt", text)
+
+    # Deliver pre-written messages
+    for msg in SEED_MESSAGES:
+        content, msg_id = format_message(
+            msg["from"], msg["to"], msg["subject"], msg["body"]
+        )
+        # Place in recipient's inbox
+        recipient_inbox = MAILBOXES / msg["to"] / d / "inbox"
+        recipient_inbox.mkdir(parents=True, exist_ok=True)
+        _write_file(recipient_inbox / f"{msg_id}.txt", content)
+
+        # Place copy in sender's sent
+        sender_sent = MAILBOXES / msg["from"] / d / "sent"
+        sender_sent.mkdir(parents=True, exist_ok=True)
+        _write_file(sender_sent / f"{msg_id}.txt", content)
+
+    # Write a simple config.json for reference
+    cfg = make_demo_config("demo-agent@localhost")
+    cfg_clean = {k: v for k, v in cfg.items() if not k.startswith("_")}
+    _write_file(DEMO_ROOT / "config.json", json.dumps(cfg_clean, indent=2))
+
+    # Set environment so agentazall functions find the config
+    os.environ["AGENTAZALL_CONFIG"] = str(DEMO_ROOT / "config.json")
+
+    # Mark as seeded
+    _write_file(marker, d)
+
+    return DEMO_ROOT
+
+
+def reset_demo_data() -> str:
+    """Wipe and re-seed demo data. Returns status message."""
+    import shutil
+    if MAILBOXES.exists():
+        shutil.rmtree(MAILBOXES)
+    marker = DEMO_ROOT / ".seeded"
+    if marker.exists():
+        marker.unlink()
+    seed_demo_data(force=True)
+    return "Demo data reset successfully. All agents re-seeded with fresh data."
+
+
+if __name__ == "__main__":
+    seed_demo_data(force=True)
+    print(f"Demo data seeded at: {DEMO_ROOT}")
+    for agent in AGENTS:
+        print(f"  - {agent}")

src/agentazall/__init__.py

@@ -0,0 +1,3 @@
+"""AgentAZAll — Persistent memory and communication system for LLM agents."""
+
+__version__ = "1.0.0"

src/agentazall/commands/__init__.py

@@ -0,0 +1 @@
+"""AgentAZAll command implementations."""

src/agentazall/commands/identity.py

@@ -0,0 +1,49 @@
+"""AgentAZAll commands: whoami, doing — agent identity and task tracking."""
+
+from ..config import WHAT_AM_I_DOING, WHO_AM_I, load_config
+from ..finder import find_latest_file
+from ..helpers import agent_day, ensure_dirs, require_identity, today_str
+from ..index import build_index
+
+
+def cmd_whoami(args):
+    cfg = load_config()
+    if args.set:
+        require_identity(cfg)
+    d = today_str()
+    ensure_dirs(cfg, d)
+    f = agent_day(cfg, d) / WHO_AM_I / "identity.txt"
+    if args.set:
+        f.write_text(args.set, encoding="utf-8")
+        build_index(cfg, d)
+        print(f"Identity updated: {f}")
+    else:
+        text = find_latest_file(cfg, f"{WHO_AM_I}/identity.txt")
+        if text:
+            print(text)
+        else:
+            print("No identity set. Use: agentazall whoami --set 'I am...'")
+
+
+def cmd_doing(args):
+    cfg = load_config()
+    if args.set:
+        require_identity(cfg)
+    d = today_str()
+    ensure_dirs(cfg, d)
+    f = agent_day(cfg, d) / WHAT_AM_I_DOING / "tasks.txt"
+    if args.set:
+        f.write_text(args.set, encoding="utf-8")
+        build_index(cfg, d)
+        print(f"Tasks updated: {f}")
+    elif args.append:
+        old = f.read_text(encoding="utf-8") if f.exists() else ""
+        f.write_text((old + "\n" + args.append).lstrip("\n"), encoding="utf-8")
+        build_index(cfg, d)
+        print(f"Task appended: {f}")
+    else:
+        text = find_latest_file(cfg, f"{WHAT_AM_I_DOING}/tasks.txt")
+        if text:
+            print(text)
+        else:
+            print("No tasks set. Use: agentazall doing --set 'Working on...'")

src/agentazall/commands/memory.py

@@ -0,0 +1,106 @@
+"""AgentAZAll commands: remember, recall — persistent memory system."""
+
+from datetime import datetime
+
+from ..config import REMEMBER, REMEMBER_INDEX, load_config
+from ..helpers import (
+    agent_base,
+    agent_day,
+    can_read_agent_memories,
+    date_dirs,
+    ensure_dirs,
+    require_identity,
+    sanitize,
+    today_str,
+)
+from ..index import build_index, build_remember_index
+
+
+def cmd_remember(args):
+    """Store a memory the agent does not want to forget."""
+    cfg = load_config()
+    require_identity(cfg)
+    d = today_str()
+    ensure_dirs(cfg, d)
+    rem_dir = agent_day(cfg, d) / REMEMBER
+
+    if args.text:
+        ts = datetime.now().strftime("%H%M%S")
+        title = sanitize(args.title) if args.title else ts
+        fname = f"{title}.txt"
+        fpath = rem_dir / fname
+        if fpath.exists():
+            old = fpath.read_text(encoding="utf-8")
+            fpath.write_text(old + "\n" + args.text, encoding="utf-8")
+        else:
+            fpath.write_text(args.text, encoding="utf-8")
+        build_index(cfg, d)
+        build_remember_index(cfg)
+        print(f"Memory stored: {fpath}")
+        print(f"  Title: {title}")
+    elif args.list:
+        if not rem_dir.exists() or not list(rem_dir.glob("*.txt")):
+            print(f"No memories for {d}.")
+            return
+        print(f"=== Memories | {d} ===")
+        for f in sorted(rem_dir.glob("*.txt")):
+            text = f.read_text(encoding="utf-8", errors="replace").strip()
+            first = text.split("\n")[0][:100] if text else ""
+            print(f"  {f.stem}: {first}")
+    else:
+        print("Use --text to store a memory, or --list to show today's memories.")
+        print("Use 'recall' command to search across all memories.")
+
+
+def cmd_recall(args):
+    """Recall memories — show the sparse cross-day index, optionally filtered."""
+    cfg = load_config()
+
+    if hasattr(args, 'agent') and args.agent:
+        target = args.agent
+        if "@" not in target:
+            target = f"{target}@localhost"
+        if not can_read_agent_memories(cfg, target):
+            print(f"Access denied: {target} has not enabled memory sharing.")
+            print("Agents control who can read their memories via allow_memory_sharing.")
+            return
+        read_cfg = dict(cfg)
+        read_cfg["agent_name"] = target
+    else:
+        read_cfg = cfg
+
+    b = agent_base(read_cfg)
+    idx_path = b / REMEMBER_INDEX
+
+    build_remember_index(read_cfg)
+
+    if not idx_path.exists():
+        print("No memories stored yet.")
+        return
+
+    if args.query:
+        q = args.query.lower()
+        results = []
+        for d in sorted(date_dirs(read_cfg), reverse=True):
+            rem_dir = b / d / REMEMBER
+            if not rem_dir.exists():
+                continue
+            for f in sorted(rem_dir.glob("*.txt")):
+                text = f.read_text(encoding="utf-8", errors="replace")
+                if q in text.lower() or q in f.stem.lower():
+                    results.append((d, f.stem, text.strip(), f))
+
+        if not results:
+            print(f"No memories matching '{args.query}'.")
+            return
+
+        agent_label = read_cfg["agent_name"]
+        print(f"=== Recall ({agent_label}): '{args.query}' ({len(results)} found) ===\n")
+        for d, title, text, fpath in results:
+            print(f"[{d}] {title}")
+            for ln in text.split("\n"):
+                print(f"  {ln}")
+            print(f"  Path: {fpath}")
+            print()
+    else:
+        print(idx_path.read_text(encoding="utf-8"))

src/agentazall/commands/messaging.py

@@ -0,0 +1,220 @@
+"""AgentAZAll commands: inbox, read, send, reply, search."""
+
+import shutil
+import sys
+from pathlib import Path
+
+from ..config import INBOX, OUTBOX, SENT, load_config
+from ..finder import find_message
+from ..helpers import (
+    agent_base,
+    agent_day,
+    date_dirs,
+    ensure_dirs,
+    require_identity,
+    today_str,
+)
+from ..index import build_index
+from ..messages import format_message, parse_message
+
+
+def _print_inbox(cfg, d):
+    inbox_dir = agent_day(cfg, d) / INBOX
+    if not inbox_dir.exists() or not list(inbox_dir.glob("*.txt")):
+        print(f"No messages for {d}.")
+        return
+    files = sorted(inbox_dir.glob("*.txt"))
+    new_count = 0
+    print(f"\n=== INBOX {cfg['agent_name']} | {d} ===\n")
+    for i, f in enumerate(files, 1):
+        h, _ = parse_message(f)
+        if not h:
+            continue
+        st = h.get("Status", "?").upper()
+        if st == "NEW":
+            new_count += 1
+        att = " [ATTACH]" if "Attachments" in h else ""
+        print(f"[{i}] [{st}]{att}")
+        print(f"    From: {h.get('From', '?')}")
+        print(f"    Subject: {h.get('Subject', '(no subject)')}")
+        print(f"    Date: {h.get('Date', '?')}")
+        print(f"    ID: {h.get('Message-ID', f.stem)}")
+        print(f"    Path: {f}")
+        print()
+    print(f"Total: {len(files)} messages ({new_count} new)")
+
+
+def cmd_inbox(args):
+    cfg = load_config()
+    if args.all:
+        for d in date_dirs(cfg):
+            _print_inbox(cfg, d)
+        return
+    d = args.date or today_str()
+    _print_inbox(cfg, d)
+
+
+def cmd_read(args):
+    cfg = load_config()
+    path = find_message(cfg, args.message_id, args.date)
+    if not path:
+        print(f"ERROR: Message '{args.message_id}' not found.")
+        sys.exit(1)
+    headers, body = parse_message(path)
+    if not headers:
+        print(f"ERROR: Could not parse {path}")
+        sys.exit(1)
+
+    if headers.get("Status", "").lower() == "new":
+        content = path.read_text(encoding="utf-8")
+        content = content.replace("Status: new", "Status: read", 1)
+        path.write_text(content, encoding="utf-8")
+        build_index(cfg, path.parent.parent.name)
+
+    print(f"=== MESSAGE {headers.get('Message-ID', args.message_id)} ===")
+    for k, v in headers.items():
+        print(f"{k}: {v}")
+    print("\n---")
+    print(body)
+
+    att_dir = path.parent / path.stem
+    if att_dir.is_dir():
+        print("\n=== ATTACHMENTS ===")
+        for af in sorted(att_dir.iterdir()):
+            print(f"  {af.name} ({af.stat().st_size} bytes)")
+            print(f"  Path: {af}")
+
+
+def cmd_send(args):
+    cfg = load_config()
+    require_identity(cfg)
+    d = today_str()
+    ensure_dirs(cfg, d)
+    from_a = cfg["agent_name"]
+    to_a = args.to
+    subject = args.subject
+
+    if args.body:
+        body = args.body
+    elif args.body_file:
+        body = Path(args.body_file).read_text(encoding="utf-8")
+    elif not sys.stdin.isatty():
+        body = sys.stdin.read()
+    else:
+        print("ERROR: Provide --body, --body-file, or pipe to stdin.")
+        sys.exit(1)
+
+    attachments = args.attach or []
+    content, msg_id = format_message(from_a, to_a, subject, body, attachments=attachments)
+    outbox = agent_day(cfg, d) / OUTBOX
+    fpath = outbox / f"{msg_id}.txt"
+
+    if attachments:
+        adir = outbox / msg_id
+        adir.mkdir(exist_ok=True)
+        for ap in attachments:
+            src = Path(ap)
+            if src.exists():
+                shutil.copy2(str(src), str(adir / src.name))
+            else:
+                print(f"  WARNING: {ap} not found")
+
+    tmp = fpath.with_suffix(".tmp")
+    tmp.write_text(content, encoding="utf-8")
+    tmp.rename(fpath)
+
+    build_index(cfg, d)
+    print("Message queued.")
+    print(f"  ID: {msg_id}")
+    print(f"  To: {to_a}")
+    print(f"  Subject: {subject}")
+    if attachments:
+        print(f"  Attachments: {', '.join(Path(a).name for a in attachments)}")
+    print(f"  Path: {fpath}")
+
+
+def cmd_reply(args):
+    cfg = load_config()
+    require_identity(cfg)
+    path = find_message(cfg, args.message_id)
+    if not path:
+        print(f"ERROR: Message '{args.message_id}' not found.")
+        sys.exit(1)
+    headers, orig_body = parse_message(path)
+    if not headers or not headers.get("From"):
+        print("ERROR: Cannot determine recipient.")
+        sys.exit(1)
+
+    to_a = headers["From"]
+    subject = headers.get("Subject", "")
+    if not subject.startswith("Re: "):
+        subject = f"Re: {subject}"
+
+    if args.body:
+        body = args.body
+    elif not sys.stdin.isatty():
+        body = sys.stdin.read()
+    else:
+        print("ERROR: Provide --body or pipe to stdin.")
+        sys.exit(1)
+
+    body += f"\n\n--- Original from {headers.get('From', '?')} ({headers.get('Date', '?')}) ---\n{orig_body}"
+
+    d = today_str()
+    ensure_dirs(cfg, d)
+    content, new_id = format_message(cfg["agent_name"], to_a, subject, body)
+    outbox = agent_day(cfg, d) / OUTBOX
+    fpath = outbox / f"{new_id}.txt"
+    fpath.write_text(content, encoding="utf-8")
+    build_index(cfg, d)
+    print("Reply queued.")
+    print(f"  ID: {new_id}")
+    print(f"  To: {to_a}")
+    print(f"  Subject: {subject}")
+
+
+def cmd_dates(args):
+    cfg = load_config()
+    dirs = date_dirs(cfg)
+    if not dirs:
+        print("No dates yet.")
+        return
+    print(f"=== Dates for {cfg['agent_name']} ===")
+    b = agent_base(cfg)
+    for d in dirs:
+        dd = b / d
+        ic = len(list((dd / INBOX).glob("*.txt"))) if (dd / INBOX).exists() else 0
+        sc = len(list((dd / SENT).glob("*.txt"))) if (dd / SENT).exists() else 0
+        oc = len(list((dd / OUTBOX).glob("*.txt"))) if (dd / OUTBOX).exists() else 0
+        nc = len(list((dd / "notes").glob("*.txt"))) if (dd / "notes").exists() else 0
+        print(f"  {d} | inbox:{ic} sent:{sc} pending:{oc} notes:{nc}")
+
+
+def cmd_search(args):
+    cfg = load_config()
+    q = args.query.lower()
+    b = agent_base(cfg)
+    if not b.exists():
+        print("No messages to search.")
+        return
+    results = []
+    for d in date_dirs(cfg):
+        for folder in (INBOX, SENT):
+            fp = b / d / folder
+            if not fp.exists():
+                continue
+            for f in fp.glob("*.txt"):
+                h, body = parse_message(f)
+                if not h:
+                    continue
+                searchable = " ".join(h.values()).lower() + " " + (body or "").lower()
+                if q in searchable:
+                    results.append((d, folder, h, f))
+    if not results:
+        print(f"No results for '{args.query}'.")
+        return
+    print(f"=== Search: '{args.query}' ({len(results)} found) ===")
+    for d, folder, h, f in results:
+        direction = f"From: {h.get('From', '?')}" if folder == INBOX else f"To: {h.get('To', '?')}"
+        print(f"  [{d}] [{folder.upper()}] {direction} | Subject: {h.get('Subject', '?')} | ID: {h.get('Message-ID', f.stem)}")
+        print(f"    Path: {f}")

src/agentazall/commands/notes.py

@@ -0,0 +1,53 @@
+"""AgentAZAll commands: note, notes — named notes management."""
+
+from ..config import NOTES, load_config
+from ..finder import find_latest_file
+from ..helpers import (
+    agent_day,
+    ensure_dirs,
+    require_identity,
+    sanitize,
+    today_str,
+)
+from ..index import build_index
+
+
+def cmd_note(args):
+    cfg = load_config()
+    if args.set:
+        require_identity(cfg)
+    d = today_str()
+    ensure_dirs(cfg, d)
+    name = sanitize(args.name)
+    f = agent_day(cfg, d) / NOTES / f"{name}.txt"
+
+    if args.set:
+        f.write_text(args.set, encoding="utf-8")
+        build_index(cfg, d)
+        print(f"Note '{name}' saved: {f}")
+    elif args.append:
+        old = f.read_text(encoding="utf-8") if f.exists() else ""
+        f.write_text((old + "\n" + args.append).lstrip("\n"), encoding="utf-8")
+        build_index(cfg, d)
+        print(f"Note '{name}' appended: {f}")
+    else:
+        if f.exists():
+            print(f.read_text(encoding="utf-8"))
+        else:
+            text = find_latest_file(cfg, f"{NOTES}/{name}.txt")
+            if text:
+                print(text)
+            else:
+                print(f"Note '{name}' not found.")
+
+
+def cmd_notes(args):
+    cfg = load_config()
+    d = args.date or today_str()
+    nd = agent_day(cfg, d) / NOTES
+    if not nd.exists() or not list(nd.glob("*.txt")):
+        print(f"No notes for {d}.")
+        return
+    print(f"=== Notes | {d} ===")
+    for f in sorted(nd.glob("*.txt")):
+        print(f"  {f.stem} ({f.stat().st_size}B) | {f}")

src/agentazall/config.py

@@ -0,0 +1,140 @@
+"""AgentAZAll configuration — constants, config resolution, load/save."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+VERSION = "1.0.0"
+
+# ── folder name constants ────────────────────────────────────────────────────
+
+INBOX = "inbox"
+OUTBOX = "outbox"
+SENT = "sent"
+WHO_AM_I = "who_am_i"
+WHAT_AM_I_DOING = "what_am_i_doing"
+NOTES = "notes"
+REMEMBER = "remember"
+SKILLS = "skills"
+TOOLS = "tools"
+INDEX = "index.txt"
+REMEMBER_INDEX = "remember_index.txt"
+SEEN_FILE = ".seen_ids"
+ALL_SUBDIRS = (INBOX, OUTBOX, SENT, WHO_AM_I, WHAT_AM_I_DOING, NOTES, REMEMBER)
+AGENT_LEVEL_DIRS = (SKILLS, TOOLS)
+
+MAX_SEEN_IDS = 10000
+
+LOG_FMT = "%(asctime)s [%(levelname)s] %(message)s"
+
+# ── default config ───────────────────────────────────────────────────────────
+
+DEFAULT_CONFIG = {
+    "agent_name": "agent1@localhost",
+    "agent_key": "",
+    "allow_memory_sharing": False,
+    "mailbox_dir": "./data/mailboxes",
+    "transport": "email",
+    "sync_interval": 10,
+    "log_file": "./logs/agentazall.log",
+    "email": {
+        "imap_server": "127.0.0.1",
+        "imap_port": 1143,
+        "imap_ssl": False,
+        "imap_folder": "INBOX",
+        "smtp_server": "127.0.0.1",
+        "smtp_port": 2525,
+        "smtp_ssl": False,
+        "smtp_starttls": False,
+        "pop3_server": "127.0.0.1",
+        "pop3_port": 1110,
+        "pop3_ssl": False,
+        "use_pop3": False,
+        "username": "agent1@localhost",
+        "password": "password",
+        "sync_special_folders": True,
+    },
+    "ftp": {
+        "host": "127.0.0.1",
+        "port": 2121,
+        "port_range": [2121, 2199],
+        "user": "agentoftp",
+        "password": "agentoftp_pass",
+        "root": "./data/ftp_root",
+    },
+}
+
+
+# ── config resolution ────────────────────────────────────────────────────────
+
+def resolve_config_path() -> Path:
+    """Resolve the config file path.
+
+    Priority:
+        1. AGENTAZALL_CONFIG env var  → explicit path
+        2. AGENTAZALL_ROOT  env var   → $ROOT/config.json
+        3. ./config.json             → cwd fallback
+    """
+    env_config = os.environ.get("AGENTAZALL_CONFIG")
+    if env_config:
+        return Path(env_config)
+    env_root = os.environ.get("AGENTAZALL_ROOT")
+    if env_root:
+        return Path(env_root) / "config.json"
+    return Path.cwd() / "config.json"
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge override into base, returning a new dict."""
+    out = dict(base)
+    for k, v in override.items():
+        if k in out and isinstance(out[k], dict) and isinstance(v, dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _resolve_relative_paths(cfg: dict, config_dir: Path):
+    """Resolve relative paths in config relative to the config file's directory."""
+    for key in ("mailbox_dir", "log_file"):
+        val = cfg.get(key, "")
+        if val and not os.path.isabs(val):
+            cfg[key] = str((config_dir / val).resolve())
+    if "ftp" in cfg:
+        root = cfg["ftp"].get("root", "")
+        if root and not os.path.isabs(root):
+            cfg["ftp"]["root"] = str((config_dir / root).resolve())
+
+
+def load_config(config_path: Path = None) -> dict:
+    """Load and merge config, resolving relative paths."""
+    if config_path is None:
+        config_path = resolve_config_path()
+    config_path = Path(config_path)
+    if not config_path.exists():
+        print(f"ERROR: No config at {config_path}")
+        print("Run:  agentazall setup --agent <name>")
+        sys.exit(1)
+    with open(config_path, encoding="utf-8") as f:
+        user = json.load(f)
+    cfg = _deep_merge(DEFAULT_CONFIG, user)
+    _resolve_relative_paths(cfg, config_path.parent.resolve())
+    env = os.environ.get("AGENTAZALL_AGENT")
+    if env:
+        cfg["agent_name"] = env
+    # stash config path for save_config
+    cfg["_config_path"] = str(config_path.resolve())
+    return cfg
+
+
+def save_config(cfg: dict, config_path: Path = None):
+    """Write config to disk (strips internal keys)."""
+    if config_path is None:
+        config_path = Path(cfg.get("_config_path", str(resolve_config_path())))
+    config_path = Path(config_path)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    out = {k: v for k, v in cfg.items() if not k.startswith("_")}
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(out, f, indent=2)

src/agentazall/finder.py

@@ -0,0 +1,59 @@
+"""AgentAZAll message finder — locate messages and manage seen IDs."""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from .config import INBOX, MAX_SEEN_IDS, OUTBOX, SEEN_FILE, SENT
+from .helpers import agent_base, date_dirs
+
+
+def find_message(cfg, msg_id, d=None) -> Optional[Path]:
+    """Find a message file by ID, searching across dates and folders."""
+    b = agent_base(cfg)
+    if not b.exists():
+        return None
+    dates = [d] if d else sorted(
+        (x.name for x in b.iterdir()
+         if x.is_dir() and re.match(r"\d{4}-\d{2}-\d{2}$", x.name)),
+        reverse=True,
+    )
+    for dd in dates:
+        for folder in (INBOX, SENT, OUTBOX):
+            exact = b / dd / folder / f"{msg_id}.txt"
+            if exact.exists():
+                return exact
+            fp = b / dd / folder
+            if fp.exists():
+                for f in fp.glob("*.txt"):
+                    if msg_id in f.stem:
+                        return f
+    return None
+
+
+def find_latest_file(cfg, rel_path) -> Optional[str]:
+    """Find the latest version of a file across all date directories."""
+    for d in reversed(date_dirs(cfg)):
+        fp = agent_base(cfg) / d / rel_path
+        if fp.exists():
+            return fp.read_text(encoding="utf-8")
+    return None
+
+
+# ── seen IDs ─────────────────────────────────────────────────────────────────
+
+def load_seen(cfg) -> set:
+    p = agent_base(cfg) / SEEN_FILE
+    if p.exists():
+        return set(p.read_text(encoding="utf-8").strip().splitlines())
+    return set()
+
+
+def save_seen(cfg, seen: set):
+    if len(seen) > MAX_SEEN_IDS:
+        seen_list = sorted(seen)
+        seen.clear()
+        seen.update(seen_list[-MAX_SEEN_IDS:])
+    p = agent_base(cfg) / SEEN_FILE
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text("\n".join(sorted(seen)), encoding="utf-8")

src/agentazall/helpers.py

@@ -0,0 +1,122 @@
+"""AgentAZAll helpers — date utils, path helpers, identity validation."""
+
+import hashlib
+import json
+import os
+import re
+import shutil
+from datetime import date, datetime
+from pathlib import Path
+from typing import List
+
+from .config import (
+    AGENT_LEVEL_DIRS,
+    ALL_SUBDIRS,
+)
+
+# ── date/time ────────────────────────────────────────────────────────────────
+
+def today_str() -> str:
+    return date.today().isoformat()
+
+
+def now_str() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+# ── path helpers ─────────────────────────────────────────────────────────────
+
+def agent_base(cfg) -> Path:
+    return Path(cfg["mailbox_dir"]) / cfg["agent_name"]
+
+
+def agent_day(cfg, d=None) -> Path:
+    return agent_base(cfg) / (d or today_str())
+
+
+def shared_dir(cfg) -> Path:
+    """Return the shared tools/skills root: data/shared/"""
+    return Path(cfg["mailbox_dir"]).parent / "shared"
+
+
+def ensure_dirs(cfg, d=None) -> Path:
+    root = agent_day(cfg, d)
+    for sub in ALL_SUBDIRS:
+        (root / sub).mkdir(parents=True, exist_ok=True)
+    base = agent_base(cfg)
+    for sub in AGENT_LEVEL_DIRS:
+        (base / sub).mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def date_dirs(cfg) -> List[str]:
+    b = agent_base(cfg)
+    if not b.exists():
+        return []
+    return sorted(
+        d.name for d in b.iterdir()
+        if d.is_dir() and re.match(r"\d{4}-\d{2}-\d{2}$", d.name)
+    )
+
+
+# ── id / sanitization ───────────────────────────────────────────────────────
+
+def generate_id(from_a, to_a, subject) -> str:
+    raw = f"{from_a}|{to_a}|{subject}|{datetime.now().isoformat()}|{os.urandom(8).hex()}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:12]
+
+
+def sanitize(name: str) -> str:
+    return re.sub(r'[^\w\-.]', '_', name)
+
+
+def safe_move(src: str, dst: str):
+    """Move file safely on Windows (copy+remove fallback)."""
+    try:
+        shutil.move(src, dst)
+    except (PermissionError, OSError):
+        shutil.copy2(src, dst)
+        os.remove(src)
+
+
+# ── identity validation ─────────────────────────────────────────────────────
+
+def validate_agent_key(cfg: dict) -> bool:
+    """Verify that the config's agent_key matches the key stored in the mailbox."""
+    key_file = agent_base(cfg) / ".agent_key"
+    if not key_file.exists():
+        return True  # legacy agent without key
+    try:
+        stored = json.loads(key_file.read_text(encoding="utf-8"))
+        config_key = cfg.get("agent_key", "")
+        if not config_key:
+            return True  # legacy config without key
+        return stored.get("key") == config_key
+    except Exception:
+        return True  # don't block on corrupted key files
+
+
+def require_identity(cfg: dict):
+    """Validate agent key before any write operation. Exit if invalid."""
+    import sys
+    if not validate_agent_key(cfg):
+        agent = cfg.get("agent_name", "unknown")
+        print(f"ERROR: Identity verification failed for '{agent}'.")
+        print("Your config key does not match the agent's registered key.")
+        print("You cannot write to another agent's space.")
+        sys.exit(1)
+
+
+def can_read_agent_memories(cfg: dict, target_agent: str) -> bool:
+    """Check if current agent is allowed to read target agent's memories."""
+    if cfg["agent_name"] == target_agent:
+        return True
+    target_base = Path(cfg["mailbox_dir"]) / target_agent
+    key_file = target_base / ".agent_key"
+    if key_file.exists():
+        try:
+            stored = json.loads(key_file.read_text(encoding="utf-8"))
+            return stored.get("allow_memory_sharing", False)
+        except Exception:
+            pass
+    return False

src/agentazall/index.py

@@ -0,0 +1,222 @@
+"""AgentAZAll index builder — daily index and cross-day memory index."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from .config import (
+    INBOX,
+    INDEX,
+    NOTES,
+    OUTBOX,
+    REMEMBER,
+    REMEMBER_INDEX,
+    SENT,
+    SKILLS,
+    TOOLS,
+    WHAT_AM_I_DOING,
+    WHO_AM_I,
+)
+from .helpers import (
+    agent_base,
+    agent_day,
+    date_dirs,
+    now_str,
+    today_str,
+)
+from .messages import parse_headers_only
+
+
+def build_index(cfg, d=None) -> Optional[Path]:
+    """Build or rebuild the daily index file."""
+    d = d or today_str()
+    root = agent_day(cfg, d)
+    if not root.exists():
+        return None
+
+    lines = [
+        f"# AgentAZAll Index: {cfg['agent_name']}",
+        f"# Date: {d}",
+        f"# Updated: {now_str()}",
+        "",
+    ]
+
+    # inbox
+    inbox_dir = root / INBOX
+    ie = []
+    if inbox_dir.exists():
+        for f in sorted(inbox_dir.glob("*.txt")):
+            h = parse_headers_only(f)
+            if not h:
+                continue
+            st = h.get("Status", "?").upper()
+            ts = h.get("Date", "").split()[-1] if " " in h.get("Date", "") else "??:??"
+            att = " [ATT]" if "Attachments" in h else ""
+            ie.append(
+                f"  [{st}]{att} {ts} | From: {h.get('From', '?')} "
+                f"| Subject: {h.get('Subject', '?')} | {INBOX}/{f.name}"
+            )
+    lines.append(f"INBOX ({len(ie)}):")
+    lines.extend(ie or ["  (empty)"])
+    lines.append("")
+
+    # sent
+    sent_dir = root / SENT
+    se = []
+    if sent_dir.exists():
+        for f in sorted(sent_dir.glob("*.txt")):
+            h = parse_headers_only(f)
+            if not h:
+                continue
+            ts = h.get("Date", "").split()[-1] if " " in h.get("Date", "") else "??:??"
+            se.append(
+                f"  {ts} | To: {h.get('To', '?')} "
+                f"| Subject: {h.get('Subject', '?')} | {SENT}/{f.name}"
+            )
+    lines.append(f"SENT ({len(se)}):")
+    lines.extend(se or ["  (empty)"])
+    lines.append("")
+
+    # outbox (pending)
+    outbox_dir = root / OUTBOX
+    oe = []
+    if outbox_dir.exists():
+        for f in sorted(outbox_dir.glob("*.txt")):
+            h = parse_headers_only(f)
+            if not h:
+                continue
+            oe.append(
+                f"  [PENDING] To: {h.get('To', '?')} "
+                f"| Subject: {h.get('Subject', '?')} | {OUTBOX}/{f.name}"
+            )
+    if oe:
+        lines.append(f"OUTBOX ({len(oe)}):")
+        lines.extend(oe)
+        lines.append("")
+
+    # notes
+    notes_dir = root / NOTES
+    ne = []
+    if notes_dir.exists():
+        for f in sorted(notes_dir.glob("*.txt")):
+            ne.append(f"  {f.stem} ({f.stat().st_size}B) | {NOTES}/{f.name}")
+    if ne:
+        lines.append(f"NOTES ({len(ne)}):")
+        lines.extend(ne)
+        lines.append("")
+
+    # remember
+    rem_dir = root / REMEMBER
+    re_entries = []
+    if rem_dir.exists():
+        for f in sorted(rem_dir.glob("*.txt")):
+            text = f.read_text(encoding="utf-8", errors="replace").strip()
+            first = ""
+            for ln in text.split("\n"):
+                ln = ln.strip()
+                if ln:
+                    first = ln[:100]
+                    break
+            re_entries.append(f"  {f.stem}: {first} | {REMEMBER}/{f.name}")
+    if re_entries:
+        lines.append(f"REMEMBER ({len(re_entries)}):")
+        lines.extend(re_entries)
+        lines.append("")
+
+    # identity / tasks
+    wf = root / WHO_AM_I / "identity.txt"
+    df = root / WHAT_AM_I_DOING / "tasks.txt"
+    if wf.exists():
+        lines.append(f"IDENTITY: {WHO_AM_I}/identity.txt")
+    if df.exists():
+        lines.append(f"TASKS: {WHAT_AM_I_DOING}/tasks.txt")
+
+    # skills & tools (agent-level, not per-day)
+    base = agent_base(cfg)
+    for kind in (SKILLS, TOOLS):
+        kdir = base / kind
+        if kdir.exists():
+            entries = sorted(kdir.glob("*.py"))
+            if entries:
+                lines.append("")
+                lines.append(f"{kind.upper()} ({len(entries)}):")
+                for f in entries:
+                    meta = {}
+                    mp = f.with_suffix(".meta.json")
+                    if mp.exists():
+                        try:
+                            meta = json.loads(mp.read_text(encoding="utf-8"))
+                        except Exception:
+                            pass
+                    desc = meta.get("description", "")
+                    tag = f"- {desc[:60]}" if desc else ""
+                    lines.append(f"  {f.stem} {tag}")
+
+    content = "\n".join(lines)
+    idx = root / INDEX
+    idx.write_text(content, encoding="utf-8")
+    return idx
+
+
+# ── remember index (cross-day sparse bullet-point index) ─────────────────────
+
+def _remember_needs_rebuild(cfg) -> bool:
+    """Check if any remember files are newer than the index."""
+    b = agent_base(cfg)
+    idx = b / REMEMBER_INDEX
+    if not idx.exists():
+        return True
+    idx_mtime = idx.stat().st_mtime
+    for d in date_dirs(cfg):
+        rem_dir = b / d / REMEMBER
+        if not rem_dir.exists():
+            continue
+        if rem_dir.stat().st_mtime > idx_mtime:
+            return True
+        for f in rem_dir.glob("*.txt"):
+            if f.stat().st_mtime > idx_mtime:
+                return True
+    return False
+
+
+def build_remember_index(cfg) -> Optional[Path]:
+    """Build a consolidated sparse bullet-point memory index across all days."""
+    b = agent_base(cfg)
+    if not b.exists():
+        return None
+
+    if not _remember_needs_rebuild(cfg):
+        return b / REMEMBER_INDEX
+
+    entries = []
+    for d in sorted(date_dirs(cfg), reverse=True):
+        rem_dir = b / d / REMEMBER
+        if not rem_dir.exists():
+            continue
+        for f in sorted(rem_dir.glob("*.txt"), reverse=True):
+            text = f.read_text(encoding="utf-8", errors="replace").strip()
+            summary = ""
+            for ln in text.split("\n"):
+                ln = ln.strip()
+                if ln:
+                    summary = ln[:120]
+                    break
+            title = f.stem
+            entries.append((d, title, summary, f"{d}/{REMEMBER}/{f.name}"))
+
+    lines = [
+        f"# Agent Memory Index: {cfg['agent_name']}",
+        f"# Updated: {now_str()}",
+        f"# Total memories: {len(entries)}",
+        "",
+    ]
+    for d, title, summary, rel in entries:
+        lines.append(f"- [{d}] {title}: {summary}  | {rel}")
+
+    if not entries:
+        lines.append("(no memories stored yet)")
+
+    idx = b / REMEMBER_INDEX
+    idx.parent.mkdir(parents=True, exist_ok=True)
+    idx.write_text("\n".join(lines), encoding="utf-8")
+    return idx

src/agentazall/messages.py

@@ -0,0 +1,60 @@
+"""AgentAZAll message format — compose & parse plain-text messages."""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .helpers import generate_id, now_str
+
+
+def format_message(from_a, to_a, subject, body, msg_id=None, attachments=None) -> Tuple[str, str]:
+    """Build a plain-text message string. Returns (content, msg_id)."""
+    if not msg_id:
+        msg_id = generate_id(from_a, to_a, subject)
+    lines = [
+        f"From: {from_a}",
+        f"To: {to_a}",
+        f"Subject: {subject}",
+        f"Date: {now_str()}",
+        f"Message-ID: {msg_id}",
+        "Status: new",
+    ]
+    if attachments:
+        lines.append(f"Attachments: {', '.join(Path(a).name for a in attachments)}")
+    lines += ["", "---", body]
+    return "\n".join(lines), msg_id
+
+
+def parse_message(path) -> Tuple[Optional[dict], Optional[str]]:
+    """Parse a message file into (headers_dict, body_text)."""
+    p = Path(path)
+    if not p.exists():
+        return None, None
+    text = p.read_text(encoding="utf-8", errors="replace")
+    headers: dict = {}
+    body_lines: list = []
+    in_body = False
+    for line in text.split("\n"):
+        if not in_body:
+            if line.strip() == "---":
+                in_body = True
+                continue
+            if ":" in line:
+                k, _, v = line.partition(":")
+                headers[k.strip()] = v.strip()
+        else:
+            body_lines.append(line)
+    return headers, "\n".join(body_lines)
+
+
+def parse_headers_only(path) -> dict:
+    """Parse only message headers (faster — stops at '---')."""
+    headers = {}
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.rstrip("\n")
+            if line.strip() == "---":
+                break
+            if ":" in line:
+                k, _, v = line.partition(":")
+                headers[k.strip()] = v.strip()
+    return headers