hindsight-all 0.4.6__tar.gz

hindsight_all-0.4.6/.gitignore

@@ -0,0 +1,56 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.mcp.json
+.osgrep
+# Virtual environments
+.venv
+
+# Node
+node_modules/
+
+# Environment variables and local config
+.env
+docker-compose.yml
+docker-compose.override.yml
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# NLTK data (will be downloaded automatically)
+nltk_data/
+
+# Monitoring stack (Prometheus/Grafana binaries and data)
+.monitoring/
+.pgbouncer/
+
+# Large benchmark datasets (will be downloaded automatically)
+**/longmemeval_s_cleaned.json
+
+# Debug logs
+logs/
+
+.DS_Store
+
+# Generated docs files
+hindsight-docs/static/llms-full.txt
+
+
+hindsight-dev/benchmarks/locomo/results/
+hindsight-dev/benchmarks/longmemeval/results/
+hindsight-dev/benchmarks/consolidation/results/
+benchmarks/results/
+hindsight-cli/target
+hindsight-clients/rust/target
+.claude
+whats-next.md
+TASK.md
+# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
+# CHANGELOG.md

hindsight_all-0.4.6/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: hindsight-all
+Version: 0.4.6
+Summary: Hindsight: Agent Memory That Works Like Human Memory - All-in-One Bundle
+Requires-Python: >=3.11
+Requires-Dist: hindsight-api>=0.0.7
+Requires-Dist: hindsight-client>=0.0.7
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# hindsight-all
+
+All-in-one package for Hindsight - Agent Memory That Works Like Human Memory
+
+## Quick Start
+
+```python
+from hindsight import start_server, HindsightClient
+
+# Start server with embedded PostgreSQL
+server = start_server(
+    llm_provider="groq",
+    llm_api_key="your-api-key",
+    llm_model="openai/gpt-oss-120b"
+)
+
+# Create client
+client = HindsightClient(base_url=server.url)
+
+# Store memories
+client.put(agent_id="assistant", content="User prefers Python for data analysis")
+
+# Search memories
+results = client.search(agent_id="assistant", query="programming preferences")
+
+# Generate contextual response
+response = client.think(agent_id="assistant", query="What languages should I recommend?")
+
+# Stop server when done
+server.stop()
+```
+
+## Using Context Manager
+
+```python
+from hindsight import HindsightServer, HindsightClient
+
+with HindsightServer(llm_provider="groq", llm_api_key="...") as server:
+    client = HindsightClient(base_url=server.url)
+    # ... use client ...
+# Server automatically stops
+```
+
+## Installation
+
+```bash
+pip install hindsight-all
+```

hindsight_all-0.4.6/README.md

@@ -0,0 +1,48 @@
+# hindsight-all
+
+All-in-one package for Hindsight - Agent Memory That Works Like Human Memory
+
+## Quick Start
+
+```python
+from hindsight import start_server, HindsightClient
+
+# Start server with embedded PostgreSQL
+server = start_server(
+    llm_provider="groq",
+    llm_api_key="your-api-key",
+    llm_model="openai/gpt-oss-120b"
+)
+
+# Create client
+client = HindsightClient(base_url=server.url)
+
+# Store memories
+client.put(agent_id="assistant", content="User prefers Python for data analysis")
+
+# Search memories
+results = client.search(agent_id="assistant", query="programming preferences")
+
+# Generate contextual response
+response = client.think(agent_id="assistant", query="What languages should I recommend?")
+
+# Stop server when done
+server.stop()
+```
+
+## Using Context Manager
+
+```python
+from hindsight import HindsightServer, HindsightClient
+
+with HindsightServer(llm_provider="groq", llm_api_key="...") as server:
+    client = HindsightClient(base_url=server.url)
+    # ... use client ...
+# Server automatically stops
+```
+
+## Installation
+
+```bash
+pip install hindsight-all
+```

hindsight_all-0.4.6/hindsight/__init__.py

