aloop 0.1.0__tar.gz

aloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yixin Luo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aloop-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# Include important files in the package
+include README.md
+include LICENSE
+recursive-include docs *.md
+recursive-include examples *.py *.md

aloop-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: aloop
+Version: 0.1.0
+Summary: General AI Agent System
+Author-email: luohaha <luoyixin6688@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/luohaha/aloop
+Project-URL: Documentation, https://github.com/luohaha/aloop#readme
+Project-URL: Repository, https://github.com/luohaha/aloop
+Project-URL: Issues, https://github.com/luohaha/aloop/issues
+Keywords: ai,agent,llm,claude,gpt,gemini,loop,planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ddgs>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: trafilatura>=2.0.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: litellm>=1.30.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0
+Requires-Dist: tree-sitter-languages<1.11.0,>=1.8.0
+Requires-Dist: croniter>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: types-aiofiles>=25.1.0; extra == "dev"
+Requires-Dist: types-croniter>=1.3.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+<picture>
+  <img alt="ALOOP" src="docs/assets/logo.svg" width="440">
+</picture>
+
+**One loop is all you need.**
+
+aloop is an AI agent built on a single, unified loop. Planning, parallel sub-agents,
+self-verification — everything folds into the same loop, chosen autonomously by the
+agent itself, not by a hardcoded workflow. Simple architecture, emergent capability.
+
+
+</div>
+
+## Installation
+
+Prerequisites: Python 3.12+ and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/luohaha/aloop.git
+cd aloop
+./scripts/bootstrap.sh
+```
+
+## Quick Start
+
+### 1. Configure Models
+
+On first run, `~/.aloop/models.yaml` is created with a template. Edit it to add your provider and API key:
+
+```yaml
+models:
+  openai/gpt-4o:
+    api_key: sk-...
+
+  anthropic/claude-3-5-sonnet-20241022:
+    api_key: sk-ant-...
+
+  ollama/llama2:
+    api_base: http://localhost:11434
+
+default: openai/gpt-4o
+```
+
+See [LiteLLM Providers](https://docs.litellm.ai/docs/providers) for the full list.
+
+### 2. Run
+
+```bash
+# Interactive mode
+aloop
+
+# Single task (returns raw result)
+aloop --task "Calculate 123 * 456"
+
+# Resume last session
+aloop --resume
+
+# Resume specific session (ID prefix)
+aloop --resume a1b2c3d4
+```
+
+## CLI Reference
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--task TEXT` | `-t` | Run a single task and exit |
+| `--model ID` | `-m` | LiteLLM model ID to use |
+| `--resume [ID]` | `-r` | Resume a session (`latest` if no ID given) |
+| `--verbose` | `-v` | Enable verbose logging to `~/.aloop/logs/` |
+
+## Interactive Commands
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/clear` | Clear conversation and start fresh |
+| `/stats` | Show memory and token usage statistics |
+| `/resume [id]` | List or resume a previous session |
+| `/model` | Pick a model (arrow keys + Enter) |
+| `/model edit` | Open `~/.aloop/models.yaml` in editor (auto-reload on save) |
+| `/theme` | Toggle dark/light theme |
+| `/verbose` | Toggle thinking display |
+| `/compact` | Toggle compact output |
+| `/exit` | Exit (also `/quit`) |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `/` | Command autocomplete |
+| `Ctrl+C` | Cancel current operation |
+| `Ctrl+L` | Clear screen |
+| `Ctrl+T` | Toggle thinking display |
+| `Ctrl+S` | Show quick stats |
+| Up/Down | Navigate command history |
+
+## How It Works
+
+**Agent loop**: The agent follows a Think-Act-Observe cycle. It reasons about the task, selects a tool, observes the result, and repeats until it has an answer. Planning, sub-agent dispatch, and tool use all happen inside this single loop.
+
+**Ralph verification**: For single tasks (`--task`), an outer loop verifies the agent's answer against the original task. If incomplete, feedback is injected and the agent loop re-enters. Configurable via `RALPH_LOOP_MAX_ITERATIONS` (default: 3).
+
+**Memory compression**: When context grows past a token threshold, older messages are compressed via LLM summarization. Recent messages are kept at full fidelity. Strategies: `sliding_window` (default), `selective`, `deletion`.
+
+**Session persistence**: Conversations are saved as YAML files under `~/.aloop/sessions/`. Resume with `--resume` or `/resume`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents |
+| `write_file` | Write content to a file |
+| `search_files` | Search for files by name |
+| `edit_file` | Exact string replacement in files |
+| `smart_edit` | LLM-assisted file editing |
+| `glob_files` | Glob pattern file matching |
+| `grep_content` | Regex search in file contents |
+| `code_navigator` | AST-based code navigation (tree-sitter) |
+| `calculate` | Evaluate expressions / run Python code |
+| `shell` | Execute shell commands |
+| `shell_task_status` | Check background shell task status |
+| `web_search` | Web search (DuckDuckGo) |
+| `web_fetch` | Fetch and extract web page content |
+| `explore_context` | Explore project structure and context |
+| `parallel_execute` | Run multiple tool calls in parallel |
+| `notify` | Send email notifications (Resend) |
+| `manage_todo_list` | Manage a task/todo list |
+
+## Project Structure
+
+```
+aloop/
+├── main.py                 # Entry point (argparse)
+├── cli.py                  # CLI wrapper (`aloop` entry point)
+├── interactive.py          # Interactive session, model setup, TUI
+├── config.py               # Runtime config (~/.aloop/config)
+├── agent/
+│   ├── base.py             # BaseAgent (ReAct + Ralph loops)
+│   ├── agent.py            # LoopAgent
+│   ├── verification.py     # LLMVerifier for Ralph loop
+│   ├── context.py          # Context injection (cwd, platform, date)
+│   ├── tool_executor.py    # Tool execution engine
+│   └── todo.py             # Todo list data structure
+├── llm/
+│   ├── litellm_adapter.py  # LiteLLM adapter (100+ providers)
+│   ├── model_manager.py    # Model config from ~/.aloop/models.yaml
+│   ├── retry.py            # Retry with exponential backoff
+│   └── message_types.py    # LLMMessage, LLMResponse, ToolCall
+├── memory/
+│   ├── manager.py          # Memory orchestrator + persistence
+│   ├── compressor.py       # LLM-driven compression
+│   ├── short_term.py       # Short-term memory (sliding window)
+│   ├── token_tracker.py    # Token counting + cost tracking
+│   ├── types.py            # Core data structures
+│   └── store/
+│       └── yaml_file_memory_store.py  # YAML session persistence
+├── tools/                  # 18 tool implementations
+├── utils/
+│   ├── tui/                # TUI components (input, themes, status bar)
+│   ├── logger.py           # Logging setup
+│   └── model_pricing.py    # Model pricing data
+├── docs/                   # Documentation
+├── test/                   # Tests
+├── scripts/                # Dev scripts (bootstrap.sh, dev.sh)
+└── rfc/                    # RFC design documents
+```
+
+## Configuration
+
+Runtime settings live in `~/.aloop/config` (auto-created). Key settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `MAX_ITERATIONS` | `1000` | Maximum agent loop iterations |
+| `TOOL_TIMEOUT` | `600` | Tool execution timeout (seconds) |
+| `RALPH_LOOP_MAX_ITERATIONS` | `3` | Max verification attempts |
+| `MEMORY_ENABLED` | `true` | Enable memory management |
+| `MEMORY_COMPRESSION_THRESHOLD` | `60000` | Token threshold for compression |
+| `MEMORY_SHORT_TERM_SIZE` | `100` | Messages kept at full fidelity |
+| `RETRY_MAX_ATTEMPTS` | `3` | Rate-limit retry attempts |
+
+See [Configuration Guide](docs/configuration.md) for all settings.
+
+## Documentation
+
+- [Configuration](docs/configuration.md) -- model setup, runtime settings, custom endpoints
+- [Examples](docs/examples.md) -- usage patterns and programmatic API
+- [Memory Management](docs/memory-management.md) -- compression, persistence, token tracking
+- [Extending](docs/extending.md) -- adding tools, agents, LLM providers
+- [Packaging](docs/packaging.md) -- building, publishing, Docker
+
+## License
+
+MIT License

aloop-0.1.0/README.md

@@ -0,0 +1,197 @@
+<div align="center">
+<picture>
+  <img alt="ALOOP" src="docs/assets/logo.svg" width="440">
+</picture>
+
+**One loop is all you need.**
+
+aloop is an AI agent built on a single, unified loop. Planning, parallel sub-agents,
+self-verification — everything folds into the same loop, chosen autonomously by the
+agent itself, not by a hardcoded workflow. Simple architecture, emergent capability.
+
+
+</div>
+
+## Installation
+
+Prerequisites: Python 3.12+ and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/luohaha/aloop.git
+cd aloop
+./scripts/bootstrap.sh
+```
+
+## Quick Start
+
+### 1. Configure Models
+
+On first run, `~/.aloop/models.yaml` is created with a template. Edit it to add your provider and API key:
+
+```yaml
+models:
+  openai/gpt-4o:
+    api_key: sk-...
+
+  anthropic/claude-3-5-sonnet-20241022:
+    api_key: sk-ant-...
+
+  ollama/llama2:
+    api_base: http://localhost:11434
+
+default: openai/gpt-4o
+```
+
+See [LiteLLM Providers](https://docs.litellm.ai/docs/providers) for the full list.
+
+### 2. Run
+
+```bash
+# Interactive mode
+aloop
+
+# Single task (returns raw result)
+aloop --task "Calculate 123 * 456"
+
+# Resume last session
+aloop --resume
+
+# Resume specific session (ID prefix)
+aloop --resume a1b2c3d4
+```
+
+## CLI Reference
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--task TEXT` | `-t` | Run a single task and exit |
+| `--model ID` | `-m` | LiteLLM model ID to use |
+| `--resume [ID]` | `-r` | Resume a session (`latest` if no ID given) |
+| `--verbose` | `-v` | Enable verbose logging to `~/.aloop/logs/` |
+
+## Interactive Commands
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/clear` | Clear conversation and start fresh |
+| `/stats` | Show memory and token usage statistics |
+| `/resume [id]` | List or resume a previous session |
+| `/model` | Pick a model (arrow keys + Enter) |
+| `/model edit` | Open `~/.aloop/models.yaml` in editor (auto-reload on save) |
+| `/theme` | Toggle dark/light theme |
+| `/verbose` | Toggle thinking display |
+| `/compact` | Toggle compact output |
+| `/exit` | Exit (also `/quit`) |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `/` | Command autocomplete |
+| `Ctrl+C` | Cancel current operation |
+| `Ctrl+L` | Clear screen |
+| `Ctrl+T` | Toggle thinking display |
+| `Ctrl+S` | Show quick stats |
+| Up/Down | Navigate command history |
+
+## How It Works
+
+**Agent loop**: The agent follows a Think-Act-Observe cycle. It reasons about the task, selects a tool, observes the result, and repeats until it has an answer. Planning, sub-agent dispatch, and tool use all happen inside this single loop.
+
+**Ralph verification**: For single tasks (`--task`), an outer loop verifies the agent's answer against the original task. If incomplete, feedback is injected and the agent loop re-enters. Configurable via `RALPH_LOOP_MAX_ITERATIONS` (default: 3).
+
+**Memory compression**: When context grows past a token threshold, older messages are compressed via LLM summarization. Recent messages are kept at full fidelity. Strategies: `sliding_window` (default), `selective`, `deletion`.
+
+**Session persistence**: Conversations are saved as YAML files under `~/.aloop/sessions/`. Resume with `--resume` or `/resume`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents |
+| `write_file` | Write content to a file |
+| `search_files` | Search for files by name |
+| `edit_file` | Exact string replacement in files |
+| `smart_edit` | LLM-assisted file editing |
+| `glob_files` | Glob pattern file matching |
+| `grep_content` | Regex search in file contents |
+| `code_navigator` | AST-based code navigation (tree-sitter) |
+| `calculate` | Evaluate expressions / run Python code |
+| `shell` | Execute shell commands |
+| `shell_task_status` | Check background shell task status |
+| `web_search` | Web search (DuckDuckGo) |
+| `web_fetch` | Fetch and extract web page content |
+| `explore_context` | Explore project structure and context |
+| `parallel_execute` | Run multiple tool calls in parallel |
+| `notify` | Send email notifications (Resend) |
+| `manage_todo_list` | Manage a task/todo list |
+
+## Project Structure
+
+```
+aloop/
+├── main.py                 # Entry point (argparse)
+├── cli.py                  # CLI wrapper (`aloop` entry point)
+├── interactive.py          # Interactive session, model setup, TUI
+├── config.py               # Runtime config (~/.aloop/config)
+├── agent/
+│   ├── base.py             # BaseAgent (ReAct + Ralph loops)
+│   ├── agent.py            # LoopAgent
+│   ├── verification.py     # LLMVerifier for Ralph loop
+│   ├── context.py          # Context injection (cwd, platform, date)
+│   ├── tool_executor.py    # Tool execution engine
+│   └── todo.py             # Todo list data structure
+├── llm/
+│   ├── litellm_adapter.py  # LiteLLM adapter (100+ providers)
+│   ├── model_manager.py    # Model config from ~/.aloop/models.yaml
+│   ├── retry.py            # Retry with exponential backoff
+│   └── message_types.py    # LLMMessage, LLMResponse, ToolCall
+├── memory/
+│   ├── manager.py          # Memory orchestrator + persistence
+│   ├── compressor.py       # LLM-driven compression
+│   ├── short_term.py       # Short-term memory (sliding window)
+│   ├── token_tracker.py    # Token counting + cost tracking
+│   ├── types.py            # Core data structures
+│   └── store/
+│       └── yaml_file_memory_store.py  # YAML session persistence
+├── tools/                  # 18 tool implementations
+├── utils/
+│   ├── tui/                # TUI components (input, themes, status bar)
+│   ├── logger.py           # Logging setup
+│   └── model_pricing.py    # Model pricing data
+├── docs/                   # Documentation
+├── test/                   # Tests
+├── scripts/                # Dev scripts (bootstrap.sh, dev.sh)
+└── rfc/                    # RFC design documents
+```
+
+## Configuration
+
+Runtime settings live in `~/.aloop/config` (auto-created). Key settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `MAX_ITERATIONS` | `1000` | Maximum agent loop iterations |
+| `TOOL_TIMEOUT` | `600` | Tool execution timeout (seconds) |
+| `RALPH_LOOP_MAX_ITERATIONS` | `3` | Max verification attempts |
+| `MEMORY_ENABLED` | `true` | Enable memory management |
+| `MEMORY_COMPRESSION_THRESHOLD` | `60000` | Token threshold for compression |
+| `MEMORY_SHORT_TERM_SIZE` | `100` | Messages kept at full fidelity |
+| `RETRY_MAX_ATTEMPTS` | `3` | Rate-limit retry attempts |
+
+See [Configuration Guide](docs/configuration.md) for all settings.
+
+## Documentation
+
+- [Configuration](docs/configuration.md) -- model setup, runtime settings, custom endpoints
+- [Examples](docs/examples.md) -- usage patterns and programmatic API
+- [Memory Management](docs/memory-management.md) -- compression, persistence, token tracking
+- [Extending](docs/extending.md) -- adding tools, agents, LLM providers
+- [Packaging](docs/packaging.md) -- building, publishing, Docker
+
+## License
+
+MIT License

aloop-0.1.0/agent/agent.py

@@ -0,0 +1,182 @@
+"""Loop agent implementation."""
+
+from config import Config
+from llm import LLMMessage
+from utils import terminal_ui
+
+from .base import BaseAgent
+from .context import format_context_prompt
+
+
+class LoopAgent(BaseAgent):
+    """Primary agent implementation — one unified loop for all tasks."""
+
+    SYSTEM_PROMPT = """<role>
+You are a helpful AI assistant that uses tools to accomplish tasks efficiently and reliably.
+</role>
+
+<critical_rules>
+IMPORTANT: Always think before acting
+IMPORTANT: Use the most efficient tool for each operation
+IMPORTANT: Manage todo lists for complex multi-step tasks
+IMPORTANT: Mark tasks completed IMMEDIATELY after finishing them
+</critical_rules>
+
+<task_management>
+Use the manage_todo_list tool for complex tasks to prevent forgetting steps.
+
+WHEN TO USE TODO LISTS:
+- Tasks with 3+ distinct steps
+- Multi-file operations
+- Complex workflows requiring planning
+- Any task where tracking progress helps
+
+TODO LIST RULES:
+- Create todos BEFORE starting complex work
+- Exactly ONE task must be in_progress at any time
+- Mark tasks completed IMMEDIATELY after finishing
+- Update status as you work through the list
+
+<good_example>
+User: Create a data pipeline that reads CSV, processes it, and generates report
+Assistant: I'll use the todo list to track this multi-step task.
+[Calls manage_todo_list with operation="add" for each step]
+[Marks first task as in_progress before starting]
+[Uses read_file tool]
+[Marks as completed, moves to next task]
+</good_example>
+
+<bad_example>
+User: Create a data pipeline that reads CSV, processes it, and generates report
+Assistant: [Immediately starts without planning, forgets steps halfway through]
+</bad_example>
+</task_management>
+
+<tool_usage_guidelines>
+For file operations:
+- Use glob_files to find files by pattern (fast, efficient)
+- Use code_navigator to find function/class definitions (10x faster than grep, AST-based)
+- Use grep_content for text search only (not for finding code structure)
+- Use read_file only when you need full contents (avoid reading multiple large files at once)
+- Use smart_edit for code edits (fuzzy match, auto backup, diff preview)
+- Use edit_file for simple append/insert operations only
+- Use write_file only for creating new files or complete rewrites
+
+CRITICAL: Never read multiple large files in a single iteration - this causes context overflow!
+Instead: Use code_navigator or grep_content to find specific information, then read only what you need.
+
+For complex tasks:
+- Use manage_todo_list to track progress
+- Break into smaller, manageable steps
+- Mark tasks completed as you go
+- Keep exactly ONE task in_progress at a time
+
+<good_example>
+Task: Find all Python files that import 'requests'
+Approach:
+1. Use glob_files with pattern "**/*.py" to find Python files
+2. Use grep_content with pattern "^import requests|^from requests" to search
+Result: Efficient, minimal tokens used
+</good_example>
+
+<bad_example>
+Task: Find all Python files that import 'requests'
+Approach:
+1. Use read_file on every Python file one by one
+2. Manually search through content
+Result: Wasteful, uses 100x more tokens
+</bad_example>
+</tool_usage_guidelines>
+
+<workflow>
+For each user request, follow this ReAct pattern:
+1. THINK: Analyze what's needed, choose best tools
+2. ACT: Execute with appropriate tools
+3. OBSERVE: Check results and learn from them
+4. REPEAT or COMPLETE: Continue the loop or provide final answer
+
+When you have enough information, provide your final answer directly without using more tools.
+</workflow>
+
+<complex_task_strategy>
+For complex tasks, combine tools to achieve an explore-plan-execute workflow:
+
+1. **EXPLORE**: Gather context before acting
+   - Use explore_context for parallel information gathering (code structure, web research)
+
+2. **PLAN**: Structure your approach
+   - Use manage_todo_list to break down the task into trackable steps
+   - Identify dependencies between steps
+
+3. **EXECUTE**: Carry out the plan
+   - Use parallel_execute for multiple independent/semi-dependent tasks
+   - Use regular tools for simple sequential operations
+
+When to use each approach:
+- Simple task (1-2 steps) → Use tools directly
+- Medium task (3-5 steps) → Use todo list + sequential execution
+- Complex task (needs research) → Explore → Plan → Execute
+- Parallel workload → parallel_execute
+</complex_task_strategy>"""
+
+    async def run(self, task: str, verify: bool = True) -> str:
+        """Execute ReAct loop until task is complete.
+
+        Args:
+            task: The task to complete
+            verify: If True, use ralph loop (outer verification). If False, use
+                    plain react loop (suitable for interactive multi-turn sessions).
+
+        Returns:
+            Final answer as a string
+        """
+        # Build system message with context (only if not already in memory)
+        # This allows multi-turn conversations to reuse the same system message
+        if not self.memory.system_messages:
+            system_content = self.SYSTEM_PROMPT
+            try:
+                context = await format_context_prompt()
+                system_content = context + "\n" + system_content
+            except Exception:
+                # If context gathering fails, continue without it
+                pass
+
+            # Add system message only on first turn
+            await self.memory.add_message(LLMMessage(role="system", content=system_content))
+
+        # Add user task/message
+        await self.memory.add_message(LLMMessage(role="user", content=task))
+
+        tools = self.tool_executor.get_tool_schemas()
+
+        if verify:
+            # Use ralph loop (outer verification wrapping the inner ReAct loop)
+            result = await self._ralph_loop(
+                messages=[],  # Not used when use_memory=True
+                tools=tools,
+                use_memory=True,
+                save_to_memory=True,
+                task=task,
+                max_iterations=Config.RALPH_LOOP_MAX_ITERATIONS,
+            )
+        else:
+            # Plain react loop without verification
+            result = await self._react_loop(
+                messages=[],
+                tools=tools,
+                use_memory=True,
+                save_to_memory=True,
+                task=task,
+            )
+
+        self._print_memory_stats()
+
+        # Save memory state to database after task completion
+        await self.memory.save_memory()
+
+        return result
+
+    def _print_memory_stats(self):
+        """Print memory usage statistics."""
+        stats = self.memory.get_stats()
+        terminal_ui.print_memory_stats(stats)