hindsight-api 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

hindsight_api/api/http.py

@@ -10,7 +10,7 @@ import logging
 import uuid
 from contextlib import asynccontextmanager
 from datetime import datetime
-from typing import Any
+from typing import Any, Literal
 
 from fastapi import Depends, FastAPI, Header, HTTPException, Query
 
@@ -36,6 +36,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
 from hindsight_api import MemoryEngine
 from hindsight_api.engine.db_utils import acquire_with_retry
 from hindsight_api.engine.memory_engine import Budget, fq_table
+from hindsight_api.engine.reflect.observations import Observation
 from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES, TokenUsage
 from hindsight_api.engine.search.tags import TagsMatch
 from hindsight_api.extensions import HttpExtension, OperationValidationError, load_extension
@@ -90,7 +91,9 @@ class RecallRequest(BaseModel):
 
     query: str
     types: list[str] | None = Field(
-        default=None, description="List of fact types to recall (defaults to all if not specified)"
+        default=None,
+        description="List of fact types to recall: 'world', 'experience', 'observation'. Defaults to world and experience if not specified. "
+        "Note: 'opinion' is accepted but ignored (opinions are excluded from recall).",
     )
     budget: Budget = Budget.MID
     max_tokens: int = 4096
@@ -427,6 +430,15 @@ class FactsIncludeOptions(BaseModel):
     pass  # No additional options needed, just enable/disable
 
 
+class ToolCallsIncludeOptions(BaseModel):
+    """Options for including tool calls in reflect results."""
+
+    output: bool = Field(
+        default=True,
+        description="Include tool outputs in the trace. Set to false to only include inputs (smaller payload).",
+    )
+
+
 class ReflectIncludeOptions(BaseModel):
     """Options for including additional data in reflect results."""
 
@@ -434,6 +446,10 @@ class ReflectIncludeOptions(BaseModel):
         default=None,
         description="Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled).",
     )
+    tool_calls: ToolCallsIncludeOptions | None = Field(
+        default=None,
+        description="Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only.",
+    )
 
 
 class ReflectRequest(BaseModel):
@@ -444,7 +460,6 @@ class ReflectRequest(BaseModel):
             "example": {
                 "query": "What do you think about artificial intelligence?",
                 "budget": "low",
-                "context": "This is for a research paper on AI ethics",
                 "max_tokens": 4096,
                 "include": {"facts": {}},
                 "response_schema": {
@@ -463,7 +478,13 @@ class ReflectRequest(BaseModel):
 
     query: str
     budget: Budget = Budget.LOW
-    context: str | None = None
+    context: str | None = Field(
+        default=None,
+        description="DEPRECATED: Additional context is now concatenated with the query. "
+        "Pass context directly in the query field instead. "
+        "If provided, it will be appended to the query for backward compatibility.",
+        deprecated=True,
+    )
     max_tokens: int = Field(default=4096, description="Maximum tokens for the response")
     include: ReflectIncludeOptions = Field(
         default_factory=ReflectIncludeOptions, description="Options for including additional data (disabled by default)"
@@ -514,6 +535,58 @@ class ReflectFact(BaseModel):
     occurred_end: str | None = None
 
 
+class ReflectDirective(BaseModel):
+    """A directive applied during reflect."""
+
+    id: str = Field(description="Directive ID")
+    name: str = Field(description="Directive name")
+    content: str = Field(description="Directive content")
+
+
+class ReflectMentalModel(BaseModel):
+    """A mental model used during reflect."""
+
+    id: str = Field(description="Mental model ID")
+    text: str = Field(description="Mental model content")
+    context: str | None = Field(default=None, description="Additional context")
+
+
+class ReflectToolCall(BaseModel):
+    """A tool call made during reflect agent execution."""
+
+    tool: str = Field(description="Tool name: lookup, recall, learn, expand")
+    input: dict = Field(description="Tool input parameters")
+    output: dict | None = Field(
+        default=None, description="Tool output (only included when include.tool_calls.output is true)"
+    )
+    duration_ms: int = Field(description="Execution time in milliseconds")
+    iteration: int = Field(default=0, description="Iteration number (1-based) when this tool was called")
+
+
+class ReflectLLMCall(BaseModel):
+    """An LLM call made during reflect agent execution."""
+
+    scope: str = Field(description="Call scope: agent_1, agent_2, final, etc.")
+    duration_ms: int = Field(description="Execution time in milliseconds")
+
+
+class ReflectBasedOn(BaseModel):
+    """Evidence the response is based on: memories, mental models, and directives."""
+
+    memories: list[ReflectFact] = Field(default_factory=list, description="Memory facts used to generate the response")
+    mental_models: list[ReflectMentalModel] = Field(
+        default_factory=list, description="Mental models used during reflection"
+    )
+    directives: list[ReflectDirective] = Field(default_factory=list, description="Directives applied during reflection")
+
+
+class ReflectTrace(BaseModel):
+    """Execution trace of LLM and tool calls during reflection."""
+
+    tool_calls: list[ReflectToolCall] = Field(default_factory=list, description="Tool calls made during reflection")
+    llm_calls: list[ReflectLLMCall] = Field(default_factory=list, description="LLM calls made during reflection")
+
+
 class ReflectResponse(BaseModel):
     """Response model for think endpoint."""
 
@@ -521,21 +594,38 @@ class ReflectResponse(BaseModel):
         json_schema_extra={
             "example": {
                 "text": "Based on my understanding, AI is a transformative technology...",
-                "based_on": [
-                    {"id": "123", "text": "AI is used in healthcare", "type": "world"},
-                    {"id": "456", "text": "I discussed AI applications last week", "type": "experience"},
-                ],
+                "based_on": {
+                    "memories": [
+                        {"id": "123", "text": "AI is used in healthcare", "type": "world"},
+                        {"id": "456", "text": "I discussed AI applications last week", "type": "experience"},
+                    ],
+                },
                 "structured_output": {
                     "summary": "AI is transformative",
                     "key_points": ["Used in healthcare", "Discussed recently"],
                 },
                 "usage": {"input_tokens": 1500, "output_tokens": 500, "total_tokens": 2000},
+                "trace": {
+                    "tool_calls": [{"tool": "recall", "input": {"query": "AI"}, "duration_ms": 150}],
+                    "llm_calls": [{"scope": "agent_1", "duration_ms": 1200}],
+                    "observations": [
+                        {
+                            "id": "obs-1",
+                            "name": "AI Technology",
+                            "type": "concept",
+                            "subtype": "structural",
+                        }
+                    ],
+                },
             }
         }
     )
 
     text: str
-    based_on: list[ReflectFact] = []  # Facts used to generate the response
+    based_on: ReflectBasedOn | None = Field(
+        default=None,
+        description="Evidence used to generate the response. Only present when include.facts is set.",
+    )
     structured_output: dict | None = Field(
         default=None,
         description="Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.",
@@ -544,6 +634,10 @@ class ReflectResponse(BaseModel):
         default=None,
         description="Token usage metrics for LLM calls during reflection.",
     )
+    trace: ReflectTrace | None = Field(
+        default=None,
+        description="Execution trace of tool and LLM calls. Only present when include.tool_calls is set.",
+    )
 
 
 class BanksResponse(BaseModel):
@@ -573,7 +667,7 @@ class BankProfileResponse(BaseModel):
                 "bank_id": "user123",
                 "name": "Alice",
                 "disposition": {"skepticism": 3, "literalism": 3, "empathy": 3},
-                "background": "I am a software engineer with 10 years of experience in startups",
+                "mission": "I am a software engineer helping my team stay organized and ship quality code",
             }
         }
     )