@@ -0,0 +1,53 @@
+"""
+Hindsight - All-in-one semantic memory system for AI agents.
+
+This package provides a simple way to run Hindsight locally with embedded PostgreSQL.
+
+Example:
+    ```python
+    from hindsight import start_server, HindsightClient
+
+    # Start server with embedded PostgreSQL (pg0)
+    server = start_server(
+        llm_provider="groq",
+        llm_api_key="your-api-key",
+        llm_model="openai/gpt-oss-120b"
+    )
+
+    # Create client
+    client = HindsightClient(base_url=server.url)
+
+    # Store memories
+    client.put(agent_id="assistant", content="User prefers Python for data analysis")
+
+    # Search memories
+    results = client.search(agent_id="assistant", query="programming preferences")
+
+    # Generate contextual response
+    response = client.think(agent_id="assistant", query="What languages should I recommend?")
+
+    # Stop server when done
+    server.stop()
+    ```
+
+Using context manager:
+    ```python
+    from hindsight import HindsightServer, HindsightClient
+
+    with HindsightServer(llm_provider="groq", llm_api_key="...") as server:
+        client = HindsightClient(base_url=server.url)
+        # ... use client ...
+    # Server automatically stops
+    ```
+"""
+
+from .server import Server as HindsightServer, start_server
+
+# Re-export Client from hindsight-client
+from hindsight_client import Hindsight as HindsightClient
+
+__all__ = [
+    "HindsightServer",
+    "start_server",
+    "HindsightClient",
+]

hindsight_all-0.4.6/hindsight/server.py

@@ -0,0 +1,280 @@
+"""
+Server module for running Hindsight in a background thread.
+
+Provides a simple way to start and stop the Hindsight HTTP API server
+without blocking the main thread.
+"""
+import asyncio
+import logging
+import socket
+import threading
+import time
+from typing import Optional
+
+import uvicorn
+from uvicorn import Config
+
+from hindsight_api import MemoryEngine
+from hindsight_api.api import create_app
+
+logger = logging.getLogger(__name__)
+
+
+def _find_free_port() -> int:
+    """Find a free port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        s.listen(1)
+        port = s.getsockname()[1]
+    return port
+
+
+class Server:
+    """
+    Hindsight server that runs in a background thread.
+
+    Example:
+        ```python
+        from hindsight import Server
+
+        server = Server(
+            db_url="pg0",
+            llm_provider="groq",
+            llm_api_key="your-api-key",
+            llm_model="openai/gpt-oss-120b"
+        )
+        server.start()
+
+        print(f"Server running at {server.url}")
+
+        # Use the server...
+
+        server.stop()
+        ```
+    """
+
+    def __init__(
+        self,
+        db_url: str = "pg0",
+        llm_provider: str = "groq",
+        llm_api_key: str = "",
+        llm_model: str = "openai/gpt-oss-120b",
+        llm_base_url: Optional[str] = None,
+        host: str = "127.0.0.1",
+        port: Optional[int] = None,
+        mcp_enabled: bool = False,
+        log_level: str = "info",
+    ):
+        """
+        Initialize the Hindsight server.
+
+        Args:
+            db_url: Database URL. Use "pg0" for embedded PostgreSQL.
+            llm_provider: LLM provider ("groq", "openai", "ollama", "gemini", "anthropic", "lmstudio")
+            llm_api_key: API key for the LLM provider
+            llm_model: Model name to use
+            llm_base_url: Optional custom base URL for LLM API
+            host: Host to bind to (default: 127.0.0.1)
+            port: Port to bind to (default: auto-select free port)
+            mcp_enabled: Whether to enable MCP server
+            log_level: Uvicorn log level (default: warning)
+        """
+        self.db_url = db_url
+        self.llm_provider = llm_provider
+        self.llm_api_key = llm_api_key
+        self.llm_model = llm_model
+        self.llm_base_url = llm_base_url
+        self.host = host
+        self.port = port or _find_free_port()
+        self.mcp_enabled = mcp_enabled
+        self.log_level = log_level
+
+        self._memory: Optional[MemoryEngine] = None
+        self._server: Optional[uvicorn.Server] = None
+        self._thread: Optional[threading.Thread] = None
+        self._started = threading.Event()
+        self._stopped = threading.Event()
+
+    @property
+    def url(self) -> str:
+        """Get the server URL."""
+        return f"http://{self.host}:{self.port}"
+
+    def _run_server(self):
+        """Run the server in a background thread."""
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        try:
+            # Create MemoryEngine
+            self._memory = MemoryEngine(
+                db_url=self.db_url,
+                memory_llm_provider=self.llm_provider,
+                memory_llm_api_key=self.llm_api_key,
+                memory_llm_model=self.llm_model,
+                memory_llm_base_url=self.llm_base_url,
+            )
+
+            # Create FastAPI app
+            app = create_app(
+                memory=self._memory,
+                mcp_api_enabled=self.mcp_enabled,
+                initialize_memory=True,
+            )
+
+            # Create uvicorn config and server
+            config = Config(
+                app=app,
+                host=self.host,
+                port=self.port,
+                log_level=self.log_level,
+                loop="asyncio",
+            )
+            self._server = uvicorn.Server(config)
+
+            # Signal that we're starting
+            self._started.set()
+
+            # Run the server
+            loop.run_until_complete(self._server.serve())
+
+        except Exception as e:
+            logger.error(f"Server error: {e}")
+            raise
+        finally:
+            # Cleanup
+            if self._memory:
+                loop.run_until_complete(self._memory.close())
+            loop.close()
+            self._stopped.set()
+
+    def start(self, timeout: float = 30.0) -> "Server":
+        """
+        Start the server in a background thread.
+
+        Args:
+            timeout: Maximum time to wait for server to start (seconds)
+
+        Returns:
+            self (for chaining)
+
+        Raises:
+            RuntimeError: If server fails to start within timeout
+        """
+        if self._thread is not None and self._thread.is_alive():
+            raise RuntimeError("Server is already running")
+
+        self._started.clear()
+        self._stopped.clear()
+
+        self._thread = threading.Thread(target=self._run_server, daemon=True)
+        self._thread.start()
+
+        # Wait for server to start
+        self._started.wait(timeout=timeout)
+
+        # Give uvicorn a moment to actually bind to the port
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                with socket.create_connection((self.host, self.port), timeout=1):
+                    logger.info(f"Hindsight server started at {self.url}")
+                    return self
+            except (ConnectionRefusedError, socket.timeout, OSError):
+                time.sleep(0.1)
+
+        raise RuntimeError(f"Server failed to start within {timeout} seconds")
+
+    def stop(self, timeout: float = 10.0) -> None:
+        """
+        Stop the server.
+
+        Args:
+            timeout: Maximum time to wait for server to stop (seconds)
+        """
+        if self._server is None:
+            return
+
+        # Signal uvicorn to shutdown
+        self._server.should_exit = True
+
+        # Wait for thread to finish
+        if self._thread is not None:
+            self._thread.join(timeout=timeout)
+            if self._thread.is_alive():
+                logger.warning("Server thread did not stop cleanly")
+
+        self._server = None
+        self._thread = None
+        logger.info("Hindsight server stopped")
+
+    def __enter__(self) -> "Server":
+        """Context manager entry."""
+        return self.start()
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.stop()
+
+
+def start_server(
+    db_url: str = "pg0",
+    llm_provider: str = "groq",
+    llm_api_key: str = "",
+    llm_model: str = "openai/gpt-oss-120b",
+    llm_base_url: Optional[str] = None,
+    host: str = "127.0.0.1",
+    port: Optional[int] = None,
+    mcp_enabled: bool = False,
+    log_level: str = "warning",
+    timeout: float = 30.0,
+) -> Server:
+    """
+    Start a Hindsight server in a background thread.
+
+    This is a convenience function that creates and starts a Server instance.
+
+    Args:
+        db_url: Database URL. Use "pg0" for embedded PostgreSQL.
+        llm_provider: LLM provider ("groq", "openai", "ollama", "gemini", "anthropic", "lmstudio")
+        llm_api_key: API key for the LLM provider
+        llm_model: Model name to use
+        llm_base_url: Optional custom base URL for LLM API
+        host: Host to bind to (default: 127.0.0.1)
+        port: Port to bind to (default: auto-select free port)
+        mcp_enabled: Whether to enable MCP server
+        log_level: Uvicorn log level (default: warning)
+        timeout: Maximum time to wait for server to start (seconds)
+
+    Returns:
+        Running Server instance
+
+    Example:
+        ```python
+        from hindsight import start_server, Client
+
+        server = start_server(
+            db_url="pg0",
+            llm_provider="groq",
+            llm_api_key="your-api-key",
+            llm_model="openai/gpt-oss-120b"
+        )
+
+        client = Client(base_url=server.url)
+        client.put(agent_id="assistant", content="User likes Python")
+
+        server.stop()
+        ```
+    """
+    server = Server(
+        db_url=db_url,
+        llm_provider=llm_provider,
+        llm_api_key=llm_api_key,
+        llm_model=llm_model,
+        llm_base_url=llm_base_url,
+        host=host,
+        port=port,
+        mcp_enabled=mcp_enabled,
+        log_level=log_level,
+    )
+    return server.start(timeout=timeout)

hindsight_all-0.4.6/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hindsight-all"
+version = "0.4.6"
+description = "Hindsight: Agent Memory That Works Like Human Memory - All-in-One Bundle"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "hindsight-api>=0.0.7",
+    "hindsight-client>=0.0.7",
+]
+
+[tool.uv.sources]
+hindsight-api = { workspace = true }
+hindsight-client = { workspace = true }
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["hindsight"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

hindsight_all-0.4.6/tests/README.md

@@ -0,0 +1,128 @@
+# Hindsight Integration Tests
+
+This directory contains integration tests for the Hindsight all-in-one package.
+
+## Test Overview
+
+### `test_server_integration.py`
+
+Comprehensive integration tests that verify the complete workflow:
+
+1. **`test_server_context_manager_basic_workflow`**: Main integration test that:
+   - Starts the Hindsight server using a context manager
+   - Creates a memory bank with background information
+   - Stores multiple memories (both single and batch operations)
+   - Recalls memories based on different queries (programming preferences, ML topics)
+   - Reflects (generates contextual answers) multiple times with different contexts
+   - Automatically stops the server on context exit
+
+2. **`test_server_manual_start_stop`**: Tests explicit server lifecycle management without context managers
+
+3. **`test_server_with_client_context_manager`**: Tests nested context managers for both server and client
+
+## Running the Tests
+
+### Prerequisites
+
+1. Install the hindsight package with test dependencies:
+   ```bash
+   cd hindsight
+   uv pip install -e ".[test]"
+   ```
+
+2. Set up your LLM credentials in the `.env` file at the project root:
+   ```bash
+   HINDSIGHT_API_LLM_PROVIDER=groq
+   HINDSIGHT_API_LLM_API_KEY=your-api-key
+   HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-20b
+   ```
+
+### Run All Tests
+
+```bash
+cd hindsight
+source ../.env
+export HINDSIGHT_LLM_PROVIDER=$HINDSIGHT_API_LLM_PROVIDER
+export HINDSIGHT_LLM_API_KEY=$HINDSIGHT_API_LLM_API_KEY
+export HINDSIGHT_LLM_MODEL=$HINDSIGHT_API_LLM_MODEL
+pytest tests/ -v
+```
+
+**Note on Parallel Execution**: These tests use embedded PostgreSQL (`pg0`), which is a singleton that cannot be shared across pytest-xdist worker processes. Therefore, these tests must run sequentially. Do not use `pytest -n` (parallel workers) with these tests.
+
+**Why Random `bank_id` Values?**: Each test generates a unique `bank_id` using UUID. This provides several benefits:
+- **Clean test isolation**: Tests don't interfere with each other's data
+- **Repeatable runs**: Tests can be run multiple times without cleanup
+- **Debugging**: Easy to identify which test created which data
+- **Future-ready**: If you switch from `pg0` to a real PostgreSQL instance, these tests could run in parallel
+
+### Run Specific Test
+
+```bash
+pytest tests/test_server_integration.py::test_server_context_manager_basic_workflow -v
+```
+
+### Run with Verbose Output
+
+```bash
+pytest tests/ -v -s
+```
+
+The `-s` flag shows print statements, which is useful to see the test progress.
+
+### Run with Timeout
+
+These tests involve LLM calls which can take time:
+
+```bash
+pytest tests/ --timeout=300
+```
+
+## Test Configuration
+
+The tests use:
+- **Embedded PostgreSQL** (`pg0`) for the database - no external database required
+- **LLM provider** configured via environment variables
+- **Automatic port allocation** for the server (no port conflicts)
+
+## Expected Behavior
+
+When tests run successfully, you should see:
+1. Server starting on a random available port
+2. Memory bank creation with background information
+3. Multiple memories being stored (retain operations)
+4. Memories being recalled based on different queries
+5. Multiple reflection responses with contextual answers
+6. Server automatically stopping (for context manager tests)
+
+## Sample Output
+
+The main test workflow demonstrates:
+- **Step 1**: Create memory bank
+- **Step 2**: Store 5 memories (3 individual + 2 batch)
+- **Step 3**: Recall memories about programming preferences
+- **Step 4**: Recall memories about machine learning
+- **Step 5**: Reflect on tool recommendations
+- **Step 6**: Reflect with additional context about framework choices
+- **Step 7**: Server auto-stops via context manager
+
+## Skipping Tests
+
+Tests will automatically skip if:
+- `HINDSIGHT_LLM_API_KEY` is not set
+
+## Troubleshooting
+
+### Test hangs or times out
+- Increase timeout: `pytest tests/ --timeout=600`
+- Check your LLM API key is valid
+- Verify network connectivity to LLM provider
+
+### Database errors
+- The tests use embedded PostgreSQL (`pg0`) which should handle cleanup automatically
+- If you see "database system is shutting down" errors, wait a few seconds and retry
+- Between test runs, the embedded database needs time to properly shut down
+
+### Port conflicts
+- Tests automatically find free ports, so conflicts should be rare
+- If you see port binding errors, check for other processes using high-numbered ports

hindsight_all-0.4.6/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for the hindsight package."""