@@ -581,7 +675,9 @@ class BankProfileResponse(BaseModel):
     bank_id: str
     name: str
     disposition: DispositionTraits
-    background: str
+    mission: str = Field(description="The agent's mission - who they are and what they're trying to accomplish")
+    # Deprecated: use mission instead. Kept for backwards compatibility.
+    background: str | None = Field(default=None, description="Deprecated: use mission instead")
 
 
 class UpdateDispositionRequest(BaseModel):
@@ -590,8 +686,32 @@ class UpdateDispositionRequest(BaseModel):
     disposition: DispositionTraits
 
 
+class SetMissionRequest(BaseModel):
+    """Request model for setting/updating the agent's mission."""
+
+    model_config = ConfigDict(
+        json_schema_extra={"example": {"content": "I am a PM helping my engineering team stay organized"}}
+    )
+
+    content: str = Field(description="The mission content - who you are and what you're trying to accomplish")
+
+
+class MissionResponse(BaseModel):
+    """Response model for mission update."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "mission": "I am a PM helping my engineering team stay organized and ship quality code.",
+            }
+        }
+    )
+
+    mission: str
+
+
 class AddBackgroundRequest(BaseModel):
-    """Request model for adding/merging background information."""
+    """Request model for adding/merging background information. Deprecated: use SetMissionRequest instead."""
 
     model_config = ConfigDict(
         json_schema_extra={"example": {"content": "I was born in Texas", "update_disposition": True}}
@@ -599,23 +719,24 @@ class AddBackgroundRequest(BaseModel):
 
     content: str = Field(description="New background information to add or merge")
     update_disposition: bool = Field(
-        default=True, description="If true, infer disposition traits from the merged background (default: true)"
+        default=True, description="Deprecated - disposition is no longer auto-inferred from mission"
     )
 
 
 class BackgroundResponse(BaseModel):
-    """Response model for background update."""
+    """Response model for background update. Deprecated: use MissionResponse instead."""
 
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
-                "background": "I was born in Texas. I am a software engineer with 10 years of experience.",
-                "disposition": {"skepticism": 3, "literalism": 3, "empathy": 3},
+                "mission": "I was born in Texas. I am a software engineer with 10 years of experience.",
             }
         }
     )
 
-    background: str
+    mission: str
+    # Deprecated fields kept for backwards compatibility
+    background: str | None = Field(default=None, description="Deprecated: same as mission")
     disposition: DispositionTraits | None = None
 
 
@@ -625,7 +746,7 @@ class BankListItem(BaseModel):
     bank_id: str
     name: str | None = None
     disposition: DispositionTraits
-    background: str | None = None
+    mission: str | None = None
     created_at: str | None = None
     updated_at: str | None = None
 
@@ -641,7 +762,7 @@ class BankListResponse(BaseModel):
                         "bank_id": "user123",
                         "name": "Alice",
                         "disposition": {"skepticism": 3, "literalism": 3, "empathy": 3},
-                        "background": "I am a software engineer",
+                        "mission": "I am a software engineer helping my team ship quality code",
                         "created_at": "2024-01-15T10:30:00Z",
                         "updated_at": "2024-01-16T14:20:00Z",
                     }
@@ -661,14 +782,16 @@ class CreateBankRequest(BaseModel):
             "example": {
                 "name": "Alice",
                 "disposition": {"skepticism": 3, "literalism": 3, "empathy": 3},
-                "background": "I am a creative software engineer with 10 years of experience",
+                "mission": "I am a PM helping my engineering team stay organized",
             }
         }
     )
 
     name: str | None = None
     disposition: DispositionTraits | None = None
-    background: str | None = None
+    mission: str | None = Field(default=None, description="The agent's mission")
+    # Deprecated: use mission instead
+    background: str | None = Field(default=None, description="Deprecated: use mission instead")
 
 
 class GraphDataResponse(BaseModel):
@@ -894,6 +1017,9 @@ class BankStatsResponse(BaseModel):
                 "links_breakdown": {"fact": {"temporal": 100, "semantic": 60, "entity": 40}},
                 "pending_operations": 2,
                 "failed_operations": 0,
+                "last_consolidated_at": "2024-01-15T10:30:00Z",
+                "pending_consolidation": 0,
+                "total_observations": 45,
             }
         }
     )
@@ -908,6 +1034,156 @@ class BankStatsResponse(BaseModel):
     links_breakdown: dict[str, dict[str, int]]
     pending_operations: int
     failed_operations: int
+    # Consolidation stats
+    last_consolidated_at: str | None = Field(default=None, description="When consolidation last ran (ISO format)")
+    pending_consolidation: int = Field(default=0, description="Number of memories not yet processed into observations")
+    total_observations: int = Field(default=0, description="Total number of observations")
+
+
+# Mental Model models
+
+
+class ObservationEvidenceResponse(BaseModel):
+    """A single piece of evidence supporting an observation."""
+
+    memory_id: str = Field(description="ID of the memory unit this evidence comes from")
+    quote: str = Field(description="Exact quote from the memory supporting the observation")
+    relevance: str = Field(description="Brief explanation of how this quote supports the observation")
+    timestamp: str = Field(description="When the source memory was created (ISO format)")
+
+
+# =========================================================================
+# Directive Models
+# =========================================================================
+
+
+class DirectiveResponse(BaseModel):
+    """Response model for a directive."""
+
+    id: str
+    bank_id: str
+    name: str
+    content: str
+    priority: int = 0
+    is_active: bool = True
+    tags: list[str] = Field(default_factory=list)
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class DirectiveListResponse(BaseModel):
+    """Response model for listing directives."""
+
+    items: list[DirectiveResponse]
+
+
+class CreateDirectiveRequest(BaseModel):
+    """Request model for creating a directive."""
+
+    name: str = Field(description="Human-readable name for the directive")
+    content: str = Field(description="The directive text to inject into prompts")
+    priority: int = Field(default=0, description="Higher priority directives are injected first")
+    is_active: bool = Field(default=True, description="Whether this directive is active")
+    tags: list[str] = Field(default_factory=list, description="Tags for filtering")
+
+
+class UpdateDirectiveRequest(BaseModel):
+    """Request model for updating a directive."""
+
+    name: str | None = Field(default=None, description="New name")
+    content: str | None = Field(default=None, description="New content")
+    priority: int | None = Field(default=None, description="New priority")
+    is_active: bool | None = Field(default=None, description="New active status")
+    tags: list[str] | None = Field(default=None, description="New tags")
+
+
+# =========================================================================
+# Mental Models (stored reflect responses)
+# =========================================================================
+
+
+class MentalModelTrigger(BaseModel):
+    """Trigger settings for a mental model."""
+
+    refresh_after_consolidation: bool = Field(
+        default=False,
+        description="If true, refresh this mental model after observations consolidation (real-time mode)",
+    )
+
+
+class MentalModelResponse(BaseModel):
+    """Response model for a mental model (stored reflect response)."""
+
+    id: str
+    bank_id: str
+    name: str
+    source_query: str
+    content: str
+    tags: list[str] = Field(default_factory=list)
+    max_tokens: int = Field(default=2048)
+    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger)
+    last_refreshed_at: str | None = None
+    created_at: str | None = None
+    reflect_response: dict | None = Field(
+        default=None,
+        description="Full reflect API response payload including based_on facts and observations",
+    )
+
+
+class MentalModelListResponse(BaseModel):
+    """Response model for listing mental models."""
+
+    items: list[MentalModelResponse]
+
+
+class CreateMentalModelRequest(BaseModel):
+    """Request model for creating a mental model."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "name": "Team Communication Preferences",
+                "source_query": "How does the team prefer to communicate?",
+                "tags": ["team"],
+                "max_tokens": 2048,
+                "trigger": {"refresh_after_consolidation": False},
+            }
+        }
+    )
+
+    name: str = Field(description="Human-readable name for the mental model")
+    source_query: str = Field(description="The query to run to generate content")
+    tags: list[str] = Field(default_factory=list, description="Tags for scoped visibility")
+    max_tokens: int = Field(default=2048, ge=256, le=8192, description="Maximum tokens for generated content")
+    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger, description="Trigger settings")
+
+
+class CreateMentalModelResponse(BaseModel):
+    """Response model for mental model creation."""
+
+    operation_id: str = Field(description="Operation ID to track progress")
+
+
+class UpdateMentalModelRequest(BaseModel):
+    """Request model for updating a mental model."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "name": "Updated Team Communication Preferences",
+                "source_query": "How does the team prefer to communicate?",
+                "max_tokens": 4096,
+                "tags": ["team", "communication"],
+                "trigger": {"refresh_after_consolidation": True},
+            }
+        }
+    )
+
+    name: str | None = Field(default=None, description="New name for the mental model")
+    source_query: str | None = Field(default=None, description="New source query for the mental model")
+    max_tokens: int | None = Field(default=None, ge=256, le=8192, description="Maximum tokens for generated content")
+    tags: list[str] | None = Field(default=None, description="Tags for scoped visibility")
+    trigger: MentalModelTrigger | None = Field(default=None, description="Trigger settings")
 
 
 class OperationResponse(BaseModel):
@@ -919,7 +1195,7 @@ class OperationResponse(BaseModel):
                 "id": "550e8400-e29b-41d4-a716-446655440000",
                 "task_type": "retain",
                 "items_count": 5,
-                "document_id": "meeting-notes-2024",
+                "document_id": None,
                 "created_at": "2024-01-15T10:30:00Z",
                 "status": "pending",
                 "error_message": None,
@@ -930,12 +1206,19 @@ class OperationResponse(BaseModel):
     id: str
     task_type: str
     items_count: int
-    document_id: str | None
+    document_id: str | None = None
     created_at: str
     status: str
     error_message: str | None
 
 
+class ConsolidationResponse(BaseModel):
+    """Response model for consolidation trigger endpoint."""
+
+    operation_id: str = Field(description="ID of the async consolidation operation")
+    deduplicated: bool = Field(default=False, description="True if an existing pending task was reused")
+
+
 class OperationsListResponse(BaseModel):
     """Response model for list operations endpoint."""
 
@@ -943,12 +1226,13 @@ class OperationsListResponse(BaseModel):
         json_schema_extra={
             "example": {
                 "bank_id": "user123",
+                "total": 150,
+                "limit": 20,
+                "offset": 0,
                 "operations": [
                     {
                         "id": "550e8400-e29b-41d4-a716-446655440000",
                         "task_type": "retain",
-                        "items_count": 5,
-                        "document_id": None,
                         "created_at": "2024-01-15T10:30:00Z",
                         "status": "pending",
                         "error_message": None,
@@ -959,6 +1243,9 @@ class OperationsListResponse(BaseModel):
     )
 
     bank_id: str
+    total: int
+    limit: int
+    offset: int
     operations: list[OperationResponse]
 
 
@@ -980,6 +1267,76 @@ class CancelOperationResponse(BaseModel):
     operation_id: str
 
 
+class OperationStatusResponse(BaseModel):
+    """Response model for getting a single operation status."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "operation_id": "550e8400-e29b-41d4-a716-446655440000",
+                "status": "completed",
+                "operation_type": "refresh_mental_models",
+                "created_at": "2024-01-15T10:30:00Z",
+                "updated_at": "2024-01-15T10:31:30Z",
+                "completed_at": "2024-01-15T10:31:30Z",
+                "error_message": None,
+            }
+        }
+    )
+
+    operation_id: str
+    status: Literal["pending", "completed", "failed", "not_found"]
+    operation_type: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    completed_at: str | None = None
+    error_message: str | None = None
+
+
+class AsyncOperationSubmitResponse(BaseModel):
+    """Response model for submitting an async operation."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "operation_id": "550e8400-e29b-41d4-a716-446655440000",
+                "status": "queued",
+            }
+        }
+    )
+
+    operation_id: str
+    status: str
+
+
+class FeaturesInfo(BaseModel):
+    """Feature flags indicating which capabilities are enabled."""
+
+    observations: bool = Field(description="Whether observations (auto-consolidation) are enabled")
+    mcp: bool = Field(description="Whether MCP (Model Context Protocol) server is enabled")
+    worker: bool = Field(description="Whether the background worker is enabled")
+
+
+class VersionResponse(BaseModel):
+    """Response model for the version/info endpoint."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "api_version": "1.0.0",
+                "features": {
+                    "observations": False,
+                    "mcp": True,
+                    "worker": True,
+                },
+            }
+        }
+    )
+
+    api_version: str = Field(description="API version string")
+    features: FeaturesInfo = Field(description="Enabled feature flags")
+
+
 def create_app(
     memory: MemoryEngine,
     initialize_memory: bool = True,
@@ -1015,6 +1372,16 @@ def create_app(
         Lifespan context manager for startup and shutdown events.
         Note: This only fires when running the app standalone, not when mounted.
         """
+        import asyncio
+        import socket
+
+        from hindsight_api.config import get_config
+        from hindsight_api.worker import WorkerPoller
+
+        config = get_config()
+        poller = None
+        poller_task = None
+
         # Initialize OpenTelemetry metrics
         try:
             prometheus_reader = initialize_metrics(service_name="hindsight-api", service_version="1.0.0")
@@ -1037,6 +1404,21 @@ def create_app(
                 metrics_collector.set_db_pool(memory._pool)
                 logging.info("DB pool metrics configured")
 
+        # Start worker poller if enabled (standalone mode)
+        if config.worker_enabled and memory._pool is not None:
+            worker_id = config.worker_id or socket.gethostname()
+            poller = WorkerPoller(
+                pool=memory._pool,
+                worker_id=worker_id,
+                executor=memory.execute_task,
+                poll_interval_ms=config.worker_poll_interval_ms,
+                batch_size=config.worker_batch_size,
+                max_retries=config.worker_max_retries,
+                tenant_extension=getattr(memory, "_tenant_extension", None),
+            )
+            poller_task = asyncio.create_task(poller.run())
+            logging.info(f"Worker poller started (worker_id={worker_id})")
+
         # Call HTTP extension startup hook
         if http_extension:
             await http_extension.on_startup()
@@ -1044,6 +1426,17 @@ def create_app(
 
         yield
 
+        # Shutdown worker poller if running
+        if poller is not None:
+            await poller.shutdown_graceful(timeout=30.0)
+            if poller_task is not None:
+                poller_task.cancel()
+                try:
+                    await poller_task
+                except asyncio.CancelledError:
+                    pass
+            logging.info("Worker poller stopped")
+
         # Call HTTP extension shutdown hook
         if http_extension:
             await http_extension.on_shutdown()
@@ -1158,6 +1551,34 @@ def _register_routes(app: FastAPI):
         status_code = 200 if health.get("status") == "healthy" else 503
         return JSONResponse(content=health, status_code=status_code)
 
+    @app.get(
+        "/version",
+        response_model=VersionResponse,
+        summary="Get API version and feature flags",
+        description="Returns API version information and enabled feature flags. "
+        "Use this to check which capabilities are available in this deployment.",
+        tags=["Monitoring"],
+        operation_id="get_version",
+    )
+    async def version_endpoint() -> VersionResponse:
+        """
+        Get API version and enabled features.
+
+        Returns version info and feature flags that can be used by clients
+        to determine which capabilities are available.
+        """
+        from hindsight_api.config import get_config
+
+        config = get_config()
+        return VersionResponse(
+            api_version="1.0.0",
+            features=FeaturesInfo(
+                observations=config.enable_observations,
+                mcp=config.mcp_enabled,
+                worker=config.worker_enabled,
+            ),
+        )
+
     @app.get(
         "/metrics",
         summary="Prometheus metrics endpoint",
@@ -1301,8 +1722,10 @@ def _register_routes(app: FastAPI):
         metrics = get_metrics_collector()
 
         try:
-            # Default to world, experience, opinion if not specified (exclude observation by default)
+            # Default to world and experience if not specified (exclude observation and opinion)
+            # Filter out 'opinion' even if requested - opinions are excluded from recall
             fact_types = request.types if request.types else list(VALID_RECALL_FACT_TYPES)
+            fact_types = [ft for ft in fact_types if ft != "opinion"]
 
             # Parse query_timestamp if provided
             question_date = None
@@ -1391,7 +1814,10 @@ def _register_routes(app: FastAPI):
                     )
 
             response = RecallResponse(
-                results=recall_results, trace=core_result.trace, entities=entities_response, chunks=chunks_response
+                results=recall_results,
+                trace=core_result.trace,
+                entities=entities_response,
+                chunks=chunks_response,
             )
 
             handler_duration = time.time() - handler_start
@@ -1442,13 +1868,18 @@ def _register_routes(app: FastAPI):
         metrics = get_metrics_collector()
 
         try:
+            # Handle deprecated context field by concatenating with query
+            query = request.query
+            if request.context:
+                query = f"{request.query}\n\nAdditional context: {request.context}"
+
             # Use the memory system's reflect_async method (record metrics)
             with metrics.record_operation("reflect", bank_id=bank_id, source="api", budget=request.budget.value):
                 core_result = await app.state.memory.reflect_async(
                     bank_id=bank_id,
-                    query=request.query,
+                    query=query,
                     budget=request.budget,
-                    context=request.context,
+                    context=None,  # Deprecated, now concatenated with query
                     max_tokens=request.max_tokens,
                     response_schema=request.response_schema,
                     request_context=request_context,
@@ -1456,27 +1887,73 @@ def _register_routes(app: FastAPI):
                     tags_match=request.tags_match,
                 )
 
-            # Convert core MemoryFact objects to API ReflectFact objects if facts are requested
-            based_on_facts = []
+            # Build based_on (memories + mental_models + directives) if facts are requested
+            based_on_result: ReflectBasedOn | None = None
             if request.include.facts is not None:
+                memories = []
+                mental_models = []
+                directives = []
                 for fact_type, facts in core_result.based_on.items():
-                    for fact in facts:
-                        based_on_facts.append(
-                            ReflectFact(
-                                id=fact.id,
-                                text=fact.text,
-                                type=fact.fact_type,
-                                context=fact.context,
-                                occurred_start=fact.occurred_start,
-                                occurred_end=fact.occurred_end,
+                    if fact_type == "directives":
+                        # Directives have different structure (id, name, content)
+                        for directive in facts:
+                            directives.append(
+                                ReflectDirective(
+                                    id=directive.id,
+                                    name=directive.name,
+                                    content=directive.content,
+                                )
+                            )
+                    elif fact_type == "mental_models":
+                        # Mental models are MemoryFact with type "mental_models"
+                        for fact in facts:
+                            mental_models.append(
+                                ReflectMentalModel(
+                                    id=fact.id,
+                                    text=fact.text,
+                                    context=fact.context,
+                                )
                             )
-                        )
+                    else:
+                        for fact in facts:
+                            memories.append(
+                                ReflectFact(
+                                    id=fact.id,
+                                    text=fact.text,
+                                    type=fact.fact_type,
+                                    context=fact.context,
+                                    occurred_start=fact.occurred_start,
+                                    occurred_end=fact.occurred_end,
+                                )
+                            )
+                based_on_result = ReflectBasedOn(memories=memories, mental_models=mental_models, directives=directives)
+
+            # Build trace (tool_calls + llm_calls + observations) if tool_calls is requested
+            trace_result: ReflectTrace | None = None
+            if request.include.tool_calls is not None:
+                include_output = request.include.tool_calls.output
+                tool_calls = [
+                    ReflectToolCall(
+                        tool=tc.tool,
+                        input=tc.input,
+                        output=tc.output if include_output else None,
+                        duration_ms=tc.duration_ms,
+                        iteration=tc.iteration,
+                    )
+                    for tc in core_result.tool_trace
+                ]
+                llm_calls = [ReflectLLMCall(scope=lc.scope, duration_ms=lc.duration_ms) for lc in core_result.llm_trace]
+                trace_result = ReflectTrace(
+                    tool_calls=tool_calls,
+                    llm_calls=llm_calls,
+                )
 
             return ReflectResponse(
                 text=core_result.text,
-                based_on=based_on_facts,
+                based_on=based_on_result,
                 structured_output=core_result.structured_output,
                 usage=core_result.usage,
+                trace=trace_result,
             )
 
         except OperationValidationError as e:
@@ -1602,6 +2079,31 @@ def _register_routes(app: FastAPI):
                 )
                 total_documents = doc_count_result["count"] if doc_count_result else 0
 
+                # Get consolidation stats from memory-level tracking
+                consolidation_stats = await conn.fetchrow(
+                    f"""
+                    SELECT
+                        MAX(consolidated_at) as last_consolidated_at,
+                        COUNT(*) FILTER (WHERE consolidated_at IS NULL AND fact_type IN ('experience', 'world')) as pending
+                    FROM {fq_table("memory_units")}
+                    WHERE bank_id = $1
+                    """,
+                    bank_id,
+                )
+                last_consolidated_at = consolidation_stats["last_consolidated_at"] if consolidation_stats else None
+                pending_consolidation = consolidation_stats["pending"] if consolidation_stats else 0
+
+                # Count total observations (consolidated knowledge)
+                observation_count_result = await conn.fetchrow(
+                    f"""
+                    SELECT COUNT(*) as count
+                    FROM {fq_table("memory_units")}
+                    WHERE bank_id = $1 AND fact_type = 'observation'
+                    """,
+                    bank_id,
+                )
+                total_observations = observation_count_result["count"] if observation_count_result else 0
+
                 # Format results
                 nodes_by_type = {row["fact_type"]: row["count"] for row in node_stats}
                 links_by_type = {row["link_type"]: row["count"] for row in link_stats}
@@ -1631,6 +2133,9 @@ def _register_routes(app: FastAPI):
                     links_breakdown=links_breakdown,
                     pending_operations=pending_operations,
                     failed_operations=failed_operations,
+                    last_consolidated_at=(last_consolidated_at.isoformat() if last_consolidated_at else None),
+                    pending_consolidation=pending_consolidation,
+                    total_observations=total_observations,
                 )
 
         except (AuthenticationError, HTTPException):
@@ -1718,54 +2223,422 @@ def _register_routes(app: FastAPI):
     @app.post(
         "/v1/default/banks/{bank_id}/entities/{entity_id}/regenerate",
         response_model=EntityDetailResponse,
-        summary="Regenerate entity observations",
-        description="Regenerate observations for an entity based on all facts mentioning it.",
+        summary="Regenerate entity observations (deprecated)",
+        description="This endpoint is deprecated. Entity observations have been replaced by mental models.",
         operation_id="regenerate_entity_observations",
         tags=["Entities"],
+        deprecated=True,
     )
     async def api_regenerate_entity_observations(
         bank_id: str,
         entity_id: str,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Regenerate observations for an entity."""
+        """Regenerate observations for an entity. DEPRECATED."""
+        raise HTTPException(
+            status_code=410,
+            detail="This endpoint is deprecated. Entity observations are no longer supported.",
+        )
+
+    # =========================================================================
+    # =========================================================================
+    # MENTAL MODELS ENDPOINTS (stored reflect responses)
+    # =========================================================================
+
+    @app.get(
+        "/v1/default/banks/{bank_id}/mental-models",
+        response_model=MentalModelListResponse,
+        summary="List mental models",
+        description="List user-curated living documents that stay current.",
+        operation_id="list_mental_models",
+        tags=["Mental Models"],
+    )
+    async def api_list_mental_models(
+        bank_id: str,
+        tags_filter: list[str] | None = Query(None, alias="tags", description="Filter by tags"),
+        tags_match: Literal["any", "all", "exact"] = Query("any", description="How to match tags"),
+        limit: int = Query(100, ge=1, le=1000),
+        offset: int = Query(0, ge=0),
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """List mental models for a bank."""
         try:
-            # Get the entity to verify it exists and get canonical_name
-            entity = await app.state.memory.get_entity(bank_id, entity_id, request_context=request_context)
+            mental_models = await app.state.memory.list_mental_models(
+                bank_id=bank_id,
+                tags=tags_filter,
+                tags_match=tags_match,
+                limit=limit,
+                offset=offset,
+                request_context=request_context,
+            )
+            return MentalModelListResponse(items=[MentalModelResponse(**m) for m in mental_models])
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
 
-            if entity is None:
-                raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/mental-models: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
 
-            # Regenerate observations
-            await app.state.memory.regenerate_entity_observations(
+    @app.get(
+        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
+        response_model=MentalModelResponse,
+        summary="Get mental model",
+        description="Get a specific mental model by ID.",
+        operation_id="get_mental_model",
+        tags=["Mental Models"],
+    )
+    async def api_get_mental_model(
+        bank_id: str,
+        mental_model_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Get a mental model by ID."""
+        try:
+            mental_model = await app.state.memory.get_mental_model(
                 bank_id=bank_id,
-                entity_id=entity_id,
-                entity_name=entity["canonical_name"],
+                mental_model_id=mental_model_id,
                 request_context=request_context,
             )
+            if mental_model is None:
+                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
+            return MentalModelResponse(**mental_model)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
 
-            # Get updated entity with new observations
-            entity = await app.state.memory.get_entity(bank_id, entity_id, request_context=request_context)
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
 
-            return EntityDetailResponse(
-                id=entity["id"],
-                canonical_name=entity["canonical_name"],
-                mention_count=entity["mention_count"],
-                first_seen=entity["first_seen"],
-                last_seen=entity["last_seen"],
-                metadata=_parse_metadata(entity["metadata"]),
-                observations=[
-                    EntityObservationResponse(text=obs.text, mentioned_at=obs.mentioned_at)
-                    for obs in entity["observations"]
-                ],
+    @app.post(
+        "/v1/default/banks/{bank_id}/mental-models",
+        response_model=CreateMentalModelResponse,
+        summary="Create mental model",
+        description="Create a mental model by running reflect with the source query in the background. "
+        "Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. "
+        "Use the operations endpoint to check completion status.",
+        operation_id="create_mental_model",
+        tags=["Mental Models"],
+    )
+    async def api_create_mental_model(
+        bank_id: str,
+        body: CreateMentalModelRequest,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Create a mental model (async - returns operation_id)."""
+        try:
+            # 1. Create the mental model with placeholder content
+            mental_model = await app.state.memory.create_mental_model(
+                bank_id=bank_id,
+                name=body.name,
+                source_query=body.source_query,
+                content="Generating content...",
+                tags=body.tags if body.tags else None,
+                max_tokens=body.max_tokens,
+                trigger=body.trigger.model_dump() if body.trigger else None,
+                request_context=request_context,
+            )
+            # 2. Schedule a refresh to generate the actual content
+            result = await app.state.memory.submit_async_refresh_mental_model(
+                bank_id=bank_id,
+                mental_model_id=mental_model["id"],
+                request_context=request_context,
+            )
+            return CreateMentalModelResponse(operation_id=result["operation_id"])
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in POST /v1/default/banks/{bank_id}/mental-models: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.post(
+        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh",
+        response_model=AsyncOperationSubmitResponse,
+        summary="Refresh mental model",
+        description="Submit an async task to re-run the source query through reflect and update the content.",
+        operation_id="refresh_mental_model",
+        tags=["Mental Models"],
+    )
+    async def api_refresh_mental_model(
+        bank_id: str,
+        mental_model_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Refresh a mental model by re-running its source query (async)."""
+        try:
+            result = await app.state.memory.submit_async_refresh_mental_model(
+                bank_id=bank_id,
+                mental_model_id=mental_model_id,
+                request_context=request_context,
+            )
+            return AsyncOperationSubmitResponse(operation_id=result["operation_id"], status="queued")
+        except ValueError as e:
+            raise HTTPException(status_code=404, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(
+                f"Error in POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh: {error_detail}"
+            )
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.patch(
+        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
+        response_model=MentalModelResponse,
+        summary="Update mental model",
+        description="Update a mental model's name and/or source query.",
+        operation_id="update_mental_model",
+        tags=["Mental Models"],
+    )
+    async def api_update_mental_model(
+        bank_id: str,
+        mental_model_id: str,
+        body: UpdateMentalModelRequest,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Update a mental model."""
+        try:
+            mental_model = await app.state.memory.update_mental_model(
+                bank_id=bank_id,
+                mental_model_id=mental_model_id,
+                name=body.name,
+                source_query=body.source_query,
+                max_tokens=body.max_tokens,
+                tags=body.tags,
+                trigger=body.trigger.model_dump() if body.trigger else None,
+                request_context=request_context,
+            )
+            if mental_model is None:
+                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
+            return MentalModelResponse(**mental_model)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.delete(
+        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
+        summary="Delete mental model",
+        description="Delete a mental model.",
+        operation_id="delete_mental_model",
+        tags=["Mental Models"],
+    )
+    async def api_delete_mental_model(
+        bank_id: str,
+        mental_model_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Delete a mental model."""
+        try:
+            deleted = await app.state.memory.delete_mental_model(
+                bank_id=bank_id,
+                mental_model_id=mental_model_id,
+                request_context=request_context,
+            )
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
+            return {"status": "deleted"}
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    # =========================================================================
+    # DIRECTIVES ENDPOINTS
+    # =========================================================================
+
+    @app.get(
+        "/v1/default/banks/{bank_id}/directives",
+        response_model=DirectiveListResponse,
+        summary="List directives",
+        description="List hard rules that are injected into prompts.",
+        operation_id="list_directives",
+        tags=["Directives"],
+    )
+    async def api_list_directives(
+        bank_id: str,
+        tags_filter: list[str] | None = Query(None, alias="tags", description="Filter by tags"),
+        tags_match: Literal["any", "all", "exact"] = Query("any", description="How to match tags"),
+        active_only: bool = Query(True, description="Only return active directives"),
+        limit: int = Query(100, ge=1, le=1000),
+        offset: int = Query(0, ge=0),
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """List directives for a bank."""
+        try:
+            directives = await app.state.memory.list_directives(
+                bank_id=bank_id,
+                tags=tags_filter,
+                tags_match=tags_match,
+                active_only=active_only,
+                limit=limit,
+                offset=offset,
+                request_context=request_context,
+            )
+            return DirectiveListResponse(items=[DirectiveResponse(**d) for d in directives])
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/directives: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.get(
+        "/v1/default/banks/{bank_id}/directives/{directive_id}",
+        response_model=DirectiveResponse,
+        summary="Get directive",
+        description="Get a specific directive by ID.",
+        operation_id="get_directive",
+        tags=["Directives"],
+    )
+    async def api_get_directive(
+        bank_id: str,
+        directive_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Get a directive by ID."""
+        try:
+            directive = await app.state.memory.get_directive(
+                bank_id=bank_id,
+                directive_id=directive_id,
+                request_context=request_context,
+            )
+            if directive is None:
+                raise HTTPException(status_code=404, detail=f"Directive '{directive_id}' not found")
+            return DirectiveResponse(**directive)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/directives/{directive_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.post(
+        "/v1/default/banks/{bank_id}/directives",
+        response_model=DirectiveResponse,
+        summary="Create directive",
+        description="Create a hard rule that will be injected into prompts.",
+        operation_id="create_directive",
+        tags=["Directives"],
+    )
+    async def api_create_directive(
+        bank_id: str,
+        body: CreateDirectiveRequest,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Create a directive."""
+        try:
+            directive = await app.state.memory.create_directive(
+                bank_id=bank_id,
+                name=body.name,
+                content=body.content,
+                priority=body.priority,
+                is_active=body.is_active,
+                tags=body.tags,
+                request_context=request_context,
+            )
+            return DirectiveResponse(**directive)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in POST /v1/default/banks/{bank_id}/directives: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.patch(
+        "/v1/default/banks/{bank_id}/directives/{directive_id}",
+        response_model=DirectiveResponse,
+        summary="Update directive",
+        description="Update a directive's properties.",
+        operation_id="update_directive",
+        tags=["Directives"],
+    )
+    async def api_update_directive(
+        bank_id: str,
+        directive_id: str,
+        body: UpdateDirectiveRequest,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Update a directive."""
+        try:
+            directive = await app.state.memory.update_directive(
+                bank_id=bank_id,
+                directive_id=directive_id,
+                name=body.name,
+                content=body.content,
+                priority=body.priority,
+                is_active=body.is_active,
+                tags=body.tags,
+                request_context=request_context,
+            )
+            if directive is None:
+                raise HTTPException(status_code=404, detail=f"Directive '{directive_id}' not found")
+            return DirectiveResponse(**directive)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}/directives/{directive_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.delete(
+        "/v1/default/banks/{bank_id}/directives/{directive_id}",
+        summary="Delete directive",
+        description="Delete a directive.",
+        operation_id="delete_directive",
+        tags=["Directives"],
+    )
+    async def api_delete_directive(
+        bank_id: str,
+        directive_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Delete a directive."""
+        try:
+            deleted = await app.state.memory.delete_directive(
+                bank_id=bank_id,
+                directive_id=directive_id,
+                request_context=request_context,
             )
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Directive '{directive_id}' not found")
+            return {"status": "deleted"}
         except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in /v1/default/banks/{bank_id}/entities/{entity_id}/regenerate: {error_detail}")
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/directives/{directive_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.get(
@@ -1968,17 +2841,28 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/operations",
         response_model=OperationsListResponse,
         summary="List async operations",
-        description="Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations",
+        description="Get a list of async operations for a specific agent, with optional filtering by status. Results are sorted by most recent first.",
         operation_id="list_operations",
         tags=["Operations"],
     )
-    async def api_list_operations(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
-        """List all async operations (pending and failed) for a memory bank."""
+    async def api_list_operations(
+        bank_id: str,
+        status: str | None = Query(default=None, description="Filter by status: pending, completed, or failed"),
+        limit: int = Query(default=20, ge=1, le=100, description="Maximum number of operations to return"),
+        offset: int = Query(default=0, ge=0, description="Number of operations to skip"),
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """List async operations for a memory bank with optional filtering and pagination."""
         try:
-            operations = await app.state.memory.list_operations(bank_id, request_context=request_context)
+            result = await app.state.memory.list_operations(
+                bank_id, status=status, limit=limit, offset=offset, request_context=request_context
+            )
             return OperationsListResponse(
                 bank_id=bank_id,
-                operations=[OperationResponse(**op) for op in operations],
+                total=result["total"],
+                limit=limit,
+                offset=offset,
+                operations=[OperationResponse(**op) for op in result["operations"]],
             )
         except (AuthenticationError, HTTPException):
             raise
@@ -1989,6 +2873,37 @@ def _register_routes(app: FastAPI):
             logger.error(f"Error in /v1/default/banks/{bank_id}/operations: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
+    @app.get(
+        "/v1/default/banks/{bank_id}/operations/{operation_id}",
+        response_model=OperationStatusResponse,
+        summary="Get operation status",
+        description="Get the status of a specific async operation. Returns 'pending', 'completed', or 'failed'. "
+        "Completed operations are removed from storage, so 'completed' means the operation finished successfully.",
+        operation_id="get_operation_status",
+        tags=["Operations"],
+    )
+    async def api_get_operation_status(
+        bank_id: str, operation_id: str, request_context: RequestContext = Depends(get_request_context)
+    ):
+        """Get the status of an async operation."""
+        try:
+            # Validate UUID format
+            try:
+                uuid.UUID(operation_id)
+            except ValueError:
+                raise HTTPException(status_code=400, detail=f"Invalid operation_id format: {operation_id}")
+
+            result = await app.state.memory.get_operation_status(bank_id, operation_id, request_context=request_context)
+            return OperationStatusResponse(**result)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/operations/{operation_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
     @app.delete(
         "/v1/default/banks/{bank_id}/operations/{operation_id}",
         response_model=CancelOperationResponse,
@@ -2025,12 +2940,12 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/profile",
         response_model=BankProfileResponse,
         summary="Get memory bank profile",
-        description="Get disposition traits and background for a memory bank. Auto-creates agent with defaults if not exists.",
+        description="Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.",
         operation_id="get_bank_profile",
         tags=["Banks"],
     )
     async def api_get_bank_profile(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
-        """Get memory bank profile (disposition + background)."""
+        """Get memory bank profile (disposition + mission)."""
         try:
             profile = await app.state.memory.get_bank_profile(bank_id, request_context=request_context)
             # Convert DispositionTraits object to dict for Pydantic
@@ -2039,11 +2954,13 @@ def _register_routes(app: FastAPI):
                 if hasattr(profile["disposition"], "model_dump")
                 else dict(profile["disposition"])
             )
+            mission = profile.get("mission") or ""
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=profile["name"],
                 disposition=DispositionTraits(**disposition_dict),
-                background=profile["background"],
+                mission=mission,
+                background=mission,  # Backwards compat
             )
         except (AuthenticationError, HTTPException):
             raise
@@ -2079,11 +2996,13 @@ def _register_routes(app: FastAPI):
                 if hasattr(profile["disposition"], "model_dump")
                 else dict(profile["disposition"])
             )
+            mission = profile.get("mission") or ""
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=profile["name"],
                 disposition=DispositionTraits(**disposition_dict),
-                background=profile["background"],
+                mission=mission,
+                background=mission,  # Backwards compat
             )
         except (AuthenticationError, HTTPException):
             raise
@@ -2097,25 +3016,22 @@ def _register_routes(app: FastAPI):
     @app.post(
         "/v1/default/banks/{bank_id}/background",
         response_model=BackgroundResponse,
-        summary="Add/merge memory bank background",
-        description="Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers disposition traits.",
+        summary="Add/merge memory bank background (deprecated)",
+        description="Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.",
         operation_id="add_bank_background",
         tags=["Banks"],
+        deprecated=True,
     )
     async def api_add_bank_background(
         bank_id: str, request: AddBackgroundRequest, request_context: RequestContext = Depends(get_request_context)
     ):
-        """Add or merge bank background information. Optionally infer disposition traits."""
+        """Deprecated: Add or merge bank background. Now updates mission field."""
         try:
-            result = await app.state.memory.merge_bank_background(
-                bank_id, request.content, update_disposition=request.update_disposition, request_context=request_context
+            result = await app.state.memory.merge_bank_mission(
+                bank_id, request.content, request_context=request_context
             )
-
-            response = BackgroundResponse(background=result["background"])
-            if "disposition" in result:
-                response.disposition = DispositionTraits(**result["disposition"])
-
-            return response
+            mission = result.get("mission") or ""
+            return BackgroundResponse(mission=mission, background=mission)
         except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
@@ -2129,24 +3045,25 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}",
         response_model=BankProfileResponse,
         summary="Create or update memory bank",
-        description="Create a new agent or update existing agent with disposition and background. Auto-fills missing fields with defaults.",
+        description="Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.",
         operation_id="create_or_update_bank",
         tags=["Banks"],
     )
     async def api_create_or_update_bank(
         bank_id: str, request: CreateBankRequest, request_context: RequestContext = Depends(get_request_context)
     ):
-        """Create or update an agent with disposition and background."""
+        """Create or update an agent with disposition and mission."""
         try:
             # Ensure bank exists by getting profile (auto-creates with defaults)
             await app.state.memory.get_bank_profile(bank_id, request_context=request_context)
 
-            # Update name and/or background if provided
-            if request.name is not None or request.background is not None:
+            # Update name and/or mission if provided (support both mission and deprecated background)
+            mission_value = request.mission or request.background
+            if request.name is not None or mission_value is not None:
                 await app.state.memory.update_bank(
                     bank_id,
                     name=request.name,
-                    background=request.background,
+                    mission=mission_value,
                     request_context=request_context,
                 )
 
@@ -2163,11 +3080,13 @@ def _register_routes(app: FastAPI):
                 if hasattr(final_profile["disposition"], "model_dump")
                 else dict(final_profile["disposition"])
             )
+            mission = final_profile.get("mission") or ""
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=final_profile["name"],
                 disposition=DispositionTraits(**disposition_dict),
-                background=final_profile["background"],
+                mission=mission,
+                background=mission,  # Backwards compat
             )
         except (AuthenticationError, HTTPException):
             raise
@@ -2178,6 +3097,62 @@ def _register_routes(app: FastAPI):
             logger.error(f"Error in /v1/default/banks/{bank_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
+    @app.patch(
+        "/v1/default/banks/{bank_id}",
+        response_model=BankProfileResponse,
+        summary="Partial update memory bank",
+        description="Partially update an agent's profile. Only provided fields will be updated.",
+        operation_id="update_bank",
+        tags=["Banks"],
+    )
+    async def api_update_bank(
+        bank_id: str, request: CreateBankRequest, request_context: RequestContext = Depends(get_request_context)
+    ):
+        """Partially update an agent's profile (name, mission, disposition)."""
+        try:
+            # Ensure bank exists
+            await app.state.memory.get_bank_profile(bank_id, request_context=request_context)
+
+            # Update name and/or mission if provided
+            mission_value = request.mission or request.background
+            if request.name is not None or mission_value is not None:
+                await app.state.memory.update_bank(
+                    bank_id,
+                    name=request.name,
+                    mission=mission_value,
+                    request_context=request_context,
+                )
+
+            # Update disposition if provided
+            if request.disposition is not None:
+                await app.state.memory.update_bank_disposition(
+                    bank_id, request.disposition.model_dump(), request_context=request_context
+                )
+
+            # Get final profile
+            final_profile = await app.state.memory.get_bank_profile(bank_id, request_context=request_context)
+            disposition_dict = (
+                final_profile["disposition"].model_dump()
+                if hasattr(final_profile["disposition"], "model_dump")
+                else dict(final_profile["disposition"])
+            )
+            mission = final_profile.get("mission") or ""
+            return BankProfileResponse(
+                bank_id=bank_id,
+                name=final_profile["name"],
+                disposition=DispositionTraits(**disposition_dict),
+                mission=mission,
+                background=mission,  # Backwards compat
+            )
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
     @app.delete(
         "/v1/default/banks/{bank_id}",
         response_model=DeleteResponse,
@@ -2207,6 +3182,57 @@ def _register_routes(app: FastAPI):
             logger.error(f"Error in DELETE /v1/default/banks/{bank_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
+    @app.delete(
+        "/v1/default/banks/{bank_id}/observations",
+        response_model=DeleteResponse,
+        summary="Clear all observations",
+        description="Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.",
+        operation_id="clear_observations",
+        tags=["Banks"],
+    )
+    async def api_clear_observations(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
+        """Clear all observations for a bank."""
+        try:
+            result = await app.state.memory.clear_observations(bank_id, request_context=request_context)
+            return DeleteResponse(
+                success=True,
+                message=f"Cleared {result.get('deleted_count', 0)} observations",
+                deleted_count=result.get("deleted_count", 0),
+            )
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/observations: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.post(
+        "/v1/default/banks/{bank_id}/consolidate",
+        response_model=ConsolidationResponse,
+        summary="Trigger consolidation",
+        description="Run memory consolidation to create/update observations from recent memories.",
+        operation_id="trigger_consolidation",
+        tags=["Banks"],
+    )
+    async def api_trigger_consolidation(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
+        """Trigger consolidation for a bank (async)."""
+        try:
+            result = await app.state.memory.submit_async_consolidation(bank_id=bank_id, request_context=request_context)
+            return ConsolidationResponse(
+                operation_id=result["operation_id"],
+                deduplicated=result.get("deduplicated", False),
+            )
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in POST /v1/default/banks/{bank_id}/consolidate: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
     @app.post(
         "/v1/default/banks/{bank_id}/memories",
         response_model=RetainResponse,