hindsight_all-0.4.6/tests/test_server_integration.py

@@ -0,0 +1,289 @@
+"""
+Integration test for Hindsight server with context manager.
+
+Tests the full workflow:
+1. Starting server using context manager
+2. Creating a memory bank
+3. Storing memories (retain)
+4. Recalling memories
+5. Reflecting on memories
+
+Note: These tests use embedded PostgreSQL (pg0) with a shared server instance
+across all tests. Each test uses random bank_ids to avoid conflicts, allowing
+safe parallel execution.
+"""
+
+import os
+import uuid
+import pytest
+from hindsight import HindsightServer, HindsightClient
+
+
+@pytest.fixture(scope="session")
+def llm_config():
+    """Get LLM configuration from environment (session-scoped)."""
+    provider = os.getenv("HINDSIGHT_LLM_PROVIDER", "groq")
+    api_key = os.getenv("HINDSIGHT_LLM_API_KEY", "")
+    model = os.getenv("HINDSIGHT_LLM_MODEL", "openai/gpt-oss-120b")
+
+    if not api_key:
+        raise Exception("LLM API key not configured. Set HINDSIGHT_LLM_API_KEY environment variable.")
+
+    return {
+        "llm_provider": provider,
+        "llm_api_key": api_key,
+        "llm_model": model,
+    }
+
+
+@pytest.fixture(scope="session")
+def shared_server(llm_config):
+    """
+    Shared server instance for all tests (session-scoped).
+
+    This allows tests to run in parallel by sharing the same pg0 instance,
+    while using different bank_ids to avoid data conflicts.
+    """
+    server = HindsightServer(db_url="pg0", **llm_config)
+    server.start()
+    yield server
+    server.stop()
+
+
+@pytest.fixture
+def client(shared_server):
+    """Create a client connected to the shared server."""
+    return HindsightClient(base_url=shared_server.url)
+
+
+def test_server_context_manager_basic_workflow(client):
+    """
+    Test complete workflow using shared server.
+
+    This test:
+    1. Uses a shared server instance
+    2. Creates a memory bank with unique ID
+    3. Stores multiple memories
+    4. Recalls memories based on a query
+    5. Reflects (generates contextual answers) based on stored memories
+    """
+    # Use random bank_id to allow parallel test execution
+    bank_id = f"test_assistant_{uuid.uuid4().hex[:8]}"
+
+    # Step 1: Create a memory bank with background information
+    print(f"\n1. Creating memory bank: {bank_id}")
+    bank_response = client.create_bank(
+        bank_id=bank_id,
+        name="Test Assistant",
+        background="An AI assistant that helps with programming and data analysis tasks."
+    )
+    assert "bank_id" in bank_response
+    assert bank_response["bank_id"] == bank_id
+
+    # Step 2: Store some memories about user preferences
+    print("\n2. Storing memories...")
+
+    # Store first memory
+    retain_response1 = client.retain(
+        bank_id=bank_id,
+        content="User prefers Python over JavaScript for data analysis projects.",
+        context="User conversation about programming languages"
+    )
+    assert retain_response1.get("success") is True
+
+    # Store second memory
+    retain_response2 = client.retain(
+        bank_id=bank_id,
+        content="User is working on a machine learning project using scikit-learn.",
+        context="Discussion about ML frameworks"
+    )
+    assert retain_response2.get("success") is True
+
+    # Store third memory
+    retain_response3 = client.retain(
+        bank_id=bank_id,
+        content="User likes visualizing data with matplotlib and seaborn.",
+        context="Conversation about data visualization"
+    )
+    assert retain_response3.get("success") is True
+
+    # Store batch memories
+    batch_response = client.retain_batch(
+        bank_id=bank_id,
+        items=[
+            {"content": "User is interested in neural networks and deep learning."},
+            {"content": "User asked about best practices for training models."},
+        ]
+    )
+    # Check if the batch was submitted successfully (items_count shows how many were submitted)
+    assert batch_response.get("items_count", 0) >= 2
+
+    # Step 3: Recall memories based on a query
+    print("\n3. Recalling memories about programming preferences...")
+    recall_results = client.recall(
+        bank_id=bank_id,
+        query="What programming languages and tools does the user prefer?",
+        max_tokens=4096
+    )
+
+    # Verify recall results
+    assert isinstance(recall_results, list)
+    assert len(recall_results) > 0
+    print(f"   Found {len(recall_results)} relevant memories")
+
+    # Check that results have expected structure
+    for result in recall_results:
+        assert "content" in result or "text" in result
+        print(f"   - {result.get('content') or result.get('text', '')[:100]}")
+
+    # Step 4: Recall memories about machine learning
+    print("\n4. Recalling memories about machine learning...")
+    ml_recall_results = client.recall(
+        bank_id=bank_id,
+        query="machine learning and neural networks",
+        max_tokens=4096
+    )
+
+    # Verify recall results
+    assert isinstance(ml_recall_results, list)
+    assert len(ml_recall_results) > 0
+    print(f"   Found {len(ml_recall_results)} ML-related memories")
+    for result in ml_recall_results[:3]:  # Show first 3
+        print(f"   - {result.get('content') or result.get('text', '')[:100]}")
+
+    # Step 5: Reflect (generate contextual answer based on memories)
+    print("\n5. Reflecting on query about recommendations...")
+    reflect_response = client.reflect(
+        bank_id=bank_id,
+        query="What tools and libraries should I recommend for this user's data analysis work?",
+        budget="mid"
+    )
+
+    # Verify reflection response
+    assert isinstance(reflect_response, dict)
+    assert "answer" in reflect_response or "text" in reflect_response
+
+    answer = reflect_response.get("answer") or reflect_response.get("text", "")
+    assert len(answer) > 0
+    print(f"   Answer: {answer[:200]}...")
+
+    # Verify the answer mentions relevant tools/libraries
+    answer_lower = answer.lower()
+    assert any(term in answer_lower for term in ["python", "scikit-learn", "matplotlib", "seaborn", "data"])
+
+    # Step 6: Another reflection with different context
+    print("\n6. Reflecting with additional context...")
+    reflect_with_context = client.reflect(
+        bank_id=bank_id,
+        query="Should I use TensorFlow or PyTorch?",
+        budget="low",
+        context="The user is starting a new deep learning project"
+    )
+
+    assert isinstance(reflect_with_context, dict)
+    context_answer = reflect_with_context.get("answer") or reflect_with_context.get("text", "")
+    assert len(context_answer) > 0
+    print(f"   Context-aware answer: {context_answer[:150]}...")
+
+
+def test_server_manual_start_stop(client):
+    """
+    Test basic operations on shared server.
+
+    Verifies that basic bank operations work correctly.
+    """
+    # Use random bank_id to allow parallel test execution
+    bank_id = f"test_manual_{uuid.uuid4().hex[:8]}"
+
+    # Create bank
+    bank_response = client.create_bank(
+        bank_id=bank_id,
+        name="Manual Test"
+    )
+    assert bank_response["bank_id"] == bank_id
+
+    # Store a memory
+    retain_response = client.retain(
+        bank_id=bank_id,
+        content="Testing manual server lifecycle."
+    )
+    assert retain_response.get("success") is True
+
+    # Recall the memory
+    recall_results = client.recall(
+        bank_id=bank_id,
+        query="server testing"
+    )
+    assert len(recall_results) >= 0  # May or may not find results immediately
+
+
+def test_server_with_client_context_manager(client):
+    """
+    Test client context manager with shared server.
+    """
+    # Use random bank_id to allow parallel test execution
+    bank_id = f"test_nested_context_{uuid.uuid4().hex[:8]}"
+
+    # Use client context manager (client fixture already provides this)
+    # Create bank
+    client.create_bank(bank_id=bank_id, name="Nested Context Test")
+
+    # Store memory
+    response = client.retain(
+        bank_id=bank_id,
+        content="Testing nested context managers."
+    )
+    assert response.get("success") is True
+
+    # Verify we can recall
+    results = client.recall(bank_id=bank_id, query="context")
+    assert isinstance(results, list)
+
+
+def test_list_banks(client, shared_server):
+    """
+    Test listing banks to verify bank_id field mapping.
+
+    This test verifies that the list_banks endpoint correctly returns
+    bank_id (not agent_id) in the response.
+    """
+    # Create a couple of banks with random IDs to allow parallel test execution
+    test_suffix = uuid.uuid4().hex[:8]
+    bank1_id = f"test_bank_1_{test_suffix}"
+    bank2_id = f"test_bank_2_{test_suffix}"
+
+    client.create_bank(bank_id=bank1_id, name="Test Bank 1", background="First test bank")
+    client.create_bank(bank_id=bank2_id, name="Test Bank 2", background="Second test bank")
+
+    # List all banks using the generated client
+    import hindsight_client_api
+    from hindsight_client_api.api import default_api
+
+    config = hindsight_client_api.Configuration(host=shared_server.url)
+    api_client = hindsight_client_api.ApiClient(config)
+    api = default_api.DefaultApi(api_client)
+
+    # Call list_banks endpoint
+    import asyncio
+    loop = asyncio.get_event_loop()
+    response = loop.run_until_complete(api.list_banks())
+
+    # Verify response structure
+    assert hasattr(response, 'banks'), "Response should have 'banks' attribute"
+    assert len(response.banks) >= 2, f"Should have at least 2 banks, got {len(response.banks)}"
+
+    # Verify each bank has bank_id (not agent_id)
+    for bank in response.banks:
+        bank_dict = bank.to_dict() if hasattr(bank, 'to_dict') else bank
+        assert 'bank_id' in bank_dict, f"Bank should have 'bank_id' field, got: {bank_dict.keys()}"
+        assert 'agent_id' not in bank_dict, f"Bank should NOT have 'agent_id' field, got: {bank_dict.keys()}"
+
+    # Find our test banks
+    bank_ids = [b.bank_id if hasattr(b, 'bank_id') else b['bank_id'] for b in response.banks]
+    assert bank1_id in bank_ids, f"Should find {bank1_id} in bank list"
+    assert bank2_id in bank_ids, f"Should find {bank2_id} in bank list"
+
+    print(f"✓ Successfully listed {len(response.banks)} banks with correct bank_id field")
+
+    # Cleanup
+    loop.run_until_complete(api_client.close())