tests

AGENTS.md

@@ -1,3 +1,3 @@
 # AGENTS.md
 
-See [CLAUDE.md](./CLAUDE.md) for project documentation and coding conventions.
+See [CLAUDE.md](./CLAUDE.md) for project documentation and coding conventions.

CLAUDE.md

@@ -7,7 +7,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Hindsight is an agent memory system that provides long-term memory for AI agents using biomimetic data structures. Memories are organized as:
 - **World facts**: General knowledge ("The sky is blue")
 - **Experience facts**: Personal experiences ("I visited Paris in 2023")
-- **Mental models**: Structured knowledge containers derived from reflection with evidence-grounded observations
+- **Opinion facts**: Beliefs with confidence scores ("Paris is beautiful" - 0.9 confidence)
+- **Observations**: Complex mental models derived from reflection
 
 ## Development Commands
 
@@ -100,7 +101,7 @@ cd hindsight-control-plane && npm run dev
 Main operations:
 - **Retain**: Store memories, extracts facts/entities/relationships
 - **Recall**: Retrieve memories via 4 parallel strategies (semantic, BM25, graph, temporal) + reranking
-- **Reflect**: Deep analysis with agentic reasoning loop (disposition-aware)
+- **Reflect**: Deep analysis forming new opinions/observations (disposition-aware)
 
 ### Database
 PostgreSQL with pgvector. Schema managed via Alembic migrations in `hindsight-api/hindsight_api/alembic/`. Migrations run automatically on API startup.

README.md

@@ -33,9 +33,8 @@ Most agent memory implementation rely on basic vector search or sometimes use a
 
 - **World:** Facts about the world ("The stove gets hot")
 - **Experiences:** Agent's own experiences ("I touched the stove and it really hurt")
-- **Mental Models:** Structured knowledge containers derived by reflecting on facts and experiences ("Curling irons, ovens, and fire are also hot. I shouldn't touch those either.")
-
-Mental models are evidence-grounded—every observation links back to the exact quotes from memories that support it.
+- **Opinion:** Beliefs with confidence scores ("I shouldn't touch the stove again" - .99 confidence)
+- **Observation:** Complex mental models derived by reflecting on facts and experiences ("Curling irons, ovens, and fire are also hot. I shouldn't touch those either.")
 
 Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
 
@@ -209,7 +208,7 @@ The final output is trimmed as needed to fit within the token limit.
 
 ### Reflect
 
-The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as mental models. When building agents, the reflect operation is a key capability to enable the agent to learn from its experiences. 
+The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as opinions and/or observations. When building agents, the reflect operation is a key capability to enable the agent to learn from its experiences. 
 
 For example, the `reflect` operation can be used to support use cases such as:
 

helm/hindsight/templates/_helpers.tpl

@@ -80,6 +80,22 @@ Control plane selector labels
 app.kubernetes.io/component: control-plane
 {{- end }}
 
+{{/*
+Worker labels
+*/}}
+{{- define "hindsight.worker.labels" -}}
+{{ include "hindsight.labels" . }}
+app.kubernetes.io/component: worker
+{{- end }}
+
+{{/*
+Worker selector labels
+*/}}
+{{- define "hindsight.worker.selectorLabels" -}}
+{{ include "hindsight.selectorLabels" . }}
+app.kubernetes.io/component: worker
+{{- end }}
+
 {{/*
 Create the name of the service account to use
 */}}

helm/hindsight/templates/api-deployment.yaml

@@ -55,6 +55,11 @@ spec:
         {{- end }}
         - name: HINDSIGHT_API_DATABASE_URL
           value: {{ include "hindsight.databaseUrl" . | quote }}
+        {{- /* Disable internal worker when dedicated workers are enabled */}}
+        {{- if .Values.worker.enabled }}
+        - name: HINDSIGHT_API_WORKER_ENABLED
+          value: "false"
+        {{- end }}
         {{- range $key, $value := .Values.api.env }}
         - name: {{ $key }}
           value: {{ $value | quote }}

helm/hindsight/templates/worker-service.yaml

@@ -0,0 +1,25 @@
+{{- if .Values.worker.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "hindsight.fullname" . }}-worker
+  labels:
+    {{- include "hindsight.worker.labels" . | nindent 4 }}
+  {{- if .Values.podAnnotations }}
+  annotations:
+    {{- /* Common Prometheus annotations for metrics scraping */}}
+    prometheus.io/scrape: "true"
+    prometheus.io/port: {{ .Values.worker.service.port | quote }}
+    prometheus.io/path: "/metrics"
+  {{- end }}
+spec:
+  # Headless service for StatefulSet (enables stable DNS names like worker-0.worker.namespace)
+  clusterIP: None
+  ports:
+  - port: {{ .Values.worker.service.port }}
+    targetPort: {{ .Values.worker.service.targetPort }}
+    protocol: TCP
+    name: http
+  selector:
+    {{- include "hindsight.worker.selectorLabels" . | nindent 4 }}
+{{- end }}

helm/hindsight/templates/worker-statefulset.yaml

@@ -0,0 +1,110 @@
+{{- if .Values.worker.enabled }}
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: {{ include "hindsight.fullname" . }}-worker
+  labels:
+    {{- include "hindsight.worker.labels" . | nindent 4 }}
+spec:
+  serviceName: {{ include "hindsight.fullname" . }}-worker
+  replicas: {{ .Values.worker.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.worker.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        {{- if not .Values.existingSecret }}
+        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
+        {{- end }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      labels:
+        {{- include "hindsight.worker.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- if .Values.serviceAccount.create }}
+      serviceAccountName: {{ include "hindsight.serviceAccountName" . }}
+      {{- end }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+      - name: worker
+        securityContext:
+          {{- toYaml .Values.securityContext | nindent 10 }}
+        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version }}"
+        imagePullPolicy: {{ .Values.worker.image.pullPolicy }}
+        command: ["hindsight-worker"]
+        ports:
+        - name: http
+          containerPort: {{ .Values.worker.service.targetPort }}
+          protocol: TCP
+        {{- if .Values.existingSecret }}
+        envFrom:
+        - secretRef:
+            name: {{ .Values.existingSecret }}
+        {{- end }}
+        env:
+        {{- /* POSTGRES_PASSWORD must be defined before DATABASE_URL for $(VAR) interpolation */}}
+        {{- if not .Values.postgresql.enabled }}
+        - name: POSTGRES_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: {{ include "hindsight.secretName" . }}
+              key: postgres-password
+        {{- end }}
+        - name: HINDSIGHT_API_DATABASE_URL
+          value: {{ include "hindsight.databaseUrl" . | quote }}
+        {{- /* Worker ID uses pod name (StatefulSet provides stable names like worker-0, worker-1) */}}
+        - name: HINDSIGHT_API_WORKER_ID
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
+        {{- /* Inherit LLM config from api.env */}}
+        {{- range $key, $value := .Values.api.env }}
+        - name: {{ $key }}
+          value: {{ $value | quote }}
+        {{- end }}
+        {{- /* Worker-specific env vars */}}
+        {{- range $key, $value := .Values.worker.env }}
+        - name: {{ $key }}
+          value: {{ $value | quote }}
+        {{- end }}
+        {{- /* Only use secrets when not using existingSecret */}}
+        {{- if not .Values.existingSecret }}
+        {{- /* Inherit secrets from api.secrets */}}
+        {{- range $key, $value := .Values.api.secrets }}
+        - name: {{ $key }}
+          valueFrom:
+            secretKeyRef:
+              name: {{ include "hindsight.secretName" $ }}
+              key: {{ $key }}
+        {{- end }}
+        {{- /* Worker-specific secrets (can override api.secrets) */}}
+        {{- range $key, $value := .Values.worker.secrets }}
+        - name: {{ $key }}
+          valueFrom:
+            secretKeyRef:
+              name: {{ include "hindsight.secretName" $ }}
+              key: {{ $key }}
+        {{- end }}
+        {{- end }}
+        livenessProbe:
+          {{- toYaml .Values.worker.livenessProbe | nindent 10 }}
+        readinessProbe:
+          {{- toYaml .Values.worker.readinessProbe | nindent 10 }}
+        resources:
+          {{- toYaml .Values.worker.resources | nindent 10 }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+{{- end }}

helm/hindsight/values.yaml

@@ -67,6 +67,63 @@ api:
     # HINDSIGHT_API_LLM_API_KEY: "your-api-key"
     # HINDSIGHT_API_LLM_BASE_URL: "https://api.groq.com/openai/v1"
 
+# Worker settings (distributed task processing)
+# When enabled, dedicated worker pods process tasks and the API's internal worker is disabled
+worker:
+  enabled: false
+  replicaCount: 2
+  image:
+    repository: ghcr.io/vectorize-io/hindsight-api
+    pullPolicy: IfNotPresent
+    # tag defaults to .Values.version if not specified
+
+  service:
+    # Service for metrics scraping (headless for StatefulSet)
+    port: 8889
+    targetPort: 8889
+
+  # Resource limits and requests
+  resources:
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+    requests:
+      cpu: 500m
+      memory: 1Gi
+
+  # Liveness and readiness probes
+  livenessProbe:
+    httpGet:
+      path: /health
+      port: 8889
+    initialDelaySeconds: 30
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 3
+
+  readinessProbe:
+    httpGet:
+      path: /health
+      port: 8889
+    initialDelaySeconds: 10
+    periodSeconds: 5
+    timeoutSeconds: 3
+    failureThreshold: 3
+
+  # Worker-specific environment variables
+  env:
+    # Poll interval in milliseconds (how often to check for new tasks)
+    HINDSIGHT_API_WORKER_POLL_INTERVAL_MS: "500"
+    # Number of tasks to claim per poll cycle
+    HINDSIGHT_API_WORKER_BATCH_SIZE: "10"
+    # Max retries before marking a task as failed
+    HINDSIGHT_API_WORKER_MAX_RETRIES: "3"
+    # HTTP port for metrics/health (matches service.targetPort)
+    HINDSIGHT_API_WORKER_HTTP_PORT: "8889"
+
+  # Secret environment variables (inherited from api.secrets if not specified)
+  secrets: {}
+
 # Image settings for control plane
 controlPlane:
   enabled: true

hindsight-api/README.md

@@ -2,7 +2,7 @@
 
 **Memory System for AI Agents** — Temporal + Semantic + Entity Memory Architecture using PostgreSQL with pgvector.
 
-Hindsight gives AI agents persistent memory that works like human memory: it stores facts, tracks entities and relationships, handles temporal reasoning ("what happened last spring?"), and builds mental models based on configurable disposition traits.
+Hindsight gives AI agents persistent memory that works like human memory: it stores facts, tracks entities and relationships, handles temporal reasoning ("what happened last spring?"), and forms opinions based on configurable disposition traits.
 
 ## Installation
 
@@ -120,8 +120,8 @@ This runs a stdio-based MCP server that can be used directly with MCP-compatible
 - **Multi-Strategy Retrieval (TEMPR)** — Semantic, keyword, graph, and temporal search combined with RRF fusion
 - **Entity Graph** — Automatic entity extraction and relationship tracking
 - **Temporal Reasoning** — Native support for time-based queries
-- **Disposition Traits** — Configurable skepticism, literalism, and empathy influence reasoning
-- **Two Memory Types** — World facts and experience facts with mental models for higher-level understanding
+- **Disposition Traits** — Configurable skepticism, literalism, and empathy influence opinion formation
+- **Three Memory Types** — World facts, bank actions, and formed opinions with confidence scores
 
 ## Documentation
 

hindsight-api/hindsight_api/admin/cli.py

@@ -244,6 +244,65 @@ def run_db_migration(
     typer.echo("Database migrations completed successfully")
 
 
+async def _decommission_worker(db_url: str, worker_id: str, schema: str = "public") -> int:
+    """Release all tasks owned by a worker, setting them back to pending status."""
+    is_pg0, instance_name, _ = parse_pg0_url(db_url)
+    if is_pg0:
+        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
+    resolved_url = await resolve_database_url(db_url)
+
+    conn = await asyncpg.connect(resolved_url)
+    try:
+        table = _fq_table("async_operations", schema)
+        result = await conn.fetch(
+            f"""
+            UPDATE {table}
+            SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
+            WHERE worker_id = $1 AND status = 'processing'
+            RETURNING operation_id
+            """,
+            worker_id,
+        )
+        return len(result)
+    finally:
+        await conn.close()
+
+
+@app.command(name="decommission-worker")
+def decommission_worker(
+    worker_id: str = typer.Argument(..., help="Worker ID to decommission"),
+    schema: str = typer.Option("public", "--schema", "-s", help="Database schema"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Release all tasks owned by a worker (sets status back to pending).
+
+    Use this command when a worker has crashed or been removed without graceful shutdown.
+    All tasks that were being processed by the worker will be released back to the queue
+    so other workers can pick them up.
+    """
+    config = HindsightConfig.from_env()
+
+    if not config.database_url:
+        typer.echo("Error: Database URL not configured.", err=True)
+        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
+        raise typer.Exit(1)
+
+    if not yes:
+        typer.confirm(
+            f"This will release all tasks owned by worker '{worker_id}' back to pending. Continue?",
+            abort=True,
+        )
+
+    typer.echo(f"Decommissioning worker '{worker_id}' (schema: {schema})...")
+
+    count = asyncio.run(_decommission_worker(config.database_url, worker_id, schema))
+
+    if count > 0:
+        typer.echo(f"Released {count} task(s) from worker '{worker_id}'")
+    else:
+        typer.echo(f"No tasks found for worker '{worker_id}'")
+
+
 def main():
     app()
 

hindsight-api/hindsight_api/alembic/versions/l7g8h9i0j1k2_add_worker_columns.py

@@ -0,0 +1,109 @@
+"""add_worker_columns
+
+Revision ID: l7g8h9i0j1k2
+Revises: k6f7g8h9i0j1
+Create Date: 2026-01-19 00:00:00.000000
+
+This migration adds columns to async_operations for distributed worker support:
+- worker_id: ID of the worker that claimed the task
+- claimed_at: When the task was claimed
+- retry_count: Number of retry attempts
+- task_payload: The serialized task dictionary
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import context, op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "l7g8h9i0j1k2"
+down_revision: str | Sequence[str] | None = "k6f7g8h9i0j1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _get_schema_prefix() -> str:
+    """Get schema prefix for table names (required for multi-tenant support)."""
+    schema = context.config.get_main_option("target_schema")
+    return f'"{schema}".' if schema else ""
+
+
+def upgrade() -> None:
+    """Add worker columns to async_operations."""
+    schema = _get_schema_prefix()
+
+    # Add worker_id column (ID of worker that claimed the task)
+    op.add_column(
+        "async_operations",
+        sa.Column("worker_id", sa.Text(), nullable=True),
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+
+    # Add claimed_at column (when task was claimed by worker)
+    op.add_column(
+        "async_operations",
+        sa.Column("claimed_at", postgresql.TIMESTAMP(timezone=True), nullable=True),
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+
+    # Add retry_count column (number of retry attempts)
+    op.add_column(
+        "async_operations",
+        sa.Column("retry_count", sa.Integer(), server_default="0", nullable=False),
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+
+    # Add task_payload column (serialized task dictionary)
+    op.add_column(
+        "async_operations",
+        sa.Column(
+            "task_payload",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=True,
+        ),
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+
+    # Add index for efficient worker polling (pending tasks ordered by creation time)
+    op.execute(
+        f"CREATE INDEX idx_async_operations_pending_claim ON {schema}async_operations (status, created_at) "
+        f"WHERE status = 'pending' AND task_payload IS NOT NULL"
+    )
+
+    # Add index for finding tasks by worker_id (for decommissioning)
+    op.execute(
+        f"CREATE INDEX idx_async_operations_worker_id ON {schema}async_operations (worker_id) WHERE worker_id IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    """Remove worker columns from async_operations."""
+    schema = _get_schema_prefix()
+
+    # Drop indexes
+    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_pending_claim")
+    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_worker_id")
+
+    # Drop columns
+    op.drop_column(
+        "async_operations",
+        "task_payload",
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+    op.drop_column(
+        "async_operations",
+        "retry_count",
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+    op.drop_column(
+        "async_operations",
+        "claimed_at",
+        schema=context.config.get_main_option("target_schema") or None,
+    )
+    op.drop_column(
+        "async_operations",
+        "worker_id",
+        schema=context.config.get_main_option("target_schema") or None,
+    )

hindsight-api/hindsight_api/api/http.py

@@ -1408,6 +1408,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")
@@ -1430,6 +1440,20 @@ 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,
+            )
+            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()
@@ -1437,6 +1461,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()

hindsight-api/hindsight_api/config.py

@@ -106,10 +106,13 @@ ENV_DB_POOL_MAX_SIZE = "HINDSIGHT_API_DB_POOL_MAX_SIZE"
 ENV_DB_COMMAND_TIMEOUT = "HINDSIGHT_API_DB_COMMAND_TIMEOUT"
 ENV_DB_ACQUIRE_TIMEOUT = "HINDSIGHT_API_DB_ACQUIRE_TIMEOUT"
 
-# Background task processing
-ENV_TASK_BACKEND = "HINDSIGHT_API_TASK_BACKEND"
-ENV_TASK_BACKEND_MEMORY_BATCH_SIZE = "HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_SIZE"
-ENV_TASK_BACKEND_MEMORY_BATCH_INTERVAL = "HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_INTERVAL"
+# Worker configuration (distributed task processing)
+ENV_WORKER_ENABLED = "HINDSIGHT_API_WORKER_ENABLED"
+ENV_WORKER_ID = "HINDSIGHT_API_WORKER_ID"
+ENV_WORKER_POLL_INTERVAL_MS = "HINDSIGHT_API_WORKER_POLL_INTERVAL_MS"
+ENV_WORKER_MAX_RETRIES = "HINDSIGHT_API_WORKER_MAX_RETRIES"
+ENV_WORKER_BATCH_SIZE = "HINDSIGHT_API_WORKER_BATCH_SIZE"
+ENV_WORKER_HTTP_PORT = "HINDSIGHT_API_WORKER_HTTP_PORT"
 
 # Reflect agent settings
 ENV_REFLECT_MAX_ITERATIONS = "HINDSIGHT_API_REFLECT_MAX_ITERATIONS"
@@ -177,10 +180,13 @@ DEFAULT_DB_POOL_MAX_SIZE = 100
 DEFAULT_DB_COMMAND_TIMEOUT = 60  # seconds
 DEFAULT_DB_ACQUIRE_TIMEOUT = 30  # seconds
 
-# Background task processing
-DEFAULT_TASK_BACKEND = "memory"  # Options: "memory", "noop"
-DEFAULT_TASK_BACKEND_MEMORY_BATCH_SIZE = 10
-DEFAULT_TASK_BACKEND_MEMORY_BATCH_INTERVAL = 1.0  # seconds
+# Worker configuration (distributed task processing)
+DEFAULT_WORKER_ENABLED = True  # API runs worker by default (standalone mode)
+DEFAULT_WORKER_ID = None  # Will use hostname if not specified
+DEFAULT_WORKER_POLL_INTERVAL_MS = 500  # Poll database every 500ms
+DEFAULT_WORKER_MAX_RETRIES = 3  # Max retries before marking task failed
+DEFAULT_WORKER_BATCH_SIZE = 10  # Tasks to claim per poll cycle
+DEFAULT_WORKER_HTTP_PORT = 8889  # HTTP port for worker metrics/health
 
 # Reflect agent settings
 DEFAULT_REFLECT_MAX_ITERATIONS = 10  # Max tool call iterations before forcing response
@@ -331,10 +337,13 @@ class HindsightConfig:
     db_command_timeout: int
     db_acquire_timeout: int
 
-    # Background task processing
-    task_backend: str
-    task_backend_memory_batch_size: int
-    task_backend_memory_batch_interval: float
+    # Worker configuration (distributed task processing)
+    worker_enabled: bool
+    worker_id: str | None
+    worker_poll_interval_ms: int
+    worker_max_retries: int
+    worker_batch_size: int
+    worker_http_port: int
 
     # Reflect agent settings
     reflect_max_iterations: int
@@ -424,14 +433,13 @@ class HindsightConfig:
             db_pool_max_size=int(os.getenv(ENV_DB_POOL_MAX_SIZE, str(DEFAULT_DB_POOL_MAX_SIZE))),
             db_command_timeout=int(os.getenv(ENV_DB_COMMAND_TIMEOUT, str(DEFAULT_DB_COMMAND_TIMEOUT))),
             db_acquire_timeout=int(os.getenv(ENV_DB_ACQUIRE_TIMEOUT, str(DEFAULT_DB_ACQUIRE_TIMEOUT))),
-            # Background task processing
-            task_backend=os.getenv(ENV_TASK_BACKEND, DEFAULT_TASK_BACKEND),
-            task_backend_memory_batch_size=int(
-                os.getenv(ENV_TASK_BACKEND_MEMORY_BATCH_SIZE, str(DEFAULT_TASK_BACKEND_MEMORY_BATCH_SIZE))
-            ),
-            task_backend_memory_batch_interval=float(
-                os.getenv(ENV_TASK_BACKEND_MEMORY_BATCH_INTERVAL, str(DEFAULT_TASK_BACKEND_MEMORY_BATCH_INTERVAL))
-            ),
+            # Worker configuration
+            worker_enabled=os.getenv(ENV_WORKER_ENABLED, str(DEFAULT_WORKER_ENABLED)).lower() == "true",
+            worker_id=os.getenv(ENV_WORKER_ID) or DEFAULT_WORKER_ID,
+            worker_poll_interval_ms=int(os.getenv(ENV_WORKER_POLL_INTERVAL_MS, str(DEFAULT_WORKER_POLL_INTERVAL_MS))),
+            worker_max_retries=int(os.getenv(ENV_WORKER_MAX_RETRIES, str(DEFAULT_WORKER_MAX_RETRIES))),
+            worker_batch_size=int(os.getenv(ENV_WORKER_BATCH_SIZE, str(DEFAULT_WORKER_BATCH_SIZE))),
+            worker_http_port=int(os.getenv(ENV_WORKER_HTTP_PORT, str(DEFAULT_WORKER_HTTP_PORT))),
             # Reflect agent settings
             reflect_max_iterations=int(os.getenv(ENV_REFLECT_MAX_ITERATIONS, str(DEFAULT_REFLECT_MAX_ITERATIONS))),
         )

hindsight-api/hindsight_api/engine/memory_engine.py

@@ -159,7 +159,7 @@ from .retain.types import RetainContentDict
 from .search import think_utils
 from .search.reranking import CrossEncoderReranker
 from .search.tags import TagsMatch
-from .task_backend import AsyncIOQueueBackend, NoopTaskBackend, TaskBackend
+from .task_backend import BrokerTaskBackend, SyncTaskBackend, TaskBackend
 
 
 class Budget(str, Enum):
@@ -229,8 +229,6 @@ class MemoryEngine(MemoryEngineInterface):
         db_command_timeout: int | None = None,
         db_acquire_timeout: int | None = None,
         task_backend: TaskBackend | None = None,
-        task_batch_size: int | None = None,
-        task_batch_interval: float | None = None,
         run_migrations: bool = True,
         operation_validator: "OperationValidatorExtension | None" = None,
         tenant_extension: "TenantExtension | None" = None,
@@ -265,9 +263,7 @@ class MemoryEngine(MemoryEngineInterface):
             pool_max_size: Maximum number of connections in the pool. Defaults to HINDSIGHT_API_DB_POOL_MAX_SIZE.
             db_command_timeout: PostgreSQL command timeout in seconds. Defaults to HINDSIGHT_API_DB_COMMAND_TIMEOUT.
             db_acquire_timeout: Connection acquisition timeout in seconds. Defaults to HINDSIGHT_API_DB_ACQUIRE_TIMEOUT.
-            task_backend: Custom task backend. If not provided, uses AsyncIOQueueBackend.
-            task_batch_size: Background task batch size. Defaults to HINDSIGHT_API_TASK_BATCH_SIZE.
-            task_batch_interval: Background task batch interval in seconds. Defaults to HINDSIGHT_API_TASK_BATCH_INTERVAL.
+            task_backend: Custom task backend. If not provided, uses BrokerTaskBackend for distributed processing.
             run_migrations: Whether to run database migrations during initialize(). Default: True
             operation_validator: Optional extension to validate operations before execution.
                                 If provided, retain/recall/reflect operations will be validated.
@@ -405,13 +401,9 @@ class MemoryEngine(MemoryEngineInterface):
         self._cross_encoder_reranker = CrossEncoderReranker(cross_encoder=cross_encoder)
 
         # Initialize task backend
-        _task_batch_size = task_batch_size if task_batch_size is not None else config.task_backend_memory_batch_size
-        _task_batch_interval = (
-            task_batch_interval if task_batch_interval is not None else config.task_backend_memory_batch_interval
-        )
-        self._task_backend = task_backend or AsyncIOQueueBackend(
-            batch_size=_task_batch_size, batch_interval=_task_batch_interval
-        )
+        # If no custom backend provided, use BrokerTaskBackend which stores tasks in PostgreSQL
+        # The pool_getter lambda will return the pool once it's initialized
+        self._task_backend = task_backend or BrokerTaskBackend(pool_getter=lambda: self._pool)
 
         # Backpressure mechanism: limit concurrent searches to prevent overwhelming the database
         # Configurable via HINDSIGHT_API_RECALL_MAX_CONCURRENT (default: 50)

hindsight-api/hindsight_api/engine/task_backend.py

@@ -1,31 +1,40 @@
 """
-Abstract task backend for running async tasks.
+Task backend for distributed task processing.
 
-This provides an abstraction that can be adapted to different execution models:
-- AsyncIO queue (default implementation)
-- Pub/Sub architectures (future)
-- Message brokers (future)
+This provides an abstraction for task storage and execution:
+- BrokerTaskBackend: Uses PostgreSQL as broker (production)
+- SyncTaskBackend: Executes tasks immediately (testing/embedded)
 """
 
-import asyncio
+import json
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import asyncpg
 
 logger = logging.getLogger(__name__)
 
 
+def fq_table(table: str, schema: str | None = None) -> str:
+    """Get fully-qualified table name with optional schema prefix."""
+    if schema:
+        return f'"{schema}".{table}'
+    return table
+
+
 class TaskBackend(ABC):
     """
     Abstract base class for task execution backends.
 
     Implementations must:
     1. Store/publish task events (as serializable dicts)
-    2. Execute tasks through a provided executor callback
+    2. Execute tasks through a provided executor callback (optional)
 
     The backend treats tasks as pure dictionaries that can be serialized
-    and sent over the network. The executor (typically MemoryEngine.execute_task)
+    and stored in the database. The executor (typically MemoryEngine.execute_task)
     receives the dict and routes it to the appropriate handler.
     """
 
@@ -46,7 +55,7 @@ class TaskBackend(ABC):
     @abstractmethod
     async def initialize(self):
         """
-        Initialize the backend (e.g., start workers, connect to broker).
+        Initialize the backend (e.g., connect to database).
         """
         pass
 
@@ -63,7 +72,7 @@ class TaskBackend(ABC):
     @abstractmethod
     async def shutdown(self):
         """
-        Shutdown the backend gracefully (e.g., stop workers, close connections).
+        Shutdown the backend gracefully.
         """
         pass
 
@@ -93,9 +102,8 @@ class SyncTaskBackend(TaskBackend):
     """
     Synchronous task backend that executes tasks immediately.
 
-    This is useful for embedded/CLI usage where we don't want background
-    workers that prevent clean exit. Tasks are executed inline rather than
-    being queued.
+    This is useful for tests and embedded/CLI usage where we don't want
+    background workers. Tasks are executed inline rather than being queued.
     """
 
     async def initialize(self):
@@ -121,221 +129,123 @@ class SyncTaskBackend(TaskBackend):
         logger.debug("SyncTaskBackend shutdown")
 
 
-class NoopTaskBackend(TaskBackend):
+class BrokerTaskBackend(TaskBackend):
     """
-    No-op task backend that discards all tasks.
+    Task backend using PostgreSQL as broker.
 
-    This is useful for tests where background task execution is not needed
-    and would only slow down the test suite.
+    submit_task() stores task_payload in async_operations table.
+    Actual polling and execution is handled separately by WorkerPoller.
+
+    This backend is used by the API to store tasks. Workers poll
+    the database separately to claim and execute tasks.
     """
 
-    async def initialize(self):
-        """No-op."""
-        self._initialized = True
-        logger.debug("NoopTaskBackend initialized")
-
-    async def submit_task(self, task_dict: dict[str, Any]):
-        """Discard the task (do nothing)."""
-        pass
-
-    async def shutdown(self):
-        """No-op."""
-        self._initialized = False
-        logger.debug("NoopTaskBackend shutdown")
-
-
-class AsyncIOQueueBackend(TaskBackend):
-    """
-    Task backend implementation using asyncio queues.
-
-    This is the default implementation that uses in-process asyncio queues
-    and a periodic consumer worker.
-    """
-
-    def __init__(self, batch_size: int = 10, batch_interval: float = 1.0):
+    def __init__(
+        self,
+        pool_getter: Callable[[], "asyncpg.Pool"],
+        schema: str | None = None,
+    ):
         """
-        Initialize AsyncIO queue backend.
+        Initialize the broker task backend.
 
         Args:
-            batch_size: Maximum number of tasks to process in one batch
-            batch_interval: Maximum time (seconds) to wait before processing batch
+            pool_getter: Callable that returns the asyncpg connection pool
+            schema: Database schema for multi-tenant support (optional)
         """
         super().__init__()
-        self._queue: asyncio.Queue | None = None
-        self._worker_task: asyncio.Task | None = None
-        self._shutdown_event: asyncio.Event | None = None
-        self._batch_size = batch_size
-        self._batch_interval = batch_interval
-        self._in_flight_count = 0
-        self._in_flight_lock = asyncio.Lock()
+        self._pool_getter = pool_getter
+        self._schema = schema
 
     async def initialize(self):
-        """Initialize the queue and start the worker."""
-        if self._initialized:
-            return
-
-        self._queue = asyncio.Queue()
-        self._shutdown_event = asyncio.Event()
-        self._worker_task = asyncio.create_task(self._worker())
+        """Initialize the backend."""
         self._initialized = True
-        logger.info("AsyncIOQueueBackend initialized")
+        logger.info("BrokerTaskBackend initialized")
 
     async def submit_task(self, task_dict: dict[str, Any]):
         """
-        Submit a task by putting it in the queue.
+        Store task payload in async_operations table.
+
+        The task_dict should contain an 'operation_id' if updating an existing
+        operation record, otherwise a new operation will be created.
 
         Args:
-            task_dict: Task dictionary to execute
+            task_dict: Task dictionary to store (must be JSON serializable)
         """
         if not self._initialized:
             await self.initialize()
 
-        await self._queue.put(task_dict)
+        pool = self._pool_getter()
+        operation_id = task_dict.get("operation_id")
+        task_type = task_dict.get("type", "unknown")
+        bank_id = task_dict.get("bank_id")
+        payload_json = json.dumps(task_dict)
+
+        table = fq_table("async_operations", self._schema)
+
+        if operation_id:
+            # Update existing operation with task payload
+            await pool.execute(
+                f"""
+                UPDATE {table}
+                SET task_payload = $1::jsonb, updated_at = now()
+                WHERE operation_id = $2
+                """,
+                payload_json,
+                operation_id,
+            )
+            logger.debug(f"Updated task payload for operation {operation_id}")
+        else:
+            # Insert new operation (for tasks without pre-created records)
+            # e.g., access_count_update tasks
+            import uuid
+
+            new_id = uuid.uuid4()
+            await pool.execute(
+                f"""
+                INSERT INTO {table} (operation_id, bank_id, operation_type, status, task_payload)
+                VALUES ($1, $2, $3, 'pending', $4::jsonb)
+                """,
+                new_id,
+                bank_id,
+                task_type,
+                payload_json,
+            )
+            logger.debug(f"Created new operation {new_id} for task type {task_type}")
+
+    async def shutdown(self):
+        """Shutdown the backend."""
+        self._initialized = False
+        logger.info("BrokerTaskBackend shutdown")
 
     async def wait_for_pending_tasks(self, timeout: float = 120.0):
         """
-        Wait for all pending tasks in the queue and in-flight tasks to complete.
+        Wait for pending tasks to be processed.
 
-        This is useful in tests to ensure background tasks complete before assertions.
+        In the broker model, this polls the database to check if tasks
+        for this process have been completed. This is useful in tests
+        when worker_enabled=True (API processes its own tasks).
 
         Args:
-            timeout: Maximum time to wait in seconds (default 120s for long-running tasks)
+            timeout: Maximum time to wait in seconds
         """
-        if not self._initialized or self._queue is None:
-            return
+        import asyncio
+
+        pool = self._pool_getter()
+        table = fq_table("async_operations", self._schema)
 
-        # Wait for queue to be empty AND no in-flight tasks
         start_time = asyncio.get_event_loop().time()
         while asyncio.get_event_loop().time() - start_time < timeout:
-            async with self._in_flight_lock:
-                in_flight = self._in_flight_count
+            # Check if there are any pending tasks with payloads
+            count = await pool.fetchval(
+                f"""
+                SELECT COUNT(*) FROM {table}
+                WHERE status = 'pending' AND task_payload IS NOT NULL
+                """
+            )
 
-            if self._queue.empty() and in_flight == 0:
-                # Queue is empty and no tasks in flight, we're done
+            if count == 0:
                 return
 
-            # Wait a bit before checking again
             await asyncio.sleep(0.5)
 
-    async def shutdown(self):
-        """Shutdown the worker and drain the queue."""
-        if not self._initialized:
-            return
-
-        logger.info("Shutting down AsyncIOQueueBackend...")
-
-        # Signal shutdown
-        self._shutdown_event.set()
-
-        # Cancel worker
-        if self._worker_task is not None:
-            self._worker_task.cancel()
-            try:
-                await self._worker_task
-            except asyncio.CancelledError:
-                pass  # Worker cancelled successfully
-
-        self._initialized = False
-        logger.info("AsyncIOQueueBackend shutdown complete")
-
-    async def _execute_task_with_tracking(self, task_dict: dict[str, Any]):
-        """Execute a task and track its in-flight status."""
-        async with self._in_flight_lock:
-            self._in_flight_count += 1
-        try:
-            await self._execute_task(task_dict)
-        finally:
-            async with self._in_flight_lock:
-                self._in_flight_count -= 1
-
-    async def _execute_task_no_tracking(self, task_dict: dict[str, Any]):
-        """Execute a task without in-flight tracking (tracking done at batch level)."""
-        await self._execute_task(task_dict)
-
-    def _get_queue_stats(self) -> tuple[int, dict[str, int]]:
-        """Get current queue size and bank_id distribution."""
-        queue_size = self._queue.qsize() if self._queue else 0
-        bank_distribution: dict[str, int] = {}
-
-        if queue_size > 0 and self._queue:
-            # Peek at queue items without removing them
-            # Note: This is a snapshot and may not be perfectly accurate due to concurrency
-            try:
-                # Access internal deque for logging purposes only
-                items = list(self._queue._queue)  # type: ignore[attr-defined]
-                for item in items:
-                    bank_id = item.get("bank_id", "unknown")
-                    bank_distribution[bank_id] = bank_distribution.get(bank_id, 0) + 1
-            except Exception:
-                pass  # Queue access failed, return empty distribution
-
-        return queue_size, bank_distribution
-
-    async def _worker(self):
-        """
-        Background worker that processes tasks in batches.
-
-        Collects tasks for up to batch_interval seconds or batch_size items,
-        then processes them.
-        """
-        while not self._shutdown_event.is_set():
-            try:
-                # Collect tasks for batching
-                tasks = []
-                deadline = asyncio.get_event_loop().time() + self._batch_interval
-
-                while len(tasks) < self._batch_size and asyncio.get_event_loop().time() < deadline:
-                    try:
-                        remaining_time = max(0.1, deadline - asyncio.get_event_loop().time())
-                        task_dict = await asyncio.wait_for(self._queue.get(), timeout=remaining_time)
-                        # Track task as in-flight immediately when picked up from queue
-                        # This prevents wait_for_pending_tasks from returning too early
-                        async with self._in_flight_lock:
-                            self._in_flight_count += 1
-                        tasks.append(task_dict)
-                    except TimeoutError:
-                        break
-
-                # Process batch
-                if tasks:
-                    # Log batch start with queue stats
-                    queue_size, bank_distribution = self._get_queue_stats()
-
-                    # Summarize batch by task type and bank
-                    batch_summary: dict[str, dict[str, int]] = {}
-                    for task_dict in tasks:
-                        task_type = task_dict.get("type", "unknown")
-                        bank_id = task_dict.get("bank_id", "unknown")
-                        if task_type not in batch_summary:
-                            batch_summary[task_type] = {}
-                        batch_summary[task_type][bank_id] = batch_summary[task_type].get(bank_id, 0) + 1
-
-                    # Build log message
-                    batch_parts = []
-                    for task_type, banks in sorted(batch_summary.items()):
-                        bank_str = ", ".join(f"{b}:{c}" for b, c in sorted(banks.items()))
-                        batch_parts.append(f"{task_type}[{bank_str}]")
-                    batch_str = ", ".join(batch_parts)
-
-                    if queue_size > 0:
-                        pending_str = ", ".join(f"{k}:{v}" for k, v in sorted(bank_distribution.items()))
-                        logger.info(
-                            f"Processing {len(tasks)} tasks: {batch_str} (pending={queue_size} [{pending_str}])"
-                        )
-                    else:
-                        logger.info(f"Processing {len(tasks)} tasks: {batch_str}")
-
-                    # Execute tasks concurrently (in_flight already tracked when picked up)
-                    await asyncio.gather(
-                        *[self._execute_task_no_tracking(task_dict) for task_dict in tasks], return_exceptions=True
-                    )
-
-                    # Decrement in_flight count after all tasks complete
-                    async with self._in_flight_lock:
-                        self._in_flight_count -= len(tasks)
-
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"Worker error: {e}")
-                await asyncio.sleep(1)  # Backoff on error
+        logger.warning(f"Timeout waiting for pending tasks after {timeout}s")

hindsight-api/hindsight_api/main.py

@@ -219,9 +219,12 @@ def main():
             db_pool_max_size=config.db_pool_max_size,
             db_command_timeout=config.db_command_timeout,
             db_acquire_timeout=config.db_acquire_timeout,
-            task_backend=config.task_backend,
-            task_backend_memory_batch_size=config.task_backend_memory_batch_size,
-            task_backend_memory_batch_interval=config.task_backend_memory_batch_interval,
+            worker_enabled=config.worker_enabled,
+            worker_id=config.worker_id,
+            worker_poll_interval_ms=config.worker_poll_interval_ms,
+            worker_max_retries=config.worker_max_retries,
+            worker_batch_size=config.worker_batch_size,
+            worker_http_port=config.worker_http_port,
             reflect_max_iterations=config.reflect_max_iterations,
             mental_model_refresh_concurrency=config.mental_model_refresh_concurrency,
         )

hindsight-api/hindsight_api/worker/__init__.py

@@ -0,0 +1,11 @@
+"""
+Worker package for distributed task processing.
+
+This package provides:
+- WorkerPoller: Polls PostgreSQL for pending tasks and executes them
+- main: CLI entry point for hindsight-worker
+"""
+
+from .poller import WorkerPoller
+
+__all__ = ["WorkerPoller"]

hindsight-api/hindsight_api/worker/main.py

@@ -0,0 +1,285 @@
+"""
+Command-line interface for Hindsight Worker.
+
+Run the worker with:
+    hindsight-worker
+
+Stop with Ctrl+C (graceful shutdown).
+"""
+
+import argparse
+import asyncio
+import atexit
+import logging
+import os
+import signal
+import socket
+import sys
+import warnings
+
+from ..config import get_config
+from ..engine.task_backend import SyncTaskBackend
+from .poller import WorkerPoller
+
+# Filter deprecation warnings from third-party libraries
+warnings.filterwarnings("ignore", message="websockets.legacy is deprecated")
+warnings.filterwarnings("ignore", message="websockets.server.WebSocketServerProtocol is deprecated")
+
+# Disable tokenizers parallelism to avoid warnings
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+logger = logging.getLogger(__name__)
+
+
+def create_worker_app(poller: WorkerPoller, memory):
+    """Create a minimal FastAPI app for worker metrics and health."""
+    from fastapi import FastAPI
+    from fastapi.responses import JSONResponse, Response
+    from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+
+    from ..metrics import create_metrics_collector, get_metrics_collector, initialize_metrics
+
+    app = FastAPI(
+        title="Hindsight Worker",
+        description="Worker process for distributed task execution",
+    )
+
+    # Initialize OpenTelemetry metrics
+    try:
+        prometheus_reader = initialize_metrics(service_name="hindsight-worker", service_version="1.0.0")
+        create_metrics_collector()
+        app.state.prometheus_reader = prometheus_reader
+        logger.info("Metrics initialized - available at /metrics endpoint")
+    except Exception as e:
+        logger.warning(f"Failed to initialize metrics: {e}. Metrics will be disabled.")
+        app.state.prometheus_reader = None
+
+    # Set up DB pool metrics if available
+    metrics_collector = get_metrics_collector()
+    if memory._pool is not None and hasattr(metrics_collector, "set_db_pool"):
+        metrics_collector.set_db_pool(memory._pool)
+        logger.info("DB pool metrics configured")
+
+    @app.get(
+        "/health",
+        summary="Health check endpoint",
+        description="Returns worker health status including database connectivity",
+        tags=["Monitoring"],
+    )
+    async def health_endpoint():
+        """Health check endpoint."""
+        health = await memory.health_check()
+        health["worker_id"] = poller.worker_id
+        health["is_shutdown"] = poller.is_shutdown
+        status_code = 200 if health.get("status") == "healthy" else 503
+        return JSONResponse(content=health, status_code=status_code)
+
+    @app.get(
+        "/metrics",
+        summary="Prometheus metrics endpoint",
+        description="Exports metrics in Prometheus format for scraping",
+        tags=["Monitoring"],
+    )
+    async def metrics_endpoint():
+        """Return Prometheus metrics."""
+        metrics_data = generate_latest()
+        return Response(content=metrics_data, media_type=CONTENT_TYPE_LATEST)
+
+    @app.get(
+        "/",
+        summary="Worker info",
+        description="Basic worker information",
+        tags=["Info"],
+    )
+    async def root():
+        """Return basic worker info."""
+        return {
+            "service": "hindsight-worker",
+            "worker_id": poller.worker_id,
+            "is_shutdown": poller.is_shutdown,
+        }
+
+    return app
+
+
+def main():
+    """Main entry point for the hindsight-worker CLI."""
+    # Load configuration from environment
+    config = get_config()
+
+    parser = argparse.ArgumentParser(
+        prog="hindsight-worker",
+        description="Hindsight Worker - distributed task processor",
+    )
+
+    # Worker options
+    parser.add_argument(
+        "--worker-id",
+        default=config.worker_id or socket.gethostname(),
+        help="Worker identifier (default: hostname, env: HINDSIGHT_API_WORKER_ID)",
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=int,
+        default=config.worker_poll_interval_ms,
+        help=f"Poll interval in milliseconds (default: {config.worker_poll_interval_ms}, env: HINDSIGHT_API_WORKER_POLL_INTERVAL_MS)",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=config.worker_batch_size,
+        help=f"Tasks to claim per poll (default: {config.worker_batch_size}, env: HINDSIGHT_API_WORKER_BATCH_SIZE)",
+    )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=config.worker_max_retries,
+        help=f"Max retries before marking failed (default: {config.worker_max_retries}, env: HINDSIGHT_API_WORKER_MAX_RETRIES)",
+    )
+
+    # HTTP server options
+    parser.add_argument(
+        "--http-port",
+        type=int,
+        default=config.worker_http_port,
+        help=f"HTTP port for metrics/health endpoints (default: {config.worker_http_port}, env: HINDSIGHT_API_WORKER_HTTP_PORT)",
+    )
+    parser.add_argument(
+        "--http-host",
+        default="0.0.0.0",
+        help="HTTP host to bind (default: 0.0.0.0)",
+    )
+
+    # Logging options
+    parser.add_argument(
+        "--log-level",
+        default=config.log_level,
+        choices=["critical", "error", "warning", "info", "debug", "trace"],
+        help=f"Log level (default: {config.log_level}, env: HINDSIGHT_API_LOG_LEVEL)",
+    )
+
+    args = parser.parse_args()
+
+    # Configure logging
+    config.configure_logging()
+
+    # Import MemoryEngine here to avoid circular imports
+    from .. import MemoryEngine
+
+    print(f"Starting Hindsight Worker: {args.worker_id}")
+    print(f"  Poll interval: {args.poll_interval}ms")
+    print(f"  Batch size: {args.batch_size}")
+    print(f"  Max retries: {args.max_retries}")
+    print(f"  HTTP server: {args.http_host}:{args.http_port}")
+    print()
+
+    # Global references for cleanup
+    memory = None
+    poller = None
+
+    async def run():
+        nonlocal memory, poller
+        import uvicorn
+
+        # Initialize MemoryEngine
+        # Workers use SyncTaskBackend because they execute tasks directly,
+        # they don't need to store tasks (they poll from DB)
+        memory = MemoryEngine(
+            run_migrations=False,  # Workers don't run migrations
+            task_backend=SyncTaskBackend(),
+        )
+
+        await memory.initialize()
+
+        print(f"Database connected: {config.database_url}")
+
+        # Create and start the poller
+        poller = WorkerPoller(
+            pool=memory._pool,
+            worker_id=args.worker_id,
+            executor=memory.execute_task,
+            poll_interval_ms=args.poll_interval,
+            batch_size=args.batch_size,
+            max_retries=args.max_retries,
+        )
+
+        # Create the HTTP app for metrics/health
+        app = create_worker_app(poller, memory)
+
+        # Setup signal handlers for graceful shutdown
+        shutdown_requested = asyncio.Event()
+
+        def signal_handler(signum, frame):
+            print(f"\nReceived signal {signum}, initiating graceful shutdown...")
+            shutdown_requested.set()
+
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+
+        # Create uvicorn config and server
+        uvicorn_config = uvicorn.Config(
+            app,
+            host=args.http_host,
+            port=args.http_port,
+            log_level="info",  # Reduce uvicorn noise
+            access_log=False,
+        )
+        server = uvicorn.Server(uvicorn_config)
+
+        # Run the poller and HTTP server concurrently
+        poller_task = asyncio.create_task(poller.run())
+        http_task = asyncio.create_task(server.serve())
+
+        print(f"Worker started. Metrics available at http://{args.http_host}:{args.http_port}/metrics")
+
+        # Wait for shutdown signal
+        await shutdown_requested.wait()
+
+        # Graceful shutdown
+        print("Shutting down HTTP server...")
+        server.should_exit = True
+
+        print("Waiting for poller to finish...")
+        await poller.shutdown_graceful(timeout=30.0)
+        poller_task.cancel()
+        try:
+            await poller_task
+        except asyncio.CancelledError:
+            pass
+
+        # Wait for HTTP server to finish
+        try:
+            await asyncio.wait_for(http_task, timeout=5.0)
+        except asyncio.TimeoutError:
+            http_task.cancel()
+            try:
+                await http_task
+            except asyncio.CancelledError:
+                pass
+
+        # Close memory engine
+        await memory.close()
+        print("Worker shutdown complete")
+
+    def cleanup():
+        """Synchronous cleanup for atexit."""
+        if memory is not None and memory._pg0 is not None:
+            try:
+                loop = asyncio.new_event_loop()
+                loop.run_until_complete(memory._pg0.stop())
+                loop.close()
+                print("\npg0 stopped.")
+            except Exception as e:
+                print(f"\nError stopping pg0: {e}")
+
+    atexit.register(cleanup)
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        print("\nWorker interrupted")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

hindsight-api/hindsight_api/worker/poller.py

@@ -0,0 +1,281 @@
+"""
+Worker poller for distributed task execution.
+
+Polls PostgreSQL for pending tasks and executes them using
+FOR UPDATE SKIP LOCKED for safe concurrent claiming.
+"""
+
+import asyncio
+import json
+import logging
+import traceback
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import asyncpg
+
+logger = logging.getLogger(__name__)
+
+
+def fq_table(table: str, schema: str | None = None) -> str:
+    """Get fully-qualified table name with optional schema prefix."""
+    if schema:
+        return f'"{schema}".{table}'
+    return table
+
+
+class WorkerPoller:
+    """
+    Polls PostgreSQL for pending tasks and executes them.
+
+    Uses FOR UPDATE SKIP LOCKED for safe distributed claiming,
+    allowing multiple workers to process tasks without conflicts.
+    """
+
+    def __init__(
+        self,
+        pool: "asyncpg.Pool",
+        worker_id: str,
+        executor: Callable[[dict[str, Any]], Awaitable[None]],
+        poll_interval_ms: int = 500,
+        batch_size: int = 10,
+        max_retries: int = 3,
+        schema: str | None = None,
+    ):
+        """
+        Initialize the worker poller.
+
+        Args:
+            pool: asyncpg connection pool
+            worker_id: Unique identifier for this worker
+            executor: Async function to execute tasks (typically MemoryEngine.execute_task)
+            poll_interval_ms: Interval between polls when no tasks found (milliseconds)
+            batch_size: Maximum number of tasks to claim per poll cycle
+            max_retries: Maximum retry attempts before marking task as failed
+            schema: Database schema for multi-tenant support (optional)
+        """
+        self._pool = pool
+        self._worker_id = worker_id
+        self._executor = executor
+        self._poll_interval_ms = poll_interval_ms
+        self._batch_size = batch_size
+        self._max_retries = max_retries
+        self._schema = schema
+        self._shutdown = asyncio.Event()
+        self._current_tasks: set[asyncio.Task] = set()
+        self._in_flight_count = 0
+        self._in_flight_lock = asyncio.Lock()
+
+    async def claim_batch(self) -> list[tuple[str, dict[str, Any]]]:
+        """
+        Claim up to batch_size pending tasks atomically.
+
+        Uses FOR UPDATE SKIP LOCKED to ensure no conflicts with other workers.
+
+        Returns:
+            List of tuples (operation_id, task_dict)
+        """
+        table = fq_table("async_operations", self._schema)
+
+        async with self._pool.acquire() as conn:
+            async with conn.transaction():
+                # Select and lock pending tasks
+                rows = await conn.fetch(
+                    f"""
+                    SELECT operation_id, task_payload
+                    FROM {table}
+                    WHERE status = 'pending' AND task_payload IS NOT NULL
+                    ORDER BY created_at
+                    LIMIT $1
+                    FOR UPDATE SKIP LOCKED
+                    """,
+                    self._batch_size,
+                )
+
+                if not rows:
+                    return []
+
+                # Claim the tasks by updating status and worker_id
+                operation_ids = [row["operation_id"] for row in rows]
+                await conn.execute(
+                    f"""
+                    UPDATE {table}
+                    SET status = 'processing', worker_id = $1, claimed_at = now(), updated_at = now()
+                    WHERE operation_id = ANY($2)
+                    """,
+                    self._worker_id,
+                    operation_ids,
+                )
+
+                # Parse and return task payloads
+                return [(str(row["operation_id"]), json.loads(row["task_payload"])) for row in rows]
+
+    async def _mark_completed(self, operation_id: str):
+        """Mark a task as completed."""
+        table = fq_table("async_operations", self._schema)
+        await self._pool.execute(
+            f"""
+            UPDATE {table}
+            SET status = 'completed', completed_at = now(), updated_at = now()
+            WHERE operation_id = $1
+            """,
+            operation_id,
+        )
+
+    async def _mark_failed(self, operation_id: str, error_message: str):
+        """Mark a task as failed with error message."""
+        table = fq_table("async_operations", self._schema)
+        # Truncate error message if too long (max 5000 chars in schema)
+        error_message = error_message[:5000] if len(error_message) > 5000 else error_message
+        await self._pool.execute(
+            f"""
+            UPDATE {table}
+            SET status = 'failed', error_message = $2, completed_at = now(), updated_at = now()
+            WHERE operation_id = $1
+            """,
+            operation_id,
+            error_message,
+        )
+
+    async def _retry_or_fail(self, operation_id: str, error_message: str):
+        """Increment retry count or mark as failed if max retries exceeded."""
+        table = fq_table("async_operations", self._schema)
+
+        # Get current retry count
+        row = await self._pool.fetchrow(
+            f"SELECT retry_count FROM {table} WHERE operation_id = $1",
+            operation_id,
+        )
+
+        if row is None:
+            logger.warning(f"Operation {operation_id} not found, cannot retry")
+            return
+
+        retry_count = row["retry_count"]
+
+        if retry_count >= self._max_retries:
+            # Max retries exceeded, mark as failed
+            await self._mark_failed(
+                operation_id, f"Max retries ({self._max_retries}) exceeded. Last error: {error_message}"
+            )
+            logger.error(f"Task {operation_id} failed after {retry_count} retries")
+        else:
+            # Increment retry and reset to pending
+            await self._pool.execute(
+                f"""
+                UPDATE {table}
+                SET status = 'pending', worker_id = NULL, claimed_at = NULL,
+                    retry_count = retry_count + 1, updated_at = now()
+                WHERE operation_id = $1
+                """,
+                operation_id,
+            )
+            logger.warning(f"Task {operation_id} failed, will retry (attempt {retry_count + 1}/{self._max_retries})")
+
+    async def execute_task(self, operation_id: str, task_dict: dict[str, Any]):
+        """Execute a single task and update its status."""
+        task_type = task_dict.get("type", "unknown")
+        bank_id = task_dict.get("bank_id", "unknown")
+
+        try:
+            logger.debug(f"Executing task {operation_id} (type={task_type}, bank={bank_id})")
+            await self._executor(task_dict)
+            await self._mark_completed(operation_id)
+            logger.debug(f"Task {operation_id} completed successfully")
+        except Exception as e:
+            error_msg = f"{type(e).__name__}: {e}\n{traceback.format_exc()}"
+            logger.error(f"Task {operation_id} failed: {e}")
+            await self._retry_or_fail(operation_id, error_msg)
+
+    async def run(self):
+        """
+        Main polling loop.
+
+        Continuously polls for pending tasks, claims them, and executes them
+        until shutdown is signaled.
+        """
+        logger.info(f"Worker {self._worker_id} starting polling loop")
+
+        while not self._shutdown.is_set():
+            try:
+                # Claim a batch of tasks
+                tasks = await self.claim_batch()
+
+                if tasks:
+                    # Log batch info
+                    task_types = {}
+                    for _, task_dict in tasks:
+                        t = task_dict.get("type", "unknown")
+                        task_types[t] = task_types.get(t, 0) + 1
+                    types_str = ", ".join(f"{k}:{v}" for k, v in task_types.items())
+                    logger.info(f"Worker {self._worker_id} claimed {len(tasks)} tasks: {types_str}")
+
+                    # Track in-flight tasks
+                    async with self._in_flight_lock:
+                        self._in_flight_count += len(tasks)
+
+                    # Execute tasks concurrently
+                    try:
+                        await asyncio.gather(
+                            *[self.execute_task(op_id, task_dict) for op_id, task_dict in tasks],
+                            return_exceptions=True,
+                        )
+                    finally:
+                        async with self._in_flight_lock:
+                            self._in_flight_count -= len(tasks)
+                else:
+                    # No tasks found, wait before polling again
+                    try:
+                        await asyncio.wait_for(
+                            self._shutdown.wait(),
+                            timeout=self._poll_interval_ms / 1000,
+                        )
+                    except asyncio.TimeoutError:
+                        pass  # Normal timeout, continue polling
+
+            except asyncio.CancelledError:
+                logger.info(f"Worker {self._worker_id} polling loop cancelled")
+                break
+            except Exception as e:
+                logger.error(f"Worker {self._worker_id} error in polling loop: {e}")
+                traceback.print_exc()
+                # Backoff on error
+                await asyncio.sleep(1)
+
+        logger.info(f"Worker {self._worker_id} polling loop stopped")
+
+    async def shutdown_graceful(self, timeout: float = 30.0):
+        """
+        Signal shutdown and wait for current tasks to complete.
+
+        Args:
+            timeout: Maximum time to wait for in-flight tasks (seconds)
+        """
+        logger.info(f"Worker {self._worker_id} initiating graceful shutdown")
+        self._shutdown.set()
+
+        # Wait for in-flight tasks to complete
+        start_time = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start_time < timeout:
+            async with self._in_flight_lock:
+                in_flight = self._in_flight_count
+
+            if in_flight == 0:
+                logger.info(f"Worker {self._worker_id} graceful shutdown complete")
+                return
+
+            logger.info(f"Worker {self._worker_id} waiting for {in_flight} in-flight tasks")
+            await asyncio.sleep(0.5)
+
+        logger.warning(f"Worker {self._worker_id} shutdown timeout after {timeout}s")
+
+    @property
+    def worker_id(self) -> str:
+        """Get the worker ID."""
+        return self._worker_id
+
+    @property
+    def is_shutdown(self) -> bool:
+        """Check if shutdown has been signaled."""
+        return self._shutdown.is_set()

hindsight-api/pyproject.toml

@@ -63,6 +63,7 @@ test = [
 
 [project.scripts]
 hindsight-api = "hindsight_api.main:main"
+hindsight-worker = "hindsight_api.worker.main:main"
 hindsight-local-mcp = "hindsight_api.mcp_local:main"
 hindsight-admin = "hindsight_api.admin.cli:main"
 

hindsight-api/tests/conftest.py

@@ -12,6 +12,7 @@ from hindsight_api import MemoryEngine, LLMConfig, LocalSTEmbeddings, RequestCon
 
 from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder
 from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
+from hindsight_api.engine.task_backend import SyncTaskBackend
 from hindsight_api.pg0 import EmbeddedPostgres
 
 # Default pg0 instance configuration for tests
@@ -147,6 +148,7 @@ async def memory(pg0_db_url, embeddings, cross_encoder, query_analyzer):
     Uses pg0_db_url (a postgresql:// URL) directly, so MemoryEngine won't try to
     manage pg0 lifecycle - that's handled by the session-scoped pg0_db_url fixture.
     Migrations are disabled here since they're run once at session scope in pg0_db_url.
+    Uses SyncTaskBackend so async tasks execute immediately (no worker needed).
     """
     mem = MemoryEngine(
         db_url=pg0_db_url,  # Direct postgresql:// URL, not pg0://
@@ -160,6 +162,7 @@ async def memory(pg0_db_url, embeddings, cross_encoder, query_analyzer):
         pool_min_size=1,
         pool_max_size=5,
         run_migrations=False,  # Migrations already run at session scope
+        task_backend=SyncTaskBackend(),  # Execute tasks immediately in tests
     )
     await mem.initialize()
     yield mem

hindsight-api/tests/test_custom_embedding_dimension.py

@@ -17,6 +17,7 @@ from hindsight_api import MemoryEngine, RequestContext
 from hindsight_api.engine.embeddings import LocalSTEmbeddings, OpenAIEmbeddings, CohereEmbeddings
 from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder, CohereCrossEncoder
 from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
+from hindsight_api.engine.task_backend import SyncTaskBackend
 from hindsight_api.extensions import TenantExtension, TenantContext
 from hindsight_api.migrations import run_migrations, ensure_embedding_dimension
 
@@ -323,6 +324,7 @@ class TestOpenAIEmbeddings:
             pool_max_size=3,
             run_migrations=False,
             tenant_extension=SchemaTenantExtension(schema_name),
+            task_backend=SyncTaskBackend(),
         )
 
         try:
@@ -392,6 +394,7 @@ class TestOpenAIEmbeddings:
             pool_max_size=3,
             run_migrations=False,
             tenant_extension=SchemaTenantExtension(schema_name),
+            task_backend=SyncTaskBackend(),
         )
 
         try:
@@ -559,6 +562,7 @@ class TestCohereIntegration:
             pool_max_size=3,
             run_migrations=False,
             tenant_extension=SchemaTenantExtension(schema_name),
+            task_backend=SyncTaskBackend(),
         )
 
         try:

hindsight-api/tests/test_load_large_batch.py

@@ -19,6 +19,7 @@ import pytest_asyncio
 from hindsight_api import MemoryEngine, LLMConfig, LocalSTEmbeddings, RequestContext
 from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder
 from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
+from hindsight_api.engine.task_backend import SyncTaskBackend
 from hindsight_api.engine.retain.fact_extraction import FactExtractionResponse, ExtractedFact
 from hindsight_api.engine.llm_wrapper import TokenUsage
 
@@ -106,6 +107,7 @@ class TestLargeBatchRetain:
             pool_max_size=10,
             run_migrations=False,
             skip_llm_verification=True,  # Skip LLM verification since we're mocking
+            task_backend=SyncTaskBackend(),  # Execute tasks immediately in tests
         )
         await mem.initialize()
         yield mem

hindsight-api/tests/test_worker.py

@@ -0,0 +1,592 @@
+"""
+Tests for the distributed worker system.
+
+Tests cover:
+- BrokerTaskBackend task submission and storage
+- WorkerPoller task claiming with FOR UPDATE SKIP LOCKED
+- Concurrent workers claiming different tasks (no duplicates)
+- Task completion and failure handling
+- Retry mechanism
+- Worker decommissioning
+"""
+
+import asyncio
+import json
+import uuid
+
+import pytest
+import pytest_asyncio
+
+from hindsight_api.engine.task_backend import BrokerTaskBackend, SyncTaskBackend
+
+
+# Use loadgroup to ensure these tests run in the same worker
+# since they share database state
+pytestmark = pytest.mark.xdist_group("worker_tests")
+
+
+@pytest_asyncio.fixture
+async def pool(pg0_db_url):
+    """Create a dedicated connection pool for worker tests."""
+    import asyncpg
+
+    from hindsight_api.pg0 import resolve_database_url
+
+    # Resolve pg0:// URL to postgresql:// URL if needed
+    resolved_url = await resolve_database_url(pg0_db_url)
+
+    pool = await asyncpg.create_pool(
+        resolved_url,
+        min_size=2,
+        max_size=10,
+        command_timeout=30,
+    )
+    yield pool
+    await pool.close()
+
+
+@pytest_asyncio.fixture
+async def clean_operations(pool):
+    """Clean up async_operations table before and after tests."""
+    # Clean before test
+    await pool.execute("DELETE FROM async_operations WHERE bank_id LIKE 'test-worker-%'")
+    yield
+    # Clean after test
+    await pool.execute("DELETE FROM async_operations WHERE bank_id LIKE 'test-worker-%'")
+
+
+class TestBrokerTaskBackend:
+    """Tests for BrokerTaskBackend task storage."""
+
+    @pytest.mark.asyncio
+    async def test_submit_task_updates_existing_operation(self, pool, clean_operations):
+        """Test that submit_task updates task_payload for existing operations."""
+        # Create an operation record first
+        operation_id = uuid.uuid4()
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+
+        await pool.execute(
+            """
+            INSERT INTO async_operations (operation_id, bank_id, operation_type, status)
+            VALUES ($1, $2, 'test_operation', 'pending')
+            """,
+            operation_id,
+            bank_id,
+        )
+
+        # Submit task with same operation_id
+        backend = BrokerTaskBackend(pool_getter=lambda: pool)
+        await backend.initialize()
+
+        task_dict = {
+            "operation_id": str(operation_id),
+            "type": "test_task",
+            "bank_id": bank_id,
+            "data": {"key": "value"},
+        }
+        await backend.submit_task(task_dict)
+
+        # Verify task_payload was stored
+        row = await pool.fetchrow(
+            "SELECT task_payload, status FROM async_operations WHERE operation_id = $1",
+            operation_id,
+        )
+        assert row is not None
+        assert row["status"] == "pending"
+        payload = json.loads(row["task_payload"])
+        assert payload["type"] == "test_task"
+        assert payload["data"] == {"key": "value"}
+
+    @pytest.mark.asyncio
+    async def test_submit_task_creates_new_operation(self, pool, clean_operations):
+        """Test that submit_task creates new operation when no operation_id provided."""
+        backend = BrokerTaskBackend(pool_getter=lambda: pool)
+        await backend.initialize()
+
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        task_dict = {
+            "type": "access_count_update",
+            "bank_id": bank_id,
+            "node_ids": ["node1", "node2"],
+        }
+        await backend.submit_task(task_dict)
+
+        # Verify new operation was created
+        row = await pool.fetchrow(
+            "SELECT operation_type, status, task_payload FROM async_operations WHERE bank_id = $1",
+            bank_id,
+        )
+        assert row is not None
+        assert row["operation_type"] == "access_count_update"
+        assert row["status"] == "pending"
+        payload = json.loads(row["task_payload"])
+        assert payload["node_ids"] == ["node1", "node2"]
+
+
+class TestWorkerPoller:
+    """Tests for WorkerPoller task claiming and execution."""
+
+    @pytest.mark.asyncio
+    async def test_claim_batch_claims_pending_tasks(self, pool, clean_operations):
+        """Test that claim_batch claims pending tasks with task_payload."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create some pending tasks
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        for i in range(3):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
+                VALUES ($1, $2, 'test', 'pending', $3::jsonb)
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Create poller and claim tasks
+        executed_tasks = []
+
+        async def mock_executor(task_dict):
+            executed_tasks.append(task_dict)
+
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="test-worker-1",
+            executor=mock_executor,
+            batch_size=10,
+        )
+
+        claimed = await poller.claim_batch()
+        assert len(claimed) == 3
+
+        # Verify tasks are marked as processing with worker_id
+        rows = await pool.fetch(
+            "SELECT status, worker_id FROM async_operations WHERE bank_id = $1",
+            bank_id,
+        )
+        for row in rows:
+            assert row["status"] == "processing"
+            assert row["worker_id"] == "test-worker-1"
+
+    @pytest.mark.asyncio
+    async def test_claim_batch_respects_batch_size(self, pool, clean_operations):
+        """Test that claim_batch respects the batch_size limit."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create 10 pending tasks
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        for i in range(10):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
+                VALUES ($1, $2, 'test', 'pending', $3::jsonb)
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Claim with batch_size=3
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="test-worker-1",
+            executor=lambda x: None,
+            batch_size=3,
+        )
+
+        claimed = await poller.claim_batch()
+        assert len(claimed) == 3
+
+    @pytest.mark.asyncio
+    async def test_execute_task_marks_completed(self, pool, clean_operations):
+        """Test that successful task execution marks task as completed."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create a pending task
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        op_id = uuid.uuid4()
+        payload = json.dumps({"type": "test_task", "operation_id": str(op_id), "bank_id": bank_id})
+        await pool.execute(
+            """
+            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
+            VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'test-worker-1')
+            """,
+            op_id,
+            bank_id,
+            payload,
+        )
+
+        executed = []
+
+        async def mock_executor(task_dict):
+            executed.append(task_dict)
+
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="test-worker-1",
+            executor=mock_executor,
+        )
+
+        # Execute the task
+        task_dict = json.loads(payload)
+        await poller.execute_task(str(op_id), task_dict)
+
+        assert len(executed) == 1
+
+        # Verify task is marked as completed
+        row = await pool.fetchrow(
+            "SELECT status, completed_at FROM async_operations WHERE operation_id = $1",
+            op_id,
+        )
+        assert row["status"] == "completed"
+        assert row["completed_at"] is not None
+
+    @pytest.mark.asyncio
+    async def test_execute_task_retries_on_failure(self, pool, clean_operations):
+        """Test that failed task execution triggers retry mechanism."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create a pending task with retry_count=0
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        op_id = uuid.uuid4()
+        payload = json.dumps({"type": "test_task", "operation_id": str(op_id), "bank_id": bank_id})
+        await pool.execute(
+            """
+            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id, retry_count)
+            VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'test-worker-1', 0)
+            """,
+            op_id,
+            bank_id,
+            payload,
+        )
+
+        async def failing_executor(task_dict):
+            raise ValueError("Simulated failure")
+
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="test-worker-1",
+            executor=failing_executor,
+            max_retries=3,
+        )
+
+        # Execute (should fail and retry)
+        task_dict = json.loads(payload)
+        await poller.execute_task(str(op_id), task_dict)
+
+        # Verify task is back to pending with incremented retry_count
+        row = await pool.fetchrow(
+            "SELECT status, retry_count, worker_id FROM async_operations WHERE operation_id = $1",
+            op_id,
+        )
+        assert row["status"] == "pending"
+        assert row["retry_count"] == 1
+        assert row["worker_id"] is None  # Worker ID cleared for retry
+
+    @pytest.mark.asyncio
+    async def test_execute_task_fails_after_max_retries(self, pool, clean_operations):
+        """Test that task is marked failed after exceeding max retries."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create a task that has already used all retries
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        op_id = uuid.uuid4()
+        payload = json.dumps({"type": "test_task", "operation_id": str(op_id), "bank_id": bank_id})
+        await pool.execute(
+            """
+            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id, retry_count)
+            VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'test-worker-1', 3)
+            """,
+            op_id,
+            bank_id,
+            payload,
+        )
+
+        async def failing_executor(task_dict):
+            raise ValueError("Simulated failure")
+
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="test-worker-1",
+            executor=failing_executor,
+            max_retries=3,
+        )
+
+        # Execute (should fail permanently)
+        task_dict = json.loads(payload)
+        await poller.execute_task(str(op_id), task_dict)
+
+        # Verify task is marked as failed
+        row = await pool.fetchrow(
+            "SELECT status, error_message FROM async_operations WHERE operation_id = $1",
+            op_id,
+        )
+        assert row["status"] == "failed"
+        assert "Max retries" in row["error_message"]
+
+
+class TestConcurrentWorkers:
+    """Tests for concurrent worker task claiming (FOR UPDATE SKIP LOCKED)."""
+
+    @pytest.mark.asyncio
+    async def test_concurrent_workers_claim_different_tasks(self, pool, clean_operations):
+        """Test that multiple workers claim different tasks (no duplicates)."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create 10 pending tasks
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        task_ids = []
+        for i in range(10):
+            op_id = uuid.uuid4()
+            task_ids.append(op_id)
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id, "operation_id": str(op_id)})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
+                VALUES ($1, $2, 'test', 'pending', $3::jsonb)
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Create 3 workers that will claim tasks concurrently
+        workers_claimed: dict[str, list[str]] = {"worker-1": [], "worker-2": [], "worker-3": []}
+
+        async def claim_for_worker(worker_id: str):
+            poller = WorkerPoller(
+                pool=pool,
+                worker_id=worker_id,
+                executor=lambda x: None,
+                batch_size=5,  # Each worker tries to claim 5
+            )
+            claimed = await poller.claim_batch()
+            workers_claimed[worker_id] = [op_id for op_id, _ in claimed]
+
+        # Run all workers concurrently
+        await asyncio.gather(
+            claim_for_worker("worker-1"),
+            claim_for_worker("worker-2"),
+            claim_for_worker("worker-3"),
+        )
+
+        # Verify no duplicates - each task claimed by exactly one worker
+        all_claimed = workers_claimed["worker-1"] + workers_claimed["worker-2"] + workers_claimed["worker-3"]
+        assert len(all_claimed) == len(set(all_claimed)), "Duplicate task claimed by multiple workers!"
+
+        # Verify total claimed equals available tasks (10)
+        assert len(all_claimed) == 10, f"Expected 10 tasks claimed, got {len(all_claimed)}"
+
+        # Verify each task is assigned to exactly one worker in DB
+        rows = await pool.fetch(
+            "SELECT operation_id, worker_id FROM async_operations WHERE bank_id = $1",
+            bank_id,
+        )
+        worker_assignments = {str(row["operation_id"]): row["worker_id"] for row in rows}
+
+        # With FOR UPDATE SKIP LOCKED, it's a race condition which workers get tasks.
+        # The important invariant is no duplicates and all tasks claimed, which we verified above.
+        # Just verify that at least 1 worker got tasks and all tasks have a worker assigned.
+        assert len(set(worker_assignments.values())) >= 1, "At least one worker should have claimed tasks"
+        assert all(w is not None for w in worker_assignments.values()), "All tasks should have a worker assigned"
+
+    @pytest.mark.asyncio
+    async def test_workers_do_not_claim_already_processing_tasks(self, pool, clean_operations):
+        """Test that workers skip tasks already being processed by another worker."""
+        from hindsight_api.worker import WorkerPoller
+
+        # Create tasks - some pending, some already processing
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+
+        # Create 3 pending tasks
+        for i in range(3):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
+                VALUES ($1, $2, 'test', 'pending', $3::jsonb)
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Create 2 already-processing tasks owned by another worker
+        for i in range(2):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i + 10, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
+                VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'other-worker')
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # New worker should only claim the 3 pending tasks
+        poller = WorkerPoller(
+            pool=pool,
+            worker_id="new-worker",
+            executor=lambda x: None,
+            batch_size=10,
+        )
+
+        claimed = await poller.claim_batch()
+        assert len(claimed) == 3, "Worker should only claim pending tasks"
+
+        # Verify other worker's tasks are still owned by them
+        row = await pool.fetchrow(
+            "SELECT COUNT(*) as count FROM async_operations WHERE bank_id = $1 AND worker_id = 'other-worker'",
+            bank_id,
+        )
+        assert row["count"] == 2
+
+
+class TestWorkerDecommission:
+    """Tests for worker decommissioning functionality."""
+
+    @pytest.mark.asyncio
+    async def test_decommission_releases_worker_tasks(self, pool, clean_operations):
+        """Test that decommissioning a worker releases all its processing tasks."""
+        # Create tasks being processed by a worker
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+        worker_id = "worker-to-decommission"
+
+        for i in range(5):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id, claimed_at)
+                VALUES ($1, $2, 'test', 'processing', $3::jsonb, $4, now())
+                """,
+                op_id,
+                bank_id,
+                payload,
+                worker_id,
+            )
+
+        # Run decommission
+        result = await pool.fetch(
+            """
+            UPDATE async_operations
+            SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
+            WHERE worker_id = $1 AND status = 'processing'
+            RETURNING operation_id
+            """,
+            worker_id,
+        )
+
+        assert len(result) == 5
+
+        # Verify all tasks are back to pending
+        rows = await pool.fetch(
+            "SELECT status, worker_id, claimed_at FROM async_operations WHERE bank_id = $1",
+            bank_id,
+        )
+        for row in rows:
+            assert row["status"] == "pending"
+            assert row["worker_id"] is None
+            assert row["claimed_at"] is None
+
+    @pytest.mark.asyncio
+    async def test_decommission_does_not_affect_other_workers(self, pool, clean_operations):
+        """Test that decommissioning one worker doesn't affect another worker's tasks."""
+        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
+
+        # Create tasks for worker-1
+        for i in range(3):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
+                VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'worker-1')
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Create tasks for worker-2
+        for i in range(3):
+            op_id = uuid.uuid4()
+            payload = json.dumps({"type": "test_task", "index": i + 10, "bank_id": bank_id})
+            await pool.execute(
+                """
+                INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
+                VALUES ($1, $2, 'test', 'processing', $3::jsonb, 'worker-2')
+                """,
+                op_id,
+                bank_id,
+                payload,
+            )
+
+        # Decommission worker-1 only
+        await pool.execute(
+            """
+            UPDATE async_operations
+            SET status = 'pending', worker_id = NULL, claimed_at = NULL
+            WHERE worker_id = 'worker-1' AND status = 'processing'
+            """
+        )
+
+        # Verify worker-1 tasks are released
+        worker1_rows = await pool.fetch(
+            "SELECT status, worker_id FROM async_operations WHERE bank_id = $1 AND worker_id IS NULL",
+            bank_id,
+        )
+        assert len(worker1_rows) == 3
+
+        # Verify worker-2 tasks are unaffected
+        worker2_rows = await pool.fetch(
+            "SELECT status, worker_id FROM async_operations WHERE bank_id = $1 AND worker_id = 'worker-2'",
+            bank_id,
+        )
+        assert len(worker2_rows) == 3
+        for row in worker2_rows:
+            assert row["status"] == "processing"
+
+
+class TestSyncTaskBackend:
+    """Tests for SyncTaskBackend (used in tests and embedded mode)."""
+
+    @pytest.mark.asyncio
+    async def test_sync_backend_executes_immediately(self):
+        """Test that SyncTaskBackend executes tasks immediately."""
+        executed = []
+
+        async def mock_executor(task_dict):
+            executed.append(task_dict)
+
+        backend = SyncTaskBackend()
+        backend.set_executor(mock_executor)
+        await backend.initialize()
+
+        task_dict = {"type": "test", "data": "value"}
+        await backend.submit_task(task_dict)
+
+        assert len(executed) == 1
+        assert executed[0] == task_dict
+
+    @pytest.mark.asyncio
+    async def test_sync_backend_handles_errors(self):
+        """Test that SyncTaskBackend handles executor errors gracefully."""
+
+        async def failing_executor(task_dict):
+            raise ValueError("Test error")
+
+        backend = SyncTaskBackend()
+        backend.set_executor(failing_executor)
+        await backend.initialize()
+
+        # Should not raise, error is logged
+        await backend.submit_task({"type": "test"})

hindsight-cli/Cargo.toml

@@ -45,10 +45,6 @@ chrono = "0.4"
 walkdir = "2.5"
 dirs = "5.0"
 
-[dev-dependencies]
-# For integration tests with blocking HTTP client
-reqwest = { version = "0.12", features = ["blocking"] }
-
 [profile.release]
 opt-level = "z"
 lto = true

hindsight-cli/smoke-test.sh

@@ -67,7 +67,7 @@ run_test_output() {
 cleanup() {
     echo ""
     echo "Cleaning up test bank..."
-    "$HINDSIGHT_CLI" bank delete "$TEST_BANK" -y 2>/dev/null || true
+    "$HINDSIGHT_CLI" bank delete "$TEST_BANK" 2>/dev/null || true
 }
 trap cleanup EXIT
 
@@ -115,32 +115,8 @@ run_test "list documents" "$HINDSIGHT_CLI" document list "$TEST_BANK" || FAILED=
 # Test 14: Clear memories
 run_test "clear memories" "$HINDSIGHT_CLI" memory clear "$TEST_BANK" || FAILED=1
 
-# Test 15: Health check
-run_test_output "health check" "healthy" "$HINDSIGHT_CLI" health || FAILED=1
-
-# Test 16: List memories (new command)
-run_test "list memories" "$HINDSIGHT_CLI" memory list "$TEST_BANK" || FAILED=1
-
-# Test 17: List tags
-run_test "list tags" "$HINDSIGHT_CLI" tag list "$TEST_BANK" || FAILED=1
-
-# Test 18: List mental models
-run_test "list mental models" "$HINDSIGHT_CLI" mental-model list "$TEST_BANK" || FAILED=1
-
-# Test 19: Create mental model
-run_test "create mental model" "$HINDSIGHT_CLI" mental-model create "$TEST_BANK" "Test Model" "A test mental model" || FAILED=1
-
-# Test 20: List mental models (should have one now)
-run_test_output "list mental models with model" "Test Model" "$HINDSIGHT_CLI" mental-model list "$TEST_BANK" || FAILED=1
-
-# Test 21: Bank graph
-run_test "bank graph" "$HINDSIGHT_CLI" bank graph "$TEST_BANK" || FAILED=1
-
-# Test 22: List operations
-run_test "list operations" "$HINDSIGHT_CLI" operation list "$TEST_BANK" || FAILED=1
-
-# Test 23: Delete bank
-run_test "delete bank" "$HINDSIGHT_CLI" bank delete "$TEST_BANK" -y || FAILED=1
+# Test 15: Delete bank
+run_test "delete bank" "$HINDSIGHT_CLI" bank delete "$TEST_BANK" || FAILED=1
 
 echo ""
 if [ $FAILED -eq 0 ]; then

hindsight-cli/src/api.rs

@@ -316,266 +316,6 @@ impl ApiClient {
     }
 }
 
-// ============================================================================
-// Additional API methods for complete CLI coverage
-// ============================================================================
-
-impl ApiClient {
-    // --- Mental Model Methods ---
-
-    pub fn list_mental_models(
-        &self,
-        bank_id: &str,
-        subtype: Option<&str>,
-        tags: Option<Vec<String>>,
-        tags_match: Option<&str>,
-        _verbose: bool,
-    ) -> Result<types::MentalModelListResponse> {
-        self.runtime.block_on(async {
-            let tags_match_enum = match tags_match {
-                Some("all") => Some(types::TagsMatch::All),
-                Some("any_strict") => Some(types::TagsMatch::AnyStrict),
-                Some("all_strict") => Some(types::TagsMatch::AllStrict),
-                _ => Some(types::TagsMatch::Any),
-            };
-            let response = self.client.list_mental_models(
-                bank_id,
-                subtype,
-                tags.as_ref(),
-                tags_match_enum,
-                None,
-            ).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn get_mental_model(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        _verbose: bool,
-    ) -> Result<types::MentalModelResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_mental_model(bank_id, model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn create_mental_model(
-        &self,
-        bank_id: &str,
-        request: &types::CreateMentalModelRequest,
-        _verbose: bool,
-    ) -> Result<types::MentalModelResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.create_mental_model(bank_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn delete_mental_model(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        _verbose: bool,
-    ) -> Result<types::DeleteResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.delete_mental_model(bank_id, model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn update_mental_model(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        request: &types::UpdateMentalModelRequest,
-        _verbose: bool,
-    ) -> Result<types::MentalModelResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.update_mental_model(bank_id, model_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn refresh_mental_models(
-        &self,
-        bank_id: &str,
-        subtype: Option<&str>,
-        tags: Option<Vec<String>>,
-        _verbose: bool,
-    ) -> Result<types::AsyncOperationSubmitResponse> {
-        self.runtime.block_on(async {
-            let subtype_enum = match subtype {
-                Some("structural") => Some(types::Subtype::Structural),
-                Some("emergent") => Some(types::Subtype::Emergent),
-                Some("pinned") => Some(types::Subtype::Pinned),
-                Some("learned") => Some(types::Subtype::Learned),
-                _ => None,
-            };
-            let request = types::RefreshMentalModelsRequest {
-                subtype: subtype_enum,
-                tags,
-            };
-            let response = self.client.refresh_mental_models(bank_id, None, &request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn refresh_mental_model(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        _verbose: bool,
-    ) -> Result<types::AsyncOperationSubmitResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.refresh_mental_model(bank_id, model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn list_mental_model_versions(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        _verbose: bool,
-    ) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.list_mental_model_versions(bank_id, model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn get_mental_model_version(
-        &self,
-        bank_id: &str,
-        model_id: &str,
-        version: i64,
-        _verbose: bool,
-    ) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.get_mental_model_version(bank_id, model_id, version, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Memory Methods ---
-
-    pub fn get_memory(&self, bank_id: &str, memory_id: &str, _verbose: bool) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.get_memory(bank_id, memory_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Bank Methods ---
-
-    pub fn create_bank(
-        &self,
-        bank_id: &str,
-        request: &types::CreateBankRequest,
-        _verbose: bool,
-    ) -> Result<types::BankProfileResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.create_or_update_bank(bank_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn update_bank(
-        &self,
-        bank_id: &str,
-        request: &types::CreateBankRequest,
-        _verbose: bool,
-    ) -> Result<types::BankProfileResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.update_bank(bank_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn set_mission(
-        &self,
-        bank_id: &str,
-        mission: &str,
-        _verbose: bool,
-    ) -> Result<types::BankProfileResponse> {
-        self.runtime.block_on(async {
-            let request = types::CreateBankRequest {
-                name: None,
-                mission: Some(mission.to_string()),
-                background: None,
-                disposition: None,
-            };
-            let response = self.client.update_bank(bank_id, None, &request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn get_graph(
-        &self,
-        bank_id: &str,
-        type_filter: Option<&str>,
-        limit: Option<i64>,
-        _verbose: bool,
-    ) -> Result<types::GraphDataResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_graph(bank_id, limit, type_filter, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Tag Methods ---
-
-    pub fn list_tags(
-        &self,
-        bank_id: &str,
-        q: Option<&str>,
-        limit: Option<i64>,
-        offset: Option<i64>,
-        _verbose: bool,
-    ) -> Result<types::ListTagsResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.list_tags(bank_id, limit, offset, q, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Chunk Methods ---
-
-    pub fn get_chunk(&self, chunk_id: &str, _verbose: bool) -> Result<types::ChunkResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_chunk(chunk_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Operation Methods ---
-
-    pub fn get_operation(&self, bank_id: &str, operation_id: &str, _verbose: bool) -> Result<types::OperationStatusResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_operation_status(bank_id, operation_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Health Methods ---
-
-    pub fn health(&self, _verbose: bool) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.health_endpoint_health_get().await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn metrics(&self, _verbose: bool) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.metrics_endpoint_metrics_get().await?;
-            Ok(response.into_inner())
-        })
-    }
-}
-
 // Re-export types from the generated client for use in commands
 pub use types::{
     BankProfileResponse,

hindsight-cli/src/commands/bank.rs

@@ -222,226 +222,6 @@ pub fn update_background(
     }
 }
 
-/// Set bank mission
-pub fn mission(
-    client: &ApiClient,
-    bank_id: &str,
-    mission_text: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Setting mission..."))
-    } else {
-        None
-    };
-
-    let response = client.set_mission(bank_id, mission_text, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(profile) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success("Mission updated successfully");
-                println!();
-                println!("{}", profile.mission);
-            } else {
-                output::print_output(&profile, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Create a new bank
-pub fn create(
-    client: &ApiClient,
-    bank_id: &str,
-    name: Option<String>,
-    mission_text: Option<String>,
-    skepticism: Option<i64>,
-    literalism: Option<i64>,
-    empathy: Option<i64>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Creating bank..."))
-    } else {
-        None
-    };
-
-    use hindsight_client::types;
-    use std::num::NonZeroU64;
-
-    let disposition = if skepticism.is_some() || literalism.is_some() || empathy.is_some() {
-        Some(types::DispositionTraits {
-            skepticism: NonZeroU64::new(skepticism.unwrap_or(3) as u64).unwrap(),
-            literalism: NonZeroU64::new(literalism.unwrap_or(3) as u64).unwrap(),
-            empathy: NonZeroU64::new(empathy.unwrap_or(3) as u64).unwrap(),
-        })
-    } else {
-        None
-    };
-
-    let request = types::CreateBankRequest {
-        name,
-        mission: mission_text,
-        background: None,
-        disposition,
-    };
-
-    let response = client.create_bank(bank_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(profile) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Bank '{}' created successfully", bank_id));
-                println!();
-                ui::print_disposition(&profile);
-            } else {
-                output::print_output(&profile, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Update bank properties (partial update)
-pub fn update(
-    client: &ApiClient,
-    bank_id: &str,
-    name: Option<String>,
-    mission_text: Option<String>,
-    skepticism: Option<i64>,
-    literalism: Option<i64>,
-    empathy: Option<i64>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    if name.is_none() && mission_text.is_none() && skepticism.is_none() && literalism.is_none() && empathy.is_none() {
-        anyhow::bail!("At least one field must be provided (--name, --mission, --skepticism, --literalism, --empathy)");
-    }
-
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Updating bank..."))
-    } else {
-        None
-    };
-
-    use hindsight_client::types;
-    use std::num::NonZeroU64;
-
-    let disposition = if skepticism.is_some() || literalism.is_some() || empathy.is_some() {
-        Some(types::DispositionTraits {
-            skepticism: NonZeroU64::new(skepticism.unwrap_or(3) as u64).unwrap(),
-            literalism: NonZeroU64::new(literalism.unwrap_or(3) as u64).unwrap(),
-            empathy: NonZeroU64::new(empathy.unwrap_or(3) as u64).unwrap(),
-        })
-    } else {
-        None
-    };
-
-    let request = types::CreateBankRequest {
-        name,
-        mission: mission_text,
-        background: None,
-        disposition,
-    };
-
-    let response = client.update_bank(bank_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(profile) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Bank '{}' updated successfully", bank_id));
-                println!();
-                ui::print_disposition(&profile);
-            } else {
-                output::print_output(&profile, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get memory graph data
-pub fn graph(
-    client: &ApiClient,
-    bank_id: &str,
-    type_filter: Option<String>,
-    limit: i64,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching graph data..."))
-    } else {
-        None
-    };
-
-    let response = client.get_graph(bank_id, type_filter.as_deref(), Some(limit), verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Memory Graph: {}", bank_id));
-
-                println!("  {} {}", ui::dim("Nodes:"), ui::gradient_start(&result.nodes.len().to_string()));
-                println!("  {} {}", ui::dim("Edges:"), ui::gradient_end(&result.edges.len().to_string()));
-                println!();
-
-                // Show sample of nodes
-                if !result.nodes.is_empty() {
-                    println!("{}", ui::gradient_text("─── Sample Nodes ───"));
-                    for node in result.nodes.iter().take(5) {
-                        let fact_type = node.get("type")
-                            .and_then(|v| v.as_str())
-                            .unwrap_or("unknown");
-                        let id = node.get("id")
-                            .and_then(|v| v.as_str())
-                            .unwrap_or("unknown");
-                        println!("  {} [{}]", ui::dim(id), fact_type);
-                        if let Some(text) = node.get("text").and_then(|v| v.as_str()) {
-                            let preview: String = text.chars().take(60).collect();
-                            let ellipsis = if text.len() > 60 { "..." } else { "" };
-                            println!("    {}{}", preview, ellipsis);
-                        }
-                    }
-                    if result.nodes.len() > 5 {
-                        println!("  {} more...", ui::dim(&format!("+ {}", result.nodes.len() - 5)));
-                    }
-                    println!();
-                }
-
-                println!("{}", ui::dim("Use JSON output for full graph data: -o json"));
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
 pub fn delete(
     client: &ApiClient,
     bank_id: &str,

hindsight-cli/src/commands/chunk.rs

@@ -1,96 +0,0 @@
-//! Chunk commands for retrieving document chunks.
-
-use anyhow::Result;
-
-use crate::api::ApiClient;
-use crate::output::{self, OutputFormat};
-use crate::ui;
-
-/// Get a specific chunk by ID
-pub fn get(
-    client: &ApiClient,
-    chunk_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching chunk..."))
-    } else {
-        None
-    };
-
-    let response = client.get_chunk(chunk_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Chunk: {}", chunk_id));
-
-                println!("  {} {}", ui::dim("ID:"), result.chunk_id);
-                println!("  {} {}", ui::dim("Index:"), result.chunk_index);
-                println!("  {} {}", ui::dim("Document:"), result.document_id);
-                println!("  {} {}", ui::dim("Bank:"), result.bank_id);
-                println!("  {} {}", ui::dim("Created:"), result.created_at);
-
-                println!();
-                println!("{}", ui::gradient_text("─── Content ───"));
-                println!();
-                println!("{}", result.chunk_text);
-
-                println!();
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use hindsight_client::types::ChunkResponse;
-
-    #[test]
-    fn test_chunk_response_deserialization() {
-        let json = r#"{
-            "chunk_id": "chunk-123",
-            "bank_id": "test-bank",
-            "document_id": "doc-456",
-            "chunk_index": 0,
-            "chunk_text": "This is the chunk content.",
-            "created_at": "2024-01-15T10:00:00Z"
-        }"#;
-
-        let result: ChunkResponse = serde_json::from_str(json).unwrap();
-
-        assert_eq!(result.chunk_id, "chunk-123");
-        assert_eq!(result.bank_id, "test-bank");
-        assert_eq!(result.document_id, "doc-456");
-        assert_eq!(result.chunk_index, 0);
-        assert_eq!(result.chunk_text, "This is the chunk content.");
-        assert_eq!(result.created_at, "2024-01-15T10:00:00Z");
-    }
-
-    #[test]
-    fn test_chunk_response_multiline_content() {
-        let json = r#"{
-            "chunk_id": "chunk-456",
-            "bank_id": "test-bank",
-            "document_id": "doc-789",
-            "chunk_index": 5,
-            "chunk_text": "Line 1\nLine 2\nLine 3",
-            "created_at": "2024-01-15T11:00:00Z"
-        }"#;
-
-        let result: ChunkResponse = serde_json::from_str(json).unwrap();
-
-        assert_eq!(result.chunk_index, 5);
-        assert!(result.chunk_text.contains('\n'));
-        assert_eq!(result.chunk_text.lines().count(), 3);
-    }
-}

hindsight-cli/src/commands/health.rs

@@ -1,157 +0,0 @@
-//! Health and metrics commands.
-
-use anyhow::Result;
-use serde::Deserialize;
-
-use crate::api::ApiClient;
-use crate::output::{self, OutputFormat};
-use crate::ui;
-
-// Local type for health response
-#[derive(Debug, Deserialize)]
-struct HealthResponse {
-    status: String,
-    database: Option<String>,
-    version: Option<String>,
-}
-
-/// Check API health
-pub fn health(
-    client: &ApiClient,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Checking health..."))
-    } else {
-        None
-    };
-
-    let response = client.health(verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(value) => {
-            if output_format == OutputFormat::Pretty {
-                let result: HealthResponse = serde_json::from_value(value.clone())
-                    .unwrap_or(HealthResponse {
-                        status: "unknown".to_string(),
-                        database: None,
-                        version: None,
-                    });
-
-                let status_str = if result.status == "healthy" {
-                    ui::gradient_start(&result.status)
-                } else {
-                    ui::gradient_end(&result.status)
-                };
-
-                ui::print_section_header("Health Check");
-                println!("  {} {}", ui::dim("Status:"), status_str);
-
-                if let Some(db_status) = &result.database {
-                    let db_str = if db_status == "connected" {
-                        ui::gradient_start(db_status)
-                    } else {
-                        ui::gradient_end(db_status)
-                    };
-                    println!("  {} {}", ui::dim("Database:"), db_str);
-                }
-
-                if let Some(version) = &result.version {
-                    println!("  {} {}", ui::dim("Version:"), version);
-                }
-
-                println!();
-            } else {
-                output::print_output(&value, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get Prometheus metrics
-pub fn metrics(
-    client: &ApiClient,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching metrics..."))
-    } else {
-        None
-    };
-
-    let response = client.metrics(verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header("Prometheus Metrics");
-                println!("{}", result);
-            } else {
-                // For JSON/YAML, wrap in an object
-                let wrapped = serde_json::json!({ "metrics": result });
-                output::print_output(&wrapped, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_health_response_deserialization() {
-        let json = r#"{
-            "status": "healthy",
-            "database": "connected",
-            "version": "0.3.0"
-        }"#;
-
-        let value: serde_json::Value = serde_json::from_str(json).unwrap();
-        let result: HealthResponse = serde_json::from_value(value).unwrap();
-
-        assert_eq!(result.status, "healthy");
-        assert_eq!(result.database, Some("connected".to_string()));
-        assert_eq!(result.version, Some("0.3.0".to_string()));
-    }
-
-    #[test]
-    fn test_health_response_minimal() {
-        let json = r#"{"status": "healthy"}"#;
-
-        let value: serde_json::Value = serde_json::from_str(json).unwrap();
-        let result: HealthResponse = serde_json::from_value(value).unwrap();
-
-        assert_eq!(result.status, "healthy");
-        assert_eq!(result.database, None);
-        assert_eq!(result.version, None);
-    }
-
-    #[test]
-    fn test_health_response_unhealthy() {
-        let json = r#"{
-            "status": "unhealthy",
-            "database": "disconnected"
-        }"#;
-
-        let value: serde_json::Value = serde_json::from_str(json).unwrap();
-        let result: HealthResponse = serde_json::from_value(value).unwrap();
-
-        assert_eq!(result.status, "unhealthy");
-        assert_eq!(result.database, Some("disconnected".to_string()));
-    }
-}

hindsight-cli/src/commands/memory.rs

@@ -10,30 +10,8 @@ use crate::ui;
 
 // Import types from generated client
 use hindsight_client::types::{Budget, ChunkIncludeOptions, IncludeOptions, TagsMatch};
-use serde::Deserialize;
 use serde_json;
 
-// Local types for serde_json::Value deserialization
-#[derive(Debug, Deserialize)]
-struct MemoryUnitDetail {
-    id: String,
-    text: String,
-    #[serde(rename = "type")]
-    type_: Option<String>,
-    document_id: Option<String>,
-    context: Option<String>,
-    occurred_start: Option<String>,
-    occurred_end: Option<String>,
-    entities: Option<Vec<EntityRef>>,
-    tags: Option<Vec<String>>,
-}
-
-#[derive(Debug, Deserialize)]
-struct EntityRef {
-    id: String,
-    name: String,
-}
-
 // Helper function to parse budget string to Budget enum
 fn parse_budget(budget: &str) -> Budget {
     match budget.to_lowercase().as_str() {
@@ -43,183 +21,6 @@ fn parse_budget(budget: &str) -> Budget {
     }
 }
 
-/// List memory units with pagination and optional filters
-pub fn list(
-    client: &ApiClient,
-    bank_id: &str,
-    type_filter: Option<String>,
-    query: Option<String>,
-    limit: i64,
-    offset: i64,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching memories..."))
-    } else {
-        None
-    };
-
-    let response = client.list_memories(
-        bank_id,
-        type_filter.as_deref(),
-        query.as_deref(),
-        Some(limit),
-        Some(offset),
-        verbose,
-    );
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Memories: {} (showing {}-{})", bank_id, offset + 1, offset + result.items.len() as i64));
-
-                if result.items.is_empty() {
-                    println!("  {}", ui::dim("No memories found."));
-                } else {
-                    for item in &result.items {
-                        let fact_type = item.get("type")
-                            .and_then(|v| v.as_str())
-                            .unwrap_or("unknown");
-                        let type_t = match fact_type {
-                            "world" => 0.0,
-                            "experience" => 0.5,
-                            "opinion" => 1.0,
-                            _ => 0.5,
-                        };
-
-                        let id = item.get("id")
-                            .and_then(|v| v.as_str())
-                            .unwrap_or("unknown");
-
-                        println!(
-                            "  {} {}",
-                            ui::gradient(&format!("[{}]", fact_type.to_uppercase()), type_t),
-                            ui::dim(id)
-                        );
-
-                        // Truncate text if too long
-                        if let Some(text) = item.get("text").and_then(|v| v.as_str()) {
-                            let text_preview: String = text.chars().take(100).collect();
-                            let ellipsis = if text.len() > 100 { "..." } else { "" };
-                            println!("    {}{}", text_preview, ellipsis);
-                        }
-
-                        if let Some(doc_id) = item.get("document_id").and_then(|v| v.as_str()) {
-                            println!("    {} {}", ui::dim("doc:"), ui::dim(doc_id));
-                        }
-                        println!();
-                    }
-
-                    println!("  {} {} total", ui::dim("Total:"), result.total);
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get a specific memory unit by ID
-pub fn get(
-    client: &ApiClient,
-    bank_id: &str,
-    memory_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching memory..."))
-    } else {
-        None
-    };
-
-    let response = client.get_memory(bank_id, memory_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(value) => {
-            if output_format == OutputFormat::Pretty {
-                let result: MemoryUnitDetail = serde_json::from_value(value)
-                    .with_context(|| "Failed to parse memory response")?;
-
-                let fact_type = result.type_.as_deref().unwrap_or("unknown");
-                let type_t = match fact_type {
-                    "world" => 0.0,
-                    "experience" => 0.5,
-                    "opinion" => 1.0,
-                    _ => 0.5,
-                };
-
-                ui::print_section_header(&format!("Memory: {}", memory_id));
-
-                println!("  {} {}", ui::dim("Type:"), ui::gradient(&fact_type.to_uppercase(), type_t));
-                println!("  {} {}", ui::dim("ID:"), result.id);
-
-                if let Some(doc_id) = &result.document_id {
-                    println!("  {} {}", ui::dim("Document:"), doc_id);
-                }
-
-                if let Some(context) = &result.context {
-                    println!("  {} {}", ui::dim("Context:"), context);
-                }
-
-                println!();
-                println!("{}", ui::gradient_text("─── Content ───"));
-                println!();
-                println!("{}", result.text);
-
-                // Show temporal info if available
-                if result.occurred_start.is_some() || result.occurred_end.is_some() {
-                    println!();
-                    println!("{}", ui::gradient_text("─── Temporal ───"));
-                    if let Some(start) = &result.occurred_start {
-                        println!("  {} {}", ui::dim("Start:"), start);
-                    }
-                    if let Some(end) = &result.occurred_end {
-                        println!("  {} {}", ui::dim("End:"), end);
-                    }
-                }
-
-                // Show entities if available
-                if let Some(entities) = &result.entities {
-                    if !entities.is_empty() {
-                        println!();
-                        println!("{}", ui::gradient_text("─── Entities ───"));
-                        for entity in entities {
-                            println!("  • {} ({})", entity.name, entity.id);
-                        }
-                    }
-                }
-
-                // Show tags if available
-                if let Some(tags) = &result.tags {
-                    if !tags.is_empty() {
-                        println!();
-                        println!("{}", ui::gradient_text("─── Tags ───"));
-                        println!("  {}", tags.join(", "));
-                    }
-                }
-
-                println!();
-            } else {
-                output::print_output(&value, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
 // Helper function to check if a file has a text-based extension
 fn is_text_file(path: &std::path::Path) -> bool {
     const TEXT_EXTENSIONS: &[&str] = &[

hindsight-cli/src/commands/mental_model.rs

@@ -1,721 +0,0 @@
-//! Mental model commands for managing structured knowledge containers.
-
-use anyhow::{Context, Result};
-use std::fs;
-use std::path::PathBuf;
-
-use crate::api::ApiClient;
-use crate::output::{self, OutputFormat};
-use crate::ui;
-
-use hindsight_client::types;
-use serde::Deserialize;
-
-// Local types for serde_json::Value deserialization
-#[derive(Debug, Deserialize)]
-struct VersionListResponse {
-    versions: Vec<VersionItem>,
-}
-
-#[derive(Debug, Deserialize)]
-struct VersionItem {
-    version: i64,
-    created_at: String,
-    observations_count: Option<i64>,
-}
-
-#[derive(Debug, Deserialize)]
-struct VersionDetailResponse {
-    version: i64,
-    created_at: String,
-    observations: Option<Vec<ObservationData>>,
-}
-
-#[derive(Debug, Deserialize)]
-struct ObservationData {
-    title: String,
-    content: String,
-    trend: Option<String>,
-    evidence: Option<Vec<EvidenceData>>,
-}
-
-#[derive(Debug, Deserialize)]
-struct EvidenceData {
-    quote: String,
-}
-
-/// List mental models for a bank
-pub fn list(
-    client: &ApiClient,
-    bank_id: &str,
-    subtype: Option<String>,
-    tags: Option<Vec<String>>,
-    tags_match: Option<String>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching mental models..."))
-    } else {
-        None
-    };
-
-    let response = client.list_mental_models(
-        bank_id,
-        subtype.as_deref(),
-        tags,
-        tags_match.as_deref(),
-        verbose,
-    );
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Mental Models: {}", bank_id));
-
-                if result.items.is_empty() {
-                    println!("  {}", ui::dim("No mental models found."));
-                } else {
-                    for model in &result.items {
-                        let subtype_str = &model.subtype;
-                        let obs_count = model.observations.len();
-
-                        println!(
-                            "  {} {} {}",
-                            ui::gradient_start(&model.id),
-                            ui::dim(&format!("[{}]", subtype_str)),
-                            model.name
-                        );
-
-                        if !model.description.is_empty() {
-                            println!("    {}", ui::dim(&model.description));
-                        }
-
-                        println!(
-                            "    {} observations, v{}",
-                            obs_count,
-                            model.version
-                        );
-
-                        // Show freshness status
-                        if let Some(freshness) = &model.freshness {
-                            let status = if freshness.is_up_to_date {
-                                ui::gradient_start("up to date")
-                            } else {
-                                ui::gradient_end("needs refresh")
-                            };
-                            println!("    {}", status);
-                        }
-
-                        println!();
-                    }
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get a specific mental model
-pub fn get(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching mental model..."))
-    } else {
-        None
-    };
-
-    let response = client.get_mental_model(bank_id, model_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(model) => {
-            if output_format == OutputFormat::Pretty {
-                print_mental_model_detail(&model);
-            } else {
-                output::print_output(&model, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Create a new mental model
-pub fn create(
-    client: &ApiClient,
-    bank_id: &str,
-    name: &str,
-    description: &str,
-    subtype: Option<String>,
-    tags: Option<Vec<String>>,
-    observations_file: Option<PathBuf>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Creating mental model..."))
-    } else {
-        None
-    };
-
-    // Parse observations from file if provided
-    let observations = if let Some(path) = observations_file {
-        let content = fs::read_to_string(&path)
-            .with_context(|| format!("Failed to read observations file: {}", path.display()))?;
-        let obs: Vec<types::ObservationInput> = serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse observations JSON from: {}", path.display()))?;
-        Some(obs)
-    } else {
-        None
-    };
-
-    let request = types::CreateMentalModelRequest {
-        name: name.to_string(),
-        description: description.to_string(),
-        subtype: subtype.unwrap_or_else(|| "pinned".to_string()),
-        tags: tags.unwrap_or_default(),
-        observations,
-    };
-
-    let response = client.create_mental_model(bank_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(model) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' created successfully", model.id));
-                println!();
-                print_mental_model_detail(&model);
-            } else {
-                output::print_output(&model, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Delete a mental model
-pub fn delete(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    yes: bool,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    // Confirmation prompt unless -y flag is used
-    if !yes && output_format == OutputFormat::Pretty {
-        let message = format!(
-            "Are you sure you want to delete mental model '{}'? This cannot be undone.",
-            model_id
-        );
-
-        let confirmed = ui::prompt_confirmation(&message)?;
-
-        if !confirmed {
-            ui::print_info("Operation cancelled");
-            return Ok(());
-        }
-    }
-
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Deleting mental model..."))
-    } else {
-        None
-    };
-
-    let response = client.delete_mental_model(bank_id, model_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                if result.success {
-                    ui::print_success(&format!("Mental model '{}' deleted successfully", model_id));
-                } else {
-                    ui::print_error("Failed to delete mental model");
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Update a mental model's name or description
-pub fn update(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    name: Option<String>,
-    description: Option<String>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    if name.is_none() && description.is_none() {
-        anyhow::bail!("At least one of --name or --description must be provided");
-    }
-
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Updating mental model..."))
-    } else {
-        None
-    };
-
-    let request = types::UpdateMentalModelRequest { name, description };
-
-    let response = client.update_mental_model(bank_id, model_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(model) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' updated successfully", model_id));
-                println!();
-                print_mental_model_detail(&model);
-            } else {
-                output::print_output(&model, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Refresh all mental models (or filtered by subtype)
-pub fn refresh_all(
-    client: &ApiClient,
-    bank_id: &str,
-    subtype: Option<String>,
-    tags: Option<Vec<String>>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Submitting refresh request..."))
-    } else {
-        None
-    };
-
-    let response = client.refresh_mental_models(bank_id, subtype.as_deref(), tags, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success("Refresh operation submitted");
-                println!("  Operation ID: {}", result.operation_id);
-                println!("  Status: {}", result.status);
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Refresh a specific mental model
-pub fn refresh(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Submitting refresh request..."))
-    } else {
-        None
-    };
-
-    let response = client.refresh_mental_model(bank_id, model_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Refresh submitted for model '{}'", model_id));
-                println!("  Operation ID: {}", result.operation_id);
-                println!("  Status: {}", result.status);
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// List version history for a mental model
-pub fn versions(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching versions..."))
-    } else {
-        None
-    };
-
-    let response = client.list_mental_model_versions(bank_id, model_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(value) => {
-            if output_format == OutputFormat::Pretty {
-                let result: VersionListResponse = serde_json::from_value(value)
-                    .with_context(|| "Failed to parse version list response")?;
-
-                ui::print_section_header(&format!("Version History: {}", model_id));
-
-                if result.versions.is_empty() {
-                    println!("  {}", ui::dim("No versions found."));
-                } else {
-                    for version in &result.versions {
-                        let obs_count = version.observations_count.unwrap_or(0);
-                        println!(
-                            "  {} v{} - {} observations",
-                            ui::gradient_start(&format!("v{}", version.version)),
-                            version.version,
-                            obs_count
-                        );
-                        println!("    {}", ui::dim(&version.created_at));
-                    }
-                }
-            } else {
-                output::print_output(&value, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get a specific version of a mental model
-pub fn version(
-    client: &ApiClient,
-    bank_id: &str,
-    model_id: &str,
-    version_num: i64,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching version..."))
-    } else {
-        None
-    };
-
-    let response = client.get_mental_model_version(bank_id, model_id, version_num, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(value) => {
-            if output_format == OutputFormat::Pretty {
-                let result: VersionDetailResponse = serde_json::from_value(value)
-                    .with_context(|| "Failed to parse version response")?;
-
-                ui::print_section_header(&format!("{} v{}", model_id, version_num));
-
-                println!("  {} {}", ui::dim("Created:"), result.created_at);
-                println!();
-
-                if let Some(observations) = &result.observations {
-                    if observations.is_empty() {
-                        println!("  {}", ui::dim("No observations in this version."));
-                    } else {
-                        for (i, obs) in observations.iter().enumerate() {
-                            print_observation_data(i + 1, obs);
-                        }
-                    }
-                }
-            } else {
-                output::print_output(&value, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-// Helper function to print mental model details
-fn print_mental_model_detail(model: &types::MentalModelResponse) {
-    ui::print_section_header(&model.name);
-
-    let subtype_str = &model.subtype;
-    println!("  {} {}", ui::dim("ID:"), ui::gradient_start(&model.id));
-    println!("  {} {}", ui::dim("Subtype:"), subtype_str);
-    println!("  {} v{}", ui::dim("Version:"), model.version);
-
-    if !model.description.is_empty() {
-        println!("  {} {}", ui::dim("Description:"), &model.description);
-    }
-
-    if !model.tags.is_empty() {
-        println!("  {} {}", ui::dim("Tags:"), model.tags.join(", "));
-    }
-
-    // Freshness status
-    if let Some(freshness) = &model.freshness {
-        println!();
-        println!("{}", ui::gradient_text("─── Freshness ───"));
-        let status = if freshness.is_up_to_date {
-            ui::gradient_start("Up to date")
-        } else {
-            ui::gradient_end("Needs refresh")
-        };
-        println!("  {} {}", ui::dim("Status:"), status);
-
-        if let Some(last_refresh) = &freshness.last_refresh_at {
-            println!("  {} {}", ui::dim("Last refresh:"), last_refresh);
-        }
-
-        if freshness.memories_since_refresh > 0 {
-            println!("  {} {}", ui::dim("New memories:"), freshness.memories_since_refresh);
-        }
-
-        if !freshness.reasons.is_empty() {
-            println!("  {} {}", ui::dim("Reasons:"), freshness.reasons.join(", "));
-        }
-    }
-
-    // Observations
-    println!();
-    println!("{}", ui::gradient_text("─── Observations ───"));
-    println!();
-
-    if model.observations.is_empty() {
-        println!("  {}", ui::dim("No observations yet."));
-    } else {
-        for (i, obs) in model.observations.iter().enumerate() {
-            print_observation(i + 1, obs);
-        }
-    }
-
-    println!();
-}
-
-fn print_observation(index: usize, obs: &types::MentalModelObservationResponse) {
-    let trend_str = &obs.trend;
-    let trend_colored = match trend_str.as_str() {
-        "strengthening" => ui::gradient_start(trend_str),
-        "stable" => ui::gradient_mid(trend_str),
-        "weakening" | "stale" => ui::gradient_end(trend_str),
-        _ => trend_str.to_string(),
-    };
-
-    println!("  {}. {} {}", index, ui::gradient_mid(&obs.title), ui::dim(&format!("[{}]", trend_colored)));
-    println!("     {}", obs.content);
-
-    // Show evidence if available
-    if !obs.evidence.is_empty() {
-        println!("     {} evidence items:", ui::dim(&obs.evidence.len().to_string()));
-        for ev in obs.evidence.iter().take(2) {
-            // Show first 2 evidence items
-            let quote_preview: String = ev.quote.chars().take(60).collect();
-            let ellipsis = if ev.quote.len() > 60 { "..." } else { "" };
-            println!("       • \"{}{}\"", quote_preview, ellipsis);
-        }
-        if obs.evidence.len() > 2 {
-            println!("       {} more...", ui::dim(&format!("+ {}", obs.evidence.len() - 2)));
-        }
-    }
-
-    println!();
-}
-
-fn print_observation_data(index: usize, obs: &ObservationData) {
-    let trend_str = obs.trend.as_deref().unwrap_or("unknown");
-    let trend_colored = match trend_str {
-        "strengthening" => ui::gradient_start(trend_str),
-        "stable" => ui::gradient_mid(trend_str),
-        "weakening" | "stale" => ui::gradient_end(trend_str),
-        _ => trend_str.to_string(),
-    };
-
-    println!("  {}. {} {}", index, ui::gradient_mid(&obs.title), ui::dim(&format!("[{}]", trend_colored)));
-    println!("     {}", obs.content);
-
-    // Show evidence if available
-    if let Some(evidence) = &obs.evidence {
-        if !evidence.is_empty() {
-            println!("     {} evidence items:", ui::dim(&evidence.len().to_string()));
-            for ev in evidence.iter().take(2) {
-                // Show first 2 evidence items
-                let quote_preview: String = ev.quote.chars().take(60).collect();
-                let ellipsis = if ev.quote.len() > 60 { "..." } else { "" };
-                println!("       • \"{}{}\"", quote_preview, ellipsis);
-            }
-            if evidence.len() > 2 {
-                println!("       {} more...", ui::dim(&format!("+ {}", evidence.len() - 2)));
-            }
-        }
-    }
-
-    println!();
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_observation_input_serialization() {
-        let obs = types::ObservationInput {
-            title: "Test observation".to_string(),
-            content: "Test content".to_string(),
-        };
-        let json = serde_json::to_string(&obs).unwrap();
-        assert!(json.contains("Test observation"));
-        assert!(json.contains("Test content"));
-    }
-
-    #[test]
-    fn test_version_list_response_deserialization() {
-        let json = r#"{
-            "versions": [
-                {"version": 1, "created_at": "2024-01-10T10:00:00Z", "observations_count": 5},
-                {"version": 2, "created_at": "2024-01-15T10:00:00Z", "observations_count": 8}
-            ]
-        }"#;
-
-        let value: serde_json::Value = serde_json::from_str(json).unwrap();
-        let result: VersionListResponse = serde_json::from_value(value).unwrap();
-
-        assert_eq!(result.versions.len(), 2);
-        assert_eq!(result.versions[0].version, 1);
-        assert_eq!(result.versions[1].version, 2);
-        assert_eq!(result.versions[1].observations_count, Some(8));
-    }
-
-    #[test]
-    fn test_version_detail_response_deserialization() {
-        let json = r#"{
-            "version": 1,
-            "created_at": "2024-01-10T10:00:00Z",
-            "observations": [
-                {
-                    "title": "Test observation",
-                    "content": "Test content",
-                    "trend": "stable",
-                    "evidence": [{"quote": "test evidence"}]
-                }
-            ]
-        }"#;
-
-        let value: serde_json::Value = serde_json::from_str(json).unwrap();
-        let result: VersionDetailResponse = serde_json::from_value(value).unwrap();
-
-        assert_eq!(result.created_at, "2024-01-10T10:00:00Z");
-        let observations = result.observations.unwrap();
-        assert_eq!(observations.len(), 1);
-        assert_eq!(observations[0].title, "Test observation");
-        assert_eq!(observations[0].trend, Some("stable".to_string()));
-    }
-
-    #[test]
-    fn test_observation_data_deserialization() {
-        let json = r#"{
-            "title": "Test Title",
-            "content": "Test Content",
-            "trend": "strengthening",
-            "evidence": [
-                {"quote": "Evidence 1"},
-                {"quote": "Evidence 2"}
-            ]
-        }"#;
-
-        let result: ObservationData = serde_json::from_str(json).unwrap();
-
-        assert_eq!(result.title, "Test Title");
-        assert_eq!(result.content, "Test Content");
-        assert_eq!(result.trend, Some("strengthening".to_string()));
-        let evidence = result.evidence.unwrap();
-        assert_eq!(evidence.len(), 2);
-        assert_eq!(evidence[0].quote, "Evidence 1");
-    }
-
-    #[test]
-    fn test_create_mental_model_request() {
-        let request = types::CreateMentalModelRequest {
-            name: "Test Model".to_string(),
-            description: "A test model".to_string(),
-            subtype: "pinned".to_string(),
-            tags: vec!["test".to_string()],
-            observations: None,
-        };
-
-        let json = serde_json::to_string(&request).unwrap();
-        assert!(json.contains("Test Model"));
-        assert!(json.contains("pinned"));
-        assert!(json.contains("test"));
-    }
-
-    #[test]
-    fn test_update_mental_model_request() {
-        let request = types::UpdateMentalModelRequest {
-            name: Some("Updated Name".to_string()),
-            description: None,
-        };
-
-        let json = serde_json::to_string(&request).unwrap();
-        assert!(json.contains("Updated Name"));
-    }
-
-    #[test]
-    fn test_async_operation_submit_response_deserialization() {
-        let json = r#"{
-            "operation_id": "op-123",
-            "status": "pending"
-        }"#;
-
-        let result: types::AsyncOperationSubmitResponse = serde_json::from_str(json).unwrap();
-
-        assert_eq!(result.operation_id, "op-123");
-        assert_eq!(result.status, "pending");
-    }
-}

hindsight-cli/src/commands/mod.rs

@@ -1,10 +1,6 @@
 pub mod bank;
-pub mod chunk;
+pub mod memory;
 pub mod document;
 pub mod entity;
-pub mod explore;
-pub mod health;
-pub mod memory;
-pub mod mental_model;
 pub mod operation;
-pub mod tag;
+pub mod explore;

hindsight-cli/src/commands/operation.rs

@@ -47,55 +47,6 @@ pub fn list(
     }
 }
 
-/// Get the status of a specific operation
-pub fn get(
-    client: &ApiClient,
-    agent_id: &str,
-    operation_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching operation status..."))
-    } else {
-        None
-    };
-
-    let response = client.get_operation(agent_id, operation_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Operation: {}", operation_id));
-
-                use hindsight_client::types::Status;
-                let status_str = match &result.status {
-                    Status::Completed => ui::gradient_start("completed"),
-                    Status::Pending => ui::gradient_mid("pending"),
-                    Status::Failed => ui::gradient_end("failed"),
-                    Status::NotFound => ui::gradient_end("not_found"),
-                };
-
-                println!("  {} {}", ui::dim("Status:"), status_str);
-
-                if let Some(error) = &result.error_message {
-                    println!("  {} {}", ui::dim("Error:"), ui::gradient_end(error));
-                }
-
-                println!();
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
 pub fn cancel(
     client: &ApiClient,
     agent_id: &str,

hindsight-cli/src/commands/tag.rs

@@ -1,119 +0,0 @@
-//! Tag commands for listing tags in a memory bank.
-
-use anyhow::Result;
-
-use crate::api::ApiClient;
-use crate::output::{self, OutputFormat};
-use crate::ui;
-
-/// List tags in a bank
-pub fn list(
-    client: &ApiClient,
-    bank_id: &str,
-    query: Option<String>,
-    limit: i64,
-    offset: i64,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching tags..."))
-    } else {
-        None
-    };
-
-    let response = client.list_tags(
-        bank_id,
-        query.as_deref(),
-        Some(limit),
-        Some(offset),
-        verbose,
-    );
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Tags: {}", bank_id));
-
-                if result.items.is_empty() {
-                    println!("  {}", ui::dim("No tags found."));
-                } else {
-                    for (i, tag) in result.items.iter().enumerate() {
-                        let t = i as f32 / result.items.len().max(1) as f32;
-                        println!(
-                            "  {} {}",
-                            ui::gradient(&tag.tag, t),
-                            ui::dim(&format!("({})", tag.count))
-                        );
-                    }
-                    println!();
-                    println!("  {} {} total", ui::dim("Total:"), result.total);
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use hindsight_client::types::{ListTagsResponse, TagItem};
-
-    #[test]
-    fn test_tag_item_fields() {
-        // Verify TagItem has the expected fields
-        let tag = TagItem {
-            tag: "test-tag".to_string(),
-            count: 5,
-        };
-
-        assert_eq!(tag.tag, "test-tag");
-        assert_eq!(tag.count, 5);
-    }
-
-    #[test]
-    fn test_list_tags_response_deserialization() {
-        let json = r#"{
-            "items": [
-                {"tag": "user", "count": 10},
-                {"tag": "system", "count": 5}
-            ],
-            "limit": 100,
-            "offset": 0,
-            "total": 2
-        }"#;
-
-        let result: ListTagsResponse = serde_json::from_str(json).unwrap();
-
-        assert_eq!(result.items.len(), 2);
-        assert_eq!(result.items[0].tag, "user");
-        assert_eq!(result.items[0].count, 10);
-        assert_eq!(result.items[1].tag, "system");
-        assert_eq!(result.items[1].count, 5);
-        assert_eq!(result.total, 2);
-        assert_eq!(result.limit, 100);
-        assert_eq!(result.offset, 0);
-    }
-
-    #[test]
-    fn test_empty_tags_response() {
-        let json = r#"{
-            "items": [],
-            "limit": 100,
-            "offset": 0,
-            "total": 0
-        }"#;
-
-        let result: ListTagsResponse = serde_json::from_str(json).unwrap();
-
-        assert!(result.items.is_empty());
-        assert_eq!(result.total, 0);
-    }
-}

hindsight-cli/src/main.rs

@@ -67,18 +67,14 @@ fn get_before_help() -> &'static str {
 
 #[derive(Subcommand)]
 enum Commands {
-    /// Manage banks (list, create, update, profile, stats, mission, graph, delete)
+    /// Manage banks (list, profile, stats)
     #[command(subcommand)]
     Bank(BankCommands),
 
-    /// Manage memories (list, get, recall, reflect, retain, clear)
+    /// Manage memories (recall, reflect, retain, delete)
     #[command(subcommand)]
     Memory(MemoryCommands),
 
-    /// Manage mental models (list, get, create, update, delete, refresh, versions)
-    #[command(subcommand)]
-    MentalModel(MentalModelCommands),
-
     /// Manage documents (list, get, delete)
     #[command(subcommand)]
     Document(DocumentCommands),
@@ -87,24 +83,10 @@ enum Commands {
     #[command(subcommand)]
     Entity(EntityCommands),
 
-    /// Manage tags (list)
-    #[command(subcommand)]
-    Tag(TagCommands),
-
-    /// Manage chunks (get)
-    #[command(subcommand)]
-    Chunk(ChunkCommands),
-
-    /// Manage async operations (list, get, cancel)
+    /// Manage async operations (list, cancel)
     #[command(subcommand)]
     Operation(OperationCommands),
 
-    /// Check API health status
-    Health,
-
-    /// Get Prometheus metrics
-    Metrics,
-
     /// Interactive TUI explorer (k9s-style) for navigating banks, memories, entities, and performing recall/reflect
     #[command(alias = "tui")]
     Explore,
@@ -129,59 +111,7 @@ enum BankCommands {
     /// List all banks
     List,
 
-    /// Create a new bank
-    Create {
-        /// Bank ID
-        bank_id: String,
-
-        /// Bank name
-        #[arg(short = 'n', long)]
-        name: Option<String>,
-
-        /// Mission statement
-        #[arg(short = 'm', long)]
-        mission: Option<String>,
-
-        /// Skepticism trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        skepticism: Option<i64>,
-
-        /// Literalism trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        literalism: Option<i64>,
-
-        /// Empathy trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        empathy: Option<i64>,
-    },
-
-    /// Update bank properties (partial update)
-    Update {
-        /// Bank ID
-        bank_id: String,
-
-        /// Bank name
-        #[arg(short = 'n', long)]
-        name: Option<String>,
-
-        /// Mission statement
-        #[arg(short = 'm', long)]
-        mission: Option<String>,
-
-        /// Skepticism trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        skepticism: Option<i64>,
-
-        /// Literalism trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        literalism: Option<i64>,
-
-        /// Empathy trait (1-5)
-        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
-        empathy: Option<i64>,
-    },
-
-    /// Get bank disposition and profile
+    /// Get bank disposition and background
     Disposition {
         /// Bank ID
         bank_id: String,
@@ -202,17 +132,7 @@ enum BankCommands {
         name: String,
     },
 
-    /// Set bank mission
-    Mission {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mission statement
-        mission: String,
-    },
-
-    /// Set or merge bank background (deprecated: use mission instead)
-    #[command(hide = true)]
+    /// Set or merge bank background
     Background {
         /// Bank ID
         bank_id: String,
@@ -225,20 +145,6 @@ enum BankCommands {
         no_update_disposition: bool,
     },
 
-    /// Get memory graph data
-    Graph {
-        /// Bank ID
-        bank_id: String,
-
-        /// Filter by fact type (world, experience, opinion)
-        #[arg(short = 't', long)]
-        fact_type: Option<String>,
-
-        /// Maximum nodes to return
-        #[arg(short = 'l', long, default_value = "1000")]
-        limit: i64,
-    },
-
     /// Delete a bank and all its data
     Delete {
         /// Bank ID
@@ -252,37 +158,6 @@ enum BankCommands {
 
 #[derive(Subcommand)]
 enum MemoryCommands {
-    /// List memory units with pagination
-    List {
-        /// Bank ID
-        bank_id: String,
-
-        /// Filter by fact type (world, experience, opinion)
-        #[arg(short = 't', long)]
-        fact_type: Option<String>,
-
-        /// Full-text search query
-        #[arg(short = 'q', long)]
-        query: Option<String>,
-
-        /// Maximum number of results
-        #[arg(short = 'l', long, default_value = "100")]
-        limit: i64,
-
-        /// Offset for pagination
-        #[arg(short = 's', long, default_value = "0")]
-        offset: i64,
-    },
-
-    /// Get a specific memory unit by ID
-    Get {
-        /// Bank ID
-        bank_id: String,
-
-        /// Memory unit ID
-        memory_id: String,
-    },
-
     /// Recall memories using semantic search
     Recall {
         /// Bank ID
@@ -485,15 +360,6 @@ enum OperationCommands {
         bank_id: String,
     },
 
-    /// Get the status of a specific operation
-    Get {
-        /// Bank ID
-        bank_id: String,
-
-        /// Operation ID
-        operation_id: String,
-    },
-
     /// Cancel a pending async operation
     Cancel {
         /// Bank ID
@@ -504,164 +370,6 @@ enum OperationCommands {
     },
 }
 
-#[derive(Subcommand)]
-enum MentalModelCommands {
-    /// List mental models for a bank
-    List {
-        /// Bank ID
-        bank_id: String,
-
-        /// Filter by subtype (structural, emergent, pinned, learned, directive)
-        #[arg(long)]
-        subtype: Option<String>,
-
-        /// Filter by tags
-        #[arg(long, value_delimiter = ',')]
-        tags: Option<Vec<String>>,
-
-        /// Tag matching mode (any, all, any_strict, all_strict)
-        #[arg(long, default_value = "any")]
-        tags_match: Option<String>,
-    },
-
-    /// Get a specific mental model
-    Get {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-    },
-
-    /// Create a new mental model (pinned or directive subtype)
-    Create {
-        /// Bank ID
-        bank_id: String,
-
-        /// Model name
-        name: String,
-
-        /// Model description
-        description: String,
-
-        /// Subtype (pinned or directive)
-        #[arg(long, default_value = "pinned")]
-        subtype: Option<String>,
-
-        /// Tags for the model
-        #[arg(long, value_delimiter = ',')]
-        tags: Option<Vec<String>>,
-
-        /// Path to JSON file containing initial observations
-        #[arg(long)]
-        observations: Option<PathBuf>,
-    },
-
-    /// Update a mental model's name or description
-    Update {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-
-        /// New name
-        #[arg(long)]
-        name: Option<String>,
-
-        /// New description
-        #[arg(long)]
-        description: Option<String>,
-    },
-
-    /// Delete a mental model
-    Delete {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-
-        /// Skip confirmation prompt
-        #[arg(short = 'y', long)]
-        yes: bool,
-    },
-
-    /// Refresh all mental models (async operation)
-    RefreshAll {
-        /// Bank ID
-        bank_id: String,
-
-        /// Filter by subtype
-        #[arg(long)]
-        subtype: Option<String>,
-
-        /// Filter by tags
-        #[arg(long, value_delimiter = ',')]
-        tags: Option<Vec<String>>,
-    },
-
-    /// Refresh a specific mental model (async operation)
-    Refresh {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-    },
-
-    /// List version history for a mental model
-    Versions {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-    },
-
-    /// Get a specific version of a mental model
-    Version {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        model_id: String,
-
-        /// Version number
-        version: i64,
-    },
-}
-
-#[derive(Subcommand)]
-enum TagCommands {
-    /// List tags in a bank
-    List {
-        /// Bank ID
-        bank_id: String,
-
-        /// Wildcard search query (e.g., 'user:*')
-        #[arg(short = 'q', long)]
-        query: Option<String>,
-
-        /// Maximum number of results
-        #[arg(short = 'l', long, default_value = "100")]
-        limit: i64,
-
-        /// Offset for pagination
-        #[arg(short = 's', long, default_value = "0")]
-        offset: i64,
-    },
-}
-
-#[derive(Subcommand)]
-enum ChunkCommands {
-    /// Get a specific chunk by ID
-    Get {
-        /// Chunk ID
-        chunk_id: String,
-    },
-}
-
 fn main() {
     if let Err(_) = run() {
         std::process::exit(1);
@@ -704,45 +412,20 @@ fn run() -> Result<()> {
         Commands::Configure { .. } => unreachable!(), // Handled above
         Commands::Ui => unreachable!(), // Handled above
         Commands::Explore => commands::explore::run(&client),
-
-        // Health and Metrics
-        Commands::Health => commands::health::health(&client, verbose, output_format),
-        Commands::Metrics => commands::health::metrics(&client, verbose, output_format),
-
-        // Bank commands
         Commands::Bank(bank_cmd) => match bank_cmd {
             BankCommands::List => commands::bank::list(&client, verbose, output_format),
-            BankCommands::Create { bank_id, name, mission, skepticism, literalism, empathy } => {
-                commands::bank::create(&client, &bank_id, name, mission, skepticism, literalism, empathy, verbose, output_format)
-            }
-            BankCommands::Update { bank_id, name, mission, skepticism, literalism, empathy } => {
-                commands::bank::update(&client, &bank_id, name, mission, skepticism, literalism, empathy, verbose, output_format)
-            }
             BankCommands::Disposition { bank_id } => commands::bank::disposition(&client, &bank_id, verbose, output_format),
             BankCommands::Stats { bank_id } => commands::bank::stats(&client, &bank_id, verbose, output_format),
             BankCommands::Name { bank_id, name } => commands::bank::update_name(&client, &bank_id, &name, verbose, output_format),
-            BankCommands::Mission { bank_id, mission } => {
-                commands::bank::mission(&client, &bank_id, &mission, verbose, output_format)
-            }
             BankCommands::Background { bank_id, content, no_update_disposition } => {
                 commands::bank::update_background(&client, &bank_id, &content, no_update_disposition, verbose, output_format)
             }
-            BankCommands::Graph { bank_id, fact_type, limit } => {
-                commands::bank::graph(&client, &bank_id, fact_type, limit, verbose, output_format)
-            }
             BankCommands::Delete { bank_id, yes } => {
                 commands::bank::delete(&client, &bank_id, yes, verbose, output_format)
             }
         },
 
-        // Memory commands
         Commands::Memory(memory_cmd) => match memory_cmd {
-            MemoryCommands::List { bank_id, fact_type, query, limit, offset } => {
-                commands::memory::list(&client, &bank_id, fact_type, query, limit, offset, verbose, output_format)
-            }
-            MemoryCommands::Get { bank_id, memory_id } => {
-                commands::memory::get(&client, &bank_id, &memory_id, verbose, output_format)
-            }
             MemoryCommands::Recall { bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens } => {
                 commands::memory::recall(&client, &bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens, verbose, output_format)
             }
@@ -763,38 +446,6 @@ fn run() -> Result<()> {
             }
         },
 
-        // Mental Model commands
-        Commands::MentalModel(mm_cmd) => match mm_cmd {
-            MentalModelCommands::List { bank_id, subtype, tags, tags_match } => {
-                commands::mental_model::list(&client, &bank_id, subtype, tags, tags_match, verbose, output_format)
-            }
-            MentalModelCommands::Get { bank_id, model_id } => {
-                commands::mental_model::get(&client, &bank_id, &model_id, verbose, output_format)
-            }
-            MentalModelCommands::Create { bank_id, name, description, subtype, tags, observations } => {
-                commands::mental_model::create(&client, &bank_id, &name, &description, subtype, tags, observations, verbose, output_format)
-            }
-            MentalModelCommands::Update { bank_id, model_id, name, description } => {
-                commands::mental_model::update(&client, &bank_id, &model_id, name, description, verbose, output_format)
-            }
-            MentalModelCommands::Delete { bank_id, model_id, yes } => {
-                commands::mental_model::delete(&client, &bank_id, &model_id, yes, verbose, output_format)
-            }
-            MentalModelCommands::RefreshAll { bank_id, subtype, tags } => {
-                commands::mental_model::refresh_all(&client, &bank_id, subtype, tags, verbose, output_format)
-            }
-            MentalModelCommands::Refresh { bank_id, model_id } => {
-                commands::mental_model::refresh(&client, &bank_id, &model_id, verbose, output_format)
-            }
-            MentalModelCommands::Versions { bank_id, model_id } => {
-                commands::mental_model::versions(&client, &bank_id, &model_id, verbose, output_format)
-            }
-            MentalModelCommands::Version { bank_id, model_id, version } => {
-                commands::mental_model::version(&client, &bank_id, &model_id, version, verbose, output_format)
-            }
-        },
-
-        // Document commands
         Commands::Document(doc_cmd) => match doc_cmd {
             DocumentCommands::List { bank_id, query, limit, offset } => {
                 commands::document::list(&client, &bank_id, query, limit, offset, verbose, output_format)
@@ -807,7 +458,6 @@ fn run() -> Result<()> {
             }
         },
 
-        // Entity commands
         Commands::Entity(entity_cmd) => match entity_cmd {
             EntityCommands::List { bank_id, limit } => {
                 commands::entity::list(&client, &bank_id, limit, verbose, output_format)
@@ -820,28 +470,10 @@ fn run() -> Result<()> {
             }
         },
 
-        // Tag commands
-        Commands::Tag(tag_cmd) => match tag_cmd {
-            TagCommands::List { bank_id, query, limit, offset } => {
-                commands::tag::list(&client, &bank_id, query, limit, offset, verbose, output_format)
-            }
-        },
-
-        // Chunk commands
-        Commands::Chunk(chunk_cmd) => match chunk_cmd {
-            ChunkCommands::Get { chunk_id } => {
-                commands::chunk::get(&client, &chunk_id, verbose, output_format)
-            }
-        },
-
-        // Operation commands
         Commands::Operation(op_cmd) => match op_cmd {
             OperationCommands::List { bank_id } => {
                 commands::operation::list(&client, &bank_id, verbose, output_format)
             }
-            OperationCommands::Get { bank_id, operation_id } => {
-                commands::operation::get(&client, &bank_id, &operation_id, verbose, output_format)
-            }
             OperationCommands::Cancel { bank_id, operation_id } => {
                 commands::operation::cancel(&client, &bank_id, &operation_id, verbose, output_format)
             }

hindsight-cli/tests/cli_integration.rs

@@ -1,483 +0,0 @@
-//! Integration tests for the hindsight CLI commands.
-//!
-//! These tests require a running hindsight API server.
-//! Set HINDSIGHT_API_URL environment variable to point to the server.
-//! Tests will be skipped if the server is not available.
-
-use std::env;
-use std::process::Command;
-
-/// Check if the API server is available
-fn server_available() -> bool {
-    let api_url = env::var("HINDSIGHT_API_URL").unwrap_or_else(|_| "http://localhost:8080".to_string());
-    let health_url = format!("{}/health", api_url);
-
-    match reqwest::blocking::get(&health_url) {
-        Ok(resp) => resp.status().is_success(),
-        Err(_) => false,
-    }
-}
-
-/// Helper macro to skip tests when server is not available
-macro_rules! skip_if_no_server {
-    () => {
-        if !server_available() {
-            eprintln!("Skipping test: API server not available");
-            return;
-        }
-    };
-}
-
-/// Get the path to the hindsight binary
-fn hindsight_binary() -> String {
-    env::var("CARGO_BIN_EXE_hindsight")
-        .unwrap_or_else(|_| {
-            // Try common locations
-            let target_debug = "./target/debug/hindsight";
-            let target_release = "./target/release/hindsight";
-            if std::path::Path::new(target_debug).exists() {
-                target_debug.to_string()
-            } else if std::path::Path::new(target_release).exists() {
-                target_release.to_string()
-            } else {
-                "hindsight".to_string()
-            }
-        })
-}
-
-/// Test bank ID for integration tests - each test needs a unique bank ID
-/// to avoid parallel test interference
-fn test_bank_id(test_name: &str) -> String {
-    format!("cli-test-{}-{}", test_name, std::process::id())
-}
-
-/// Run a hindsight CLI command
-fn run_hindsight(args: &[&str]) -> std::process::Output {
-    let api_url = env::var("HINDSIGHT_API_URL").unwrap_or_else(|_| "http://localhost:8080".to_string());
-
-    Command::new(hindsight_binary())
-        .env("HINDSIGHT_API_URL", &api_url)
-        .args(args)
-        .output()
-        .expect("Failed to execute hindsight command")
-}
-
-#[test]
-fn test_health_check() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["health"]);
-
-    // Should succeed or fail gracefully
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Either succeeded with "healthy" output or has a reasonable error
-    if output.status.success() {
-        // Note: output may contain ANSI color codes, so check for key text
-        assert!(
-            stdout.contains("healthy") || stdout.contains("Health") || stdout.contains("status"),
-            "Expected health check output, got: {} / {}",
-            stdout,
-            stderr
-        );
-    }
-}
-
-#[test]
-fn test_health_check_json_output() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["health", "-o", "json"]);
-
-    if output.status.success() {
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        // Should be valid JSON
-        let result: serde_json::Value = serde_json::from_str(&stdout)
-            .expect(&format!("Expected valid JSON output, got: {}", stdout));
-
-        // Should have status field
-        assert!(result.get("status").is_some(), "Expected status field in health response");
-    }
-}
-
-#[test]
-fn test_bank_list() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["bank", "list"]);
-
-    // Should succeed (even if no banks exist)
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    assert!(
-        output.status.success(),
-        "Bank list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-}
-
-#[test]
-fn test_bank_list_json_output() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["bank", "list", "-o", "json"]);
-
-    if output.status.success() {
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        // Should be valid JSON array
-        let _result: serde_json::Value = serde_json::from_str(&stdout)
-            .expect(&format!("Expected valid JSON output, got: {}", stdout));
-    }
-}
-
-#[test]
-fn test_bank_create_and_delete() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("create-delete");
-
-    // Create a bank
-    let output = run_hindsight(&[
-        "bank", "create",
-        &bank_id,
-        "--name", "Test Bank",
-        "--mission", "A test bank for CLI integration tests",
-    ]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Bank might already exist, which is OK
-    let created = output.status.success();
-
-    // Get bank disposition
-    let output = run_hindsight(&["bank", "disposition", &bank_id]);
-    if created {
-        assert!(
-            output.status.success(),
-            "Bank disposition command failed: {} / {}",
-            String::from_utf8_lossy(&output.stdout),
-            String::from_utf8_lossy(&output.stderr)
-        );
-    }
-
-    // Clean up: delete the bank
-    let output = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-    // Deletion should succeed
-    if created {
-        assert!(
-            output.status.success(),
-            "Bank delete command failed: {} / {}",
-            String::from_utf8_lossy(&output.stdout),
-            String::from_utf8_lossy(&output.stderr)
-        );
-    }
-}
-
-#[test]
-fn test_memory_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("memory-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List memories (should be empty for new bank)
-    let output = run_hindsight(&["memory", "list", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed (even if empty)
-    assert!(
-        output.status.success(),
-        "Memory list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_mental_model_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("mm-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List mental models
-    let output = run_hindsight(&["mental-model", "list", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed
-    assert!(
-        output.status.success(),
-        "Mental model list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_mental_model_create_and_delete() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("mm-create");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Create a mental model
-    let output = run_hindsight(&[
-        "mental-model", "create",
-        &bank_id,
-        "Test Model",
-        "A test mental model",
-    ]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // The create command should succeed
-    assert!(
-        output.status.success(),
-        "Mental model create failed: stdout={}, stderr={}",
-        stdout,
-        stderr
-    );
-
-    // Verify it's in the list
-    let output = run_hindsight(&["mental-model", "list", &bank_id, "-o", "json"]);
-    let stdout = String::from_utf8_lossy(&output.stdout);
-
-    assert!(
-        output.status.success(),
-        "Mental model list failed: {}",
-        stdout
-    );
-
-    // Parse JSON and verify model exists
-    if let Ok(result) = serde_json::from_str::<serde_json::Value>(&stdout) {
-        if let Some(items) = result.get("items").and_then(|v| v.as_array()) {
-            // Check if any model has the name "Test Model"
-            let found = items.iter().any(|item| {
-                item.get("name").and_then(|v| v.as_str()) == Some("Test Model")
-            });
-            assert!(found, "Expected to find 'Test Model' in mental models list: {}", stdout);
-        }
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_tag_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("tag-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List tags
-    let output = run_hindsight(&["tag", "list", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed (even if no tags)
-    assert!(
-        output.status.success(),
-        "Tag list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_entity_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("entity-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List entities
-    let output = run_hindsight(&["entity", "list", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed (even if no entities)
-    assert!(
-        output.status.success(),
-        "Entity list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_operation_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("op-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List operations
-    let output = run_hindsight(&["operation", "list", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed (even if no operations)
-    assert!(
-        output.status.success(),
-        "Operation list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_bank_stats() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("bank-stats");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Get stats
-    let output = run_hindsight(&["bank", "stats", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed
-    assert!(
-        output.status.success(),
-        "Bank stats command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_bank_graph() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("bank-graph");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Get graph
-    let output = run_hindsight(&["bank", "graph", &bank_id]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed (even if empty graph)
-    assert!(
-        output.status.success(),
-        "Bank graph command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_bank_update() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("bank-update");
-
-    // Create the bank first
-    let output = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    if output.status.success() {
-        // Update the bank
-        let output = run_hindsight(&[
-            "bank", "update", &bank_id,
-            "--name", "Updated Test Bank",
-        ]);
-
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let stderr = String::from_utf8_lossy(&output.stderr);
-
-        assert!(
-            output.status.success(),
-            "Bank update command failed: {} / {}",
-            stdout,
-            stderr
-        );
-
-        // Verify the update
-        let output = run_hindsight(&["bank", "disposition", &bank_id, "-o", "json"]);
-        if output.status.success() {
-            let stdout = String::from_utf8_lossy(&output.stdout);
-            let result: serde_json::Value = serde_json::from_str(&stdout).unwrap();
-            assert_eq!(
-                result.get("name").and_then(|v| v.as_str()),
-                Some("Updated Test Bank")
-            );
-        }
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_json_yaml_output_formats() {
-    skip_if_no_server!();
-
-    // Test JSON output for bank list
-    let output = run_hindsight(&["bank", "list", "-o", "json"]);
-    if output.status.success() {
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let _: serde_json::Value = serde_json::from_str(&stdout)
-            .expect("Expected valid JSON for bank list");
-    }
-
-    // Test YAML output for bank list
-    let output = run_hindsight(&["bank", "list", "-o", "yaml"]);
-    if output.status.success() {
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let _: serde_yaml::Value = serde_yaml::from_str(&stdout)
-            .expect("Expected valid YAML for bank list");
-    }
-}

hindsight-clients/python/hindsight_client/hindsight_client.py

@@ -6,11 +6,11 @@ easy-to-use interface on top of the auto-generated OpenAPI client.
 """
 
 import asyncio
-from typing import Optional, List, Dict, Any, Literal
+from typing import Optional, List, Dict, Any
 from datetime import datetime
 
 import hindsight_client_api
-from hindsight_client_api.api import memory_api, banks_api, mental_models_api
+from hindsight_client_api.api import memory_api, banks_api
 from hindsight_client_api.models import (
     recall_request,
     retain_request,
@@ -23,9 +23,6 @@ from hindsight_client_api.models.recall_result import RecallResult
 from hindsight_client_api.models.reflect_response import ReflectResponse
 from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
 from hindsight_client_api.models.bank_profile_response import BankProfileResponse
-from hindsight_client_api.models.mental_model_response import MentalModelResponse
-from hindsight_client_api.models.mental_model_list_response import MentalModelListResponse
-from hindsight_client_api.models.async_operation_submit_response import AsyncOperationSubmitResponse
 
 
 def _run_async(coro):
@@ -81,7 +78,6 @@ class Hindsight:
             self._api_client.set_default_header("Authorization", f"Bearer {api_key}")
         self._memory_api = memory_api.MemoryApi(self._api_client)
         self._banks_api = banks_api.BanksApi(self._api_client)
-        self._mental_models_api = mental_models_api.MentalModelsApi(self._api_client)
 
     def __enter__(self):
         """Context manager entry."""
@@ -336,256 +332,6 @@ class Hindsight:
 
         return _run_async(self._banks_api.create_or_update_bank(bank_id, request_obj))
 
-    def set_mission(
-        self,
-        bank_id: str,
-        mission: str,
-    ) -> BankProfileResponse:
-        """
-        Set or update the mission for a memory bank.
-
-        Args:
-            bank_id: The memory bank ID
-            mission: The mission text describing the agent's purpose
-
-        Returns:
-            BankProfileResponse with updated bank profile
-        """
-        from hindsight_client_api.models import create_bank_request
-
-        request_obj = create_bank_request.CreateBankRequest(mission=mission)
-        return _run_async(self._banks_api.create_or_update_bank(bank_id, request_obj))
-
-    def list_mental_models(
-        self,
-        bank_id: str,
-        subtype: Optional[Literal["structural", "emergent", "pinned", "learned", "directive"]] = None,
-        tags: Optional[List[str]] = None,
-        tags_match: Optional[Literal["any", "all", "exact"]] = None,
-    ) -> MentalModelListResponse:
-        """
-        List mental models for a bank.
-
-        Args:
-            bank_id: The memory bank ID
-            subtype: Optional filter by subtype (structural, emergent, pinned, learned, directive)
-            tags: Optional list of tags to filter by
-            tags_match: How to match tags - 'any' (OR), 'all' (AND), or 'exact'
-
-        Returns:
-            MentalModelListResponse with list of mental models
-        """
-        return _run_async(self._mental_models_api.list_mental_models(
-            bank_id=bank_id,
-            subtype=subtype,
-            tags=tags,
-            tags_match=tags_match,
-        ))
-
-    def get_mental_model(
-        self,
-        bank_id: str,
-        model_id: str,
-    ) -> MentalModelResponse:
-        """
-        Get a specific mental model by ID.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID
-
-        Returns:
-            MentalModelResponse with full mental model details including observations
-        """
-        return _run_async(self._mental_models_api.get_mental_model(
-            bank_id=bank_id,
-            model_id=model_id,
-        ))
-
-    def create_mental_model(
-        self,
-        bank_id: str,
-        name: str,
-        description: str,
-        subtype: Literal["pinned", "directive"] = "pinned",
-        observations: Optional[List[Dict[str, str]]] = None,
-        tags: Optional[List[str]] = None,
-    ) -> MentalModelResponse:
-        """
-        Create a mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            name: Human-readable name for the mental model
-            description: One-liner description for quick scanning
-            subtype: Type of mental model - 'pinned' (LLM-generated observations) or 'directive' (user-provided observations)
-            observations: For directives only - list of observations with 'title' and 'content' keys
-            tags: Optional list of tags for scoped visibility
-
-        Returns:
-            MentalModelResponse with created mental model
-        """
-        from hindsight_client_api.models.create_mental_model_request import CreateMentalModelRequest
-        from hindsight_client_api.models.observation_input import ObservationInput
-
-        obs_list = None
-        if observations:
-            obs_list = [ObservationInput(title=o.get("title", ""), content=o.get("content", "")) for o in observations]
-
-        request_obj = CreateMentalModelRequest(
-            name=name,
-            description=description,
-            subtype=subtype,
-            observations=obs_list,
-            tags=tags or [],
-        )
-        return _run_async(self._mental_models_api.create_mental_model(
-            bank_id=bank_id,
-            create_mental_model_request=request_obj,
-        ))
-
-    def update_mental_model(
-        self,
-        bank_id: str,
-        model_id: str,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-    ) -> MentalModelResponse:
-        """
-        Update a mental model's name and/or description.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID
-            name: Optional new name
-            description: Optional new description
-
-        Returns:
-            MentalModelResponse with updated mental model
-        """
-        from hindsight_client_api.models.update_mental_model_request import UpdateMentalModelRequest
-
-        request_obj = UpdateMentalModelRequest(
-            name=name,
-            description=description,
-        )
-        return _run_async(self._mental_models_api.update_mental_model(
-            bank_id=bank_id,
-            model_id=model_id,
-            update_mental_model_request=request_obj,
-        ))
-
-    def delete_mental_model(
-        self,
-        bank_id: str,
-        model_id: str,
-    ):
-        """
-        Delete a mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID
-
-        Returns:
-            DeleteResponse confirming deletion
-        """
-        return _run_async(self._mental_models_api.delete_mental_model(
-            bank_id=bank_id,
-            model_id=model_id,
-        ))
-
-    def refresh_mental_models(
-        self,
-        bank_id: str,
-        subtype: Optional[Literal["structural", "emergent", "pinned", "learned"]] = None,
-        tags: Optional[List[str]] = None,
-    ) -> AsyncOperationSubmitResponse:
-        """
-        Submit a background job to refresh mental models for a bank.
-
-        Args:
-            bank_id: The memory bank ID
-            subtype: Optional - only refresh models of this subtype
-            tags: Optional - tags to apply to newly created mental models
-
-        Returns:
-            AsyncOperationSubmitResponse with operation_id to track progress
-        """
-        from hindsight_client_api.models.refresh_mental_models_request import RefreshMentalModelsRequest
-
-        request_obj = RefreshMentalModelsRequest(
-            subtype=subtype,
-            tags=tags,
-        )
-        return _run_async(self._mental_models_api.refresh_mental_models(
-            bank_id=bank_id,
-            refresh_mental_models_request=request_obj,
-        ))
-
-    def refresh_mental_model(
-        self,
-        bank_id: str,
-        model_id: str,
-    ) -> AsyncOperationSubmitResponse:
-        """
-        Submit a background job to refresh content for a specific mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID to refresh
-
-        Returns:
-            AsyncOperationSubmitResponse with operation_id to track progress
-        """
-        return _run_async(self._mental_models_api.refresh_mental_model(
-            bank_id=bank_id,
-            model_id=model_id,
-        ))
-
-    def list_mental_model_versions(
-        self,
-        bank_id: str,
-        model_id: str,
-    ):
-        """
-        List all saved versions of a mental model's observations.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID
-
-        Returns:
-            List of version objects ordered by version descending
-        """
-        return _run_async(self._mental_models_api.list_mental_model_versions(
-            bank_id=bank_id,
-            model_id=model_id,
-        ))
-
-    def get_mental_model_version(
-        self,
-        bank_id: str,
-        model_id: str,
-        version: int,
-    ):
-        """
-        Get observations from a specific version of a mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            model_id: The mental model ID
-            version: The version number
-
-        Returns:
-            Version object with observations at that version
-        """
-        return _run_async(self._mental_models_api.get_mental_model_version(
-            bank_id=bank_id,
-            model_id=model_id,
-            version=version,
-        ))
-
     # Async methods (native async, no _run_async wrapper)
 
     async def aretain_batch(

hindsight-clients/python/tests/test_main_operations.py

@@ -544,205 +544,3 @@ class TestDeleteBank:
         # Verify bank data is deleted - memories should be gone
         memories = client.list_memories(bank_id=bank_id)
         assert memories.total == 0
-
-
-class TestMentalModels:
-    """Tests for mental model operations."""
-
-    def test_set_mission(self, client, bank_id):
-        """Test setting a bank's mission."""
-        response = client.set_mission(
-            bank_id=bank_id,
-            mission="Be a helpful PM tracking sprint progress and team capacity",
-        )
-
-        assert response is not None
-        assert response.bank_id == bank_id
-        assert response.mission == "Be a helpful PM tracking sprint progress and team capacity"
-
-    def test_create_pinned_mental_model(self, client, bank_id):
-        """Test creating a pinned mental model."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        response = client.create_mental_model(
-            bank_id=bank_id,
-            name="Product Roadmap",
-            description="Track product priorities and feature decisions",
-            subtype="pinned",
-            tags=["test"],
-        )
-
-        assert response is not None
-        assert response.name == "Product Roadmap"
-        assert response.description == "Track product priorities and feature decisions"
-        assert response.subtype == "pinned"
-
-    def test_create_directive_mental_model(self, client, bank_id):
-        """Test creating a directive mental model with observations."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        response = client.create_mental_model(
-            bank_id=bank_id,
-            name="Response Guidelines",
-            description="Rules for responding to users",
-            subtype="directive",
-            observations=[
-                {"title": "Always be polite", "content": "All responses must be courteous and professional"},
-                {"title": "Never share private info", "content": "Do not reveal internal details or user data"},
-            ],
-            tags=["test"],
-        )
-
-        assert response is not None
-        assert response.name == "Response Guidelines"
-        assert response.subtype == "directive"
-        assert response.observations is not None
-        assert len(response.observations) == 2
-
-    def test_list_mental_models(self, client, bank_id):
-        """Test listing mental models."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        client.create_mental_model(
-            bank_id=bank_id,
-            name="Test Model",
-            description="A test mental model",
-            subtype="pinned",
-        )
-
-        response = client.list_mental_models(bank_id=bank_id)
-
-        assert response is not None
-        assert response.items is not None
-        assert len(response.items) >= 1
-
-    def test_get_mental_model(self, client, bank_id):
-        """Test getting a specific mental model."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        created = client.create_mental_model(
-            bank_id=bank_id,
-            name="Retrieve Test Model",
-            description="A model to retrieve",
-            subtype="pinned",
-        )
-
-        response = client.get_mental_model(
-            bank_id=bank_id,
-            model_id=created.id,
-        )
-
-        assert response is not None
-        assert response.id == created.id
-        assert response.name == "Retrieve Test Model"
-
-    def test_update_mental_model(self, client, bank_id):
-        """Test updating a mental model."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        created = client.create_mental_model(
-            bank_id=bank_id,
-            name="Update Test Model",
-            description="Original description",
-            subtype="pinned",
-        )
-
-        response = client.update_mental_model(
-            bank_id=bank_id,
-            model_id=created.id,
-            name="Updated Model Name",
-            description="Updated description",
-        )
-
-        assert response is not None
-        assert response.name == "Updated Model Name"
-        assert response.description == "Updated description"
-
-    def test_delete_mental_model(self, client, bank_id):
-        """Test deleting a mental model."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        created = client.create_mental_model(
-            bank_id=bank_id,
-            name="Delete Test Model",
-            description="A model to delete",
-            subtype="pinned",
-        )
-
-        response = client.delete_mental_model(
-            bank_id=bank_id,
-            model_id=created.id,
-        )
-
-        assert response is not None
-        assert response.success is True
-
-    def test_refresh_mental_models(self, client, bank_id):
-        """Test refreshing all mental models (async operation)."""
-        # Set mission first (required for refresh) - this also creates the bank
-        client.set_mission(
-            bank_id=bank_id,
-            mission="Track team progress and decisions",
-        )
-
-        response = client.refresh_mental_models(
-            bank_id=bank_id,
-            tags=["test"],
-        )
-
-        assert response is not None
-        assert response.operation_id is not None
-        assert response.status == "queued"
-
-    def test_refresh_mental_model(self, client, bank_id):
-        """Test refreshing a single mental model (async operation)."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        created = client.create_mental_model(
-            bank_id=bank_id,
-            name="Refresh Single Test",
-            description="A model to refresh individually",
-            subtype="pinned",
-        )
-
-        response = client.refresh_mental_model(
-            bank_id=bank_id,
-            model_id=created.id,
-        )
-
-        assert response is not None
-        assert response.operation_id is not None
-        assert response.status == "queued"
-
-    def test_list_mental_model_versions(self, client, bank_id):
-        """Test listing mental model versions."""
-        # Create bank first (required for mental models)
-        client.create_bank(bank_id=bank_id)
-
-        # Create a model first
-        created = client.create_mental_model(
-            bank_id=bank_id,
-            name="Versions Test Model",
-            description="A model to test version history",
-            subtype="pinned",
-        )
-
-        response = client.list_mental_model_versions(
-            bank_id=bank_id,
-            model_id=created.id,
-        )
-
-        # Newly created model should have version history
-        assert response is not None

hindsight-clients/typescript/README.md

@@ -23,7 +23,7 @@ await client.retain('my-bank', 'Alice works at Google in Mountain View.');
 // Recall memories
 const results = await client.recall('my-bank', 'Where does Alice work?');
 
-// Reflect with reasoning and mental models
+// Reflect and get an opinion
 const response = await client.reflect('my-bank', 'What do you think about Alice\'s career?');
 ```
 

hindsight-clients/typescript/src/index.ts

@@ -40,10 +40,6 @@ import type {
     BankProfileResponse,
     CreateBankRequest,
     Budget,
-    MentalModelResponse,
-    MentalModelListResponse,
-    AsyncOperationSubmitResponse,
-    ObservationInput,
 } from '../generated/types.gen';
 
 export interface HindsightClientOptions {
@@ -312,176 +308,6 @@ export class HindsightClient {
 
         return this.validateResponse(response, 'getBankProfile');
     }
-
-    /**
-     * Set or update the mission for a memory bank.
-     */
-    async setMission(bankId: string, mission: string): Promise<BankProfileResponse> {
-        const response = await sdk.createOrUpdateBank({
-            client: this.client,
-            path: { bank_id: bankId },
-            body: { mission },
-        });
-
-        return this.validateResponse(response, 'setMission');
-    }
-
-    /**
-     * List mental models for a bank.
-     */
-    async listMentalModels(
-        bankId: string,
-        options?: {
-            subtype?: 'structural' | 'emergent' | 'pinned' | 'learned' | 'directive';
-            tags?: string[];
-            tagsMatch?: 'any' | 'all' | 'exact';
-        }
-    ): Promise<MentalModelListResponse> {
-        const response = await sdk.listMentalModels({
-            client: this.client,
-            path: { bank_id: bankId },
-            query: {
-                subtype: options?.subtype,
-                tags: options?.tags,
-                tags_match: options?.tagsMatch,
-            },
-        });
-
-        return this.validateResponse(response, 'listMentalModels');
-    }
-
-    /**
-     * Get a specific mental model by ID.
-     */
-    async getMentalModel(bankId: string, modelId: string): Promise<MentalModelResponse> {
-        const response = await sdk.getMentalModel({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId },
-        });
-
-        return this.validateResponse(response, 'getMentalModel');
-    }
-
-    /**
-     * Create a mental model.
-     */
-    async createMentalModel(
-        bankId: string,
-        options: {
-            name: string;
-            description: string;
-            subtype?: 'pinned' | 'directive';
-            observations?: Array<{ title: string; content: string }>;
-            tags?: string[];
-        }
-    ): Promise<MentalModelResponse> {
-        const response = await sdk.createMentalModel({
-            client: this.client,
-            path: { bank_id: bankId },
-            body: {
-                name: options.name,
-                description: options.description,
-                subtype: options.subtype,
-                observations: options.observations,
-                tags: options.tags,
-            },
-        });
-
-        return this.validateResponse(response, 'createMentalModel');
-    }
-
-    /**
-     * Update a mental model's name and/or description.
-     */
-    async updateMentalModel(
-        bankId: string,
-        modelId: string,
-        options: {
-            name?: string;
-            description?: string;
-        }
-    ): Promise<MentalModelResponse> {
-        const response = await sdk.updateMentalModel({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId },
-            body: {
-                name: options.name,
-                description: options.description,
-            },
-        });
-
-        return this.validateResponse(response, 'updateMentalModel');
-    }
-
-    /**
-     * Delete a mental model.
-     */
-    async deleteMentalModel(bankId: string, modelId: string): Promise<void> {
-        const response = await sdk.deleteMentalModel({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId },
-        });
-
-        this.validateResponse(response, 'deleteMentalModel');
-    }
-
-    /**
-     * Submit a background job to refresh mental models for a bank.
-     */
-    async refreshMentalModels(
-        bankId: string,
-        options?: {
-            subtype?: 'structural' | 'emergent' | 'pinned' | 'learned';
-            tags?: string[];
-        }
-    ): Promise<AsyncOperationSubmitResponse> {
-        const response = await sdk.refreshMentalModels({
-            client: this.client,
-            path: { bank_id: bankId },
-            body: {
-                subtype: options?.subtype,
-                tags: options?.tags,
-            },
-        });
-
-        return this.validateResponse(response, 'refreshMentalModels');
-    }
-
-    /**
-     * Submit a background job to refresh content for a specific mental model.
-     */
-    async refreshMentalModel(bankId: string, modelId: string): Promise<AsyncOperationSubmitResponse> {
-        const response = await sdk.refreshMentalModel({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId },
-        });
-
-        return this.validateResponse(response, 'refreshMentalModel');
-    }
-
-    /**
-     * List all saved versions of a mental model's observations.
-     */
-    async listMentalModelVersions(bankId: string, modelId: string): Promise<unknown> {
-        const response = await sdk.listMentalModelVersions({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId },
-        });
-
-        return this.validateResponse(response, 'listMentalModelVersions');
-    }
-
-    /**
-     * Get observations from a specific version of a mental model.
-     */
-    async getMentalModelVersion(bankId: string, modelId: string, version: number): Promise<unknown> {
-        const response = await sdk.getMentalModelVersion({
-            client: this.client,
-            path: { bank_id: bankId, model_id: modelId, version },
-        });
-
-        return this.validateResponse(response, 'getMentalModelVersion');
-    }
 }
 
 // Re-export types for convenience
@@ -497,10 +323,6 @@ export type {
     BankProfileResponse,
     CreateBankRequest,
     Budget,
-    MentalModelResponse,
-    MentalModelListResponse,
-    AsyncOperationSubmitResponse,
-    ObservationInput,
 };
 
 // Also export low-level SDK functions for advanced usage

hindsight-clients/typescript/tests/main_operations.test.ts

@@ -412,186 +412,3 @@ describe('TestDeleteBank', () => {
         expect(memories.total).toBe(0);
     });
 });
-
-describe('TestMentalModels', () => {
-    test('set mission', async () => {
-        const bankId = randomBankId();
-        const response = await client.setMission(
-            bankId,
-            'Be a helpful PM tracking sprint progress and team capacity'
-        );
-
-        expect(response).not.toBeNull();
-        expect(response.bank_id).toBe(bankId);
-        expect(response.mission).toBe('Be a helpful PM tracking sprint progress and team capacity');
-    });
-
-    test('create pinned mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        const response = await client.createMentalModel(bankId, {
-            name: 'Product Roadmap',
-            description: 'Track product priorities and feature decisions',
-            subtype: 'pinned',
-            tags: ['test'],
-        });
-
-        expect(response).not.toBeNull();
-        expect(response.name).toBe('Product Roadmap');
-        expect(response.description).toBe('Track product priorities and feature decisions');
-        expect(response.subtype).toBe('pinned');
-    });
-
-    test('create directive mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        const response = await client.createMentalModel(bankId, {
-            name: 'Response Guidelines',
-            description: 'Rules for responding to users',
-            subtype: 'directive',
-            observations: [
-                { title: 'Always be polite', content: 'All responses must be courteous and professional' },
-                { title: 'Never share private info', content: 'Do not reveal internal details or user data' },
-            ],
-            tags: ['test'],
-        });
-
-        expect(response).not.toBeNull();
-        expect(response.name).toBe('Response Guidelines');
-        expect(response.subtype).toBe('directive');
-        expect(response.observations).toBeDefined();
-        expect(response.observations!.length).toBe(2);
-    });
-
-    test('list mental models', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        await client.createMentalModel(bankId, {
-            name: 'Test Model',
-            description: 'A test mental model',
-            subtype: 'pinned',
-        });
-
-        const response = await client.listMentalModels(bankId);
-
-        expect(response).not.toBeNull();
-        expect(response.items).toBeDefined();
-        expect(response.items!.length).toBeGreaterThanOrEqual(1);
-    });
-
-    test('get mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        const created = await client.createMentalModel(bankId, {
-            name: 'Retrieve Test Model',
-            description: 'A model to retrieve',
-            subtype: 'pinned',
-        });
-
-        const response = await client.getMentalModel(bankId, created.id);
-
-        expect(response).not.toBeNull();
-        expect(response.id).toBe(created.id);
-        expect(response.name).toBe('Retrieve Test Model');
-    });
-
-    test('update mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        const created = await client.createMentalModel(bankId, {
-            name: 'Update Test Model',
-            description: 'Original description',
-            subtype: 'pinned',
-        });
-
-        const response = await client.updateMentalModel(bankId, created.id, {
-            name: 'Updated Model Name',
-            description: 'Updated description',
-        });
-
-        expect(response).not.toBeNull();
-        expect(response.name).toBe('Updated Model Name');
-        expect(response.description).toBe('Updated description');
-    });
-
-    test('delete mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        const created = await client.createMentalModel(bankId, {
-            name: 'Delete Test Model',
-            description: 'A model to delete',
-            subtype: 'pinned',
-        });
-
-        // Delete should not throw
-        await expect(client.deleteMentalModel(bankId, created.id)).resolves.not.toThrow();
-    });
-
-    test('refresh mental models', async () => {
-        const bankId = randomBankId();
-
-        // Set mission first (required for refresh) - this also creates the bank
-        await client.setMission(bankId, 'Track team progress and decisions');
-
-        const response = await client.refreshMentalModels(bankId, {
-            tags: ['test'],
-        });
-
-        expect(response).not.toBeNull();
-        expect(response.operation_id).toBeDefined();
-        expect(response.status).toBe('queued');
-    });
-
-    test('refresh mental model', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        const created = await client.createMentalModel(bankId, {
-            name: 'Refresh Single Test',
-            description: 'A model to refresh individually',
-            subtype: 'pinned',
-        });
-
-        const response = await client.refreshMentalModel(bankId, created.id);
-
-        expect(response).not.toBeNull();
-        expect(response.operation_id).toBeDefined();
-        expect(response.status).toBe('queued');
-    });
-
-    test('list mental model versions', async () => {
-        const bankId = randomBankId();
-        // Create bank first (required for mental models)
-        await client.createBank(bankId, {});
-
-        // Create a model first
-        const created = await client.createMentalModel(bankId, {
-            name: 'Versions Test Model',
-            description: 'A model to test version history',
-            subtype: 'pinned',
-        });
-
-        const response = await client.listMentalModelVersions(bankId, created.id);
-
-        // Newly created model should have version history
-        expect(response).not.toBeNull();
-    });
-});

hindsight-docs/blog/2026-01-19-mental-models.md

@@ -1,387 +0,0 @@
----
-slug: introducing-mental-models
-title: "Introducing Mental Models"
-authors: [nicoloboschi]
-hide_table_of_contents: true
----
-
-# Introducing mental models
-
-We're excited to announce **Mental Models**, a fundamental redesign of how Hindsight agents form, organize, and evolve their beliefs. This replaces the previous opinions and observations system with a more powerful, evidence-grounded architecture.
-
-<!-- truncate -->
-
----
-
-## The reflect agent needs more power
-
-When you call `reflect()`, you're asking the agent to reason—not just retrieve facts, but think about them, form judgments, and provide contextual answers. But effective reasoning requires more than raw memories. The agent needs:
-
-- **A sense of purpose**: What is this agent for? What should it pay attention to?
-- **Organized knowledge**: Not scattered facts, but structured understanding of key topics
-- **Evolving beliefs**: The ability to form, refine, and update views based on accumulated evidence
-
-This is where **Mission** and **Mental Models** come in.
-
-### Mission: defining agent purpose
-
-Every memory bank can now have a **mission**—a natural language description of what the agent is for:
-
-```python
-client.set_mission(
-    bank_id="pm-agent",
-    mission="Be a PM for the engineering team, tracking sprint progress, team capacity, and technical decisions"
-)
-```
-
-The mission is foundational. It tells the agent:
-- What topics are important to track
-- How to interpret incoming information
-- What kind of mental models to build automatically
-
-Without a mission, the agent has no compass. With one, it knows what matters.
-
-**Note:** A mission is required to use mental models, but mental models themselves are optional. You can still use `reflect()` without setting a mission—the agent will reason over raw memories as before. Mental models add an additional layer of structured understanding on top.
-
----
-
-## Mental models: structured understanding
-
-Mental models are **organized knowledge containers** that give the Reflect agent a broader, structured understanding of important topics. Instead of reasoning over raw memories alone, the agent can draw on synthesized knowledge about key people, projects, concepts, and decisions.
-
-```mermaid
-graph LR
-    Q[Query] --> A[Reflect Agent]
-    A <--> MM[Mental Models]
-    A <--> M[Memories]
-    A --> R[Response]
-```
-
-The agent runs a reasoning loop, deciding which tools to use based on the query. It can explore mental models, search memories, drill into documents, or create new mental models when it discovers important patterns. Each mental model groups observations about a topic with full provenance—the agent doesn't just know something, it knows *why* it knows it.
-
-### What about opinions and observations?
-
-In earlier versions, Hindsight formed beliefs through **opinions** (beliefs with confidence scores) and **observations** (entity-specific patterns). Mental models build on these concepts while adding:
-
-- **Organization**: All observations about a topic grouped together
-- **Evidence trail**: Every belief links back to source memories with exact quotes
-- **Version history**: Track how beliefs evolve over time
-
-### What's in a mental model?
-
-Each mental model contains:
-
-- **Name**: Human-readable identifier ("Alice", "Tech Stack Decisions")
-- **Description**: One-liner for quick scanning
-- **Observations**: List of beliefs with evidence
-- **Version**: Current version number
-- **Tags**: For scoped visibility
-
-### Evidence-grounded observations
-
-Every observation now requires **exact quotes** from source memories:
-
-```json
-{
-  "title": "Strong ML expertise",
-  "content": "Alice has deep machine learning knowledge, particularly in transformer architectures and production ML systems.",
-  "evidence": [
-    {
-      "memory_id": "mem_abc123",
-      "quote": "Alice implemented our BERT-based classifier that reduced inference latency by 40%",
-      "relevance": "Demonstrates practical transformer expertise",
-      "timestamp": "2025-11-15T10:30:00Z"
-    },
-    {
-      "memory_id": "mem_def456",
-      "quote": "Alice's talk on production ML pipelines was the highlight of the engineering offsite",
-      "relevance": "Shows recognition of ML systems knowledge",
-      "timestamp": "2025-12-02T14:00:00Z"
-    }
-  ],
-  "trend": "strengthening"
-}
-```
-
-The system **verifies** that quoted text actually exists in the source memories, ensuring observations are always grounded in real data.
-
-### Computed trends
-
-Instead of numeric confidence values, mental models use computed trends based on evidence patterns:
-
-- **new**: Recently formed, limited evidence
-- **strengthening**: Recent evidence supports this observation
-- **stable**: Consistent evidence over time
-- **weakening**: Recent evidence contradicts or is absent
-- **stale**: No recent evidence, may be outdated
-
-Trends are determined by analyzing evidence timestamps and recency patterns.
-
----
-
-## How reflect uses mental models
-
-The Reflect agent is now **agentic**—it actively explores and drills down into information as needed. When answering a query, the agent can:
-
-1. **List mental models** to see what structured knowledge is available
-2. **Read a mental model** to get synthesized observations about a topic
-3. **Drill into evidence** by following an observation's source memories
-4. **Expand to full context** by loading the original document chunk
-
-The agent decides how deep to go based on the query—simple questions may only need mental model summaries, while complex decisions may require drilling down to source documents.
-
-### Agentic tools
-
-During reflect, the agent has access to:
-
-- `list_mental_models()` — See available mental models
-- `get_mental_model(id)` — Read observations and evidence
-- `recall(query)` — Search raw memories
-- `learn(name, description)` — Create a new mental model to track a discovered pattern
-
-This makes reflect a reasoning loop, not a single retrieval step.
-
----
-
-## Five types of mental models
-
-Mental models can be created through different pathways, each serving a specific purpose:
-
-### 1. Structural (mission-derived)
-
-Created automatically from the bank's mission statement. If your agent's mission is "Be a PM for the engineering team", Hindsight generates structural models for concepts any PM would need to track: Team Members, Sprint Goals, Technical Debt.
-
-```python
-client.set_mission(
-    bank_id="pm-agent",
-    mission="Be a PM for the engineering team, tracking sprint progress and team capacity"
-)
-# Automatically creates: "Team Members", "Sprint Goals", "Blockers", etc.
-```
-
-### 2. Emergent (data-discovered)
-
-Created automatically when patterns emerge in the data. If "Alice" is mentioned frequently across many memories, Hindsight promotes her to a mental model and synthesizes observations about her.
-
-### 3. Pinned (user-created)
-
-Created explicitly by users for topics they want the agent to track:
-
-```python
-client.create_mental_model(
-    bank_id="my-agent",
-    name="Product Roadmap",
-    description="Track product priorities and feature decisions"
-)
-# Content generated by analyzing relevant memories
-```
-
-### 4. Learned (agent-created)
-
-Created by the reflect agent during reasoning when it identifies topics worth tracking long-term. As part of the agentic reflect loop, the agent doesn't just answer queries—it also considers whether this is a topic it should understand more deeply going forward.
-
-For example, if a user asks "What are customers saying about our new pricing?" and the agent finds scattered feedback across many memories, it might decide: "Customer feedback on pricing is something I should track systematically." It then creates a "Pricing Feedback" mental model, which will be populated with synthesized observations during the next refresh.
-
-This makes the agent proactive about building its own knowledge structure based on what users actually care about.
-
-### 5. Directive (hard rules)
-
-User-defined constraints that the agent must follow. Unlike other mental models, directives are never modified by the system:
-
-```python
-client.create_mental_model(
-    bank_id="support-agent",
-    name="Response Guidelines",
-    subtype="directive",
-    observations=[
-        {"title": "Always respond in French", "content": "All customer responses must be in French regardless of input language"},
-        {"title": "Never mention competitors", "content": "Do not reference or compare to competitor products"}
-    ]
-)
-```
-
-Directives are injected into the system prompt during reflect with a "(MANDATORY)" marker.
-
----
-
-## Tags and scoping
-
-Mental models support tags for multi-user scenarios. Tags let you create separate sets of mental models within the same bank and scope which ones are used during reflect—useful when a single bank serves multiple users who need personalized mental models.
-
-### Which types support tags
-
-- **Structural** and **Emergent**: Tags are applied during refresh via the `tags` parameter
-- **Pinned** and **Learned**: Tags are set at creation time
-- **Directive**: Tags are set at creation time and used to scope which directives apply during reflect
-
-### Applying tags
-
-When refreshing, pass tags to apply them to newly created models:
-
-```python
-# Create structural/emergent models with tags for a specific user
-client.refresh_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice"]
-)
-
-# Create a pinned model for a user
-client.create_mental_model(
-    bank_id="my-agent",
-    name="Alice's Preferences",
-    description="Track Alice's communication preferences",
-    tags=["user_alice"]
-)
-
-# Create a directive scoped to a user
-client.create_mental_model(
-    bank_id="my-agent",
-    name="Alice's Guidelines",
-    subtype="directive",
-    tags=["user_alice"],
-    observations=[
-        {"title": "Use formal tone", "content": "Alice prefers formal business communication"}
-    ]
-)
-```
-
-### Filtering by tags
-
-List mental models with tag filtering:
-
-```python
-# Get all models for a specific user
-models = client.list_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice"],
-    tags_match="any"  # "any", "all", "any_strict", "all_strict"
-)
-```
-
-When calling reflect with tags, both memories and directives are filtered to that scope:
-
-```python
-# Reflect using only Alice's context
-response = client.reflect(
-    bank_id="my-agent",
-    query="What should I focus on today?",
-    tags=["user_alice"]
-)
-# Only Alice's memories, mental models, and directives are considered
-```
-
-This enables a single bank to serve multiple users with personalized mental model sets.
-
----
-
-## Refreshing mental models
-
-Mental model refresh is **manual**—you decide when to update observations based on new memories. The API provides flexibility to refresh at different granularities:
-
-```python
-# Refresh all mental models in a bank
-client.refresh_mental_models(bank_id="my-agent")
-
-# Refresh only structural models (mission-derived)
-client.refresh_mental_models(bank_id="my-agent", subtype="structural")
-
-# Refresh only emergent models (data-discovered)
-client.refresh_mental_models(bank_id="my-agent", subtype="emergent")
-
-# Refresh a single mental model
-client.refresh_mental_model(bank_id="my-agent", model_id="alice")
-```
-
-All refresh operations run asynchronously and return an `operation_id` you can use to track progress.
-
-### Freshness API
-
-Each mental model includes a `freshness` field that tells you whether it's up to date:
-
-```python
-model = client.get_mental_model(bank_id="my-agent", model_id="alice")
-print(model.freshness)
-# {
-#   "is_up_to_date": false,
-#   "last_refresh_at": "2025-12-01T10:30:00Z",
-#   "memories_since_refresh": 47,
-#   "reasons": ["new_memories", "mission_changed"]
-# }
-```
-
-The `reasons` field tells you what changed since the last refresh:
-- **never_refreshed**: Model was just created and has no observations yet
-- **new_memories**: New memories have been retained since last refresh
-- **mission_changed**: The bank's mission was updated
-- **disposition_changed**: The bank's disposition traits changed
-- **directives_changed**: Directive mental models were added/modified
-
-This lets you build your own refresh strategy—refresh on a schedule, after a threshold of new memories, or on-demand when users query specific topics.
-
----
-
-## How mental models update
-
-The refresh process is a well-defined multi-phase pipeline that ensures observations stay grounded in evidence.
-
-### Phase 1: Update existing observations
-
-For each current observation, the system searches for new supporting or contradicting evidence. New quotes are added to the evidence list, and observations with strong contradictions are flagged for removal.
-
-### Phase 2: Seed new candidates
-
-The system samples recent memories and asks the LLM to identify new patterns worth tracking—skipping anything already covered by existing observations.
-
-### Phase 3: Evidence hunt
-
-For each candidate observation, parallel searches find supporting and contradicting evidence across the memory bank.
-
-### Phase 4: Validate quotes
-
-The LLM extracts exact quotes from memories. The system then verifies these quotes actually exist in the source memories (using fuzzy matching to handle minor variations). Observations without verified evidence are discarded.
-
-### Phase 5: Merge and finalize
-
-The LLM compares updated existing observations with validated new ones, deciding what to keep, remove, or merge. The final observation list becomes the new version.
-
-Each refresh creates a new version, so you can always see how understanding evolved over time.
-
----
-
-## Version history
-
-Every refresh creates a new version, preserving the full history:
-
-```python
-# List all versions
-versions = client.list_mental_model_versions(bank_id="my-agent", model_id="alice")
-
-# Get specific historical version
-v2 = client.get_mental_model_version(bank_id="my-agent", model_id="alice", version=2)
-```
-
-This enables:
-- **Auditing**: See how beliefs evolved over time
-- **Debugging**: Understand why an agent's perspective changed
-- **Rollback**: Compare current vs. historical understanding
-
----
-
-## Migration from opinions/observations
-
-If you're upgrading from a previous version:
-
-**What happens automatically:**
-- Existing opinion and observation records are deleted (they lack the evidence structure required by mental models)
-- The `background` bank field is replaced by `mission`
-
-**What you need to do:**
-- Set a mission for banks that should have mental models: `client.set_mission(bank_id, mission="...")`
-- Call `client.refresh_mental_models(bank_id)` to generate initial mental models from existing memories
-- Update any code that searched for `fact_type='opinion'` to use the mental models API instead
-
----
-
-## Try it out
-
-Mental models are available in Hindsight 0.4.0. We'd love to hear your feedback—please share your experience and suggestions on [GitHub](https://github.com/vectorize-io/hindsight/issues).

hindsight-docs/blog/authors.yml

@@ -1,4 +0,0 @@
-nicoloboschi:
-  name: Nicolò Boschi
-  url: https://github.com/nicoloboschi
-  image_url: https://github.com/nicoloboschi.png

hindsight-docs/docs/cookbook/recipes/quickstart.md

@@ -127,7 +127,7 @@ for r in results.results:
 
 ## Reflect: Generate Insights
 
-The `reflect` operation runs an agentic reasoning loop over memories and mental models. The agent explores structured knowledge, searches memories, and may create new mental models when it discovers important patterns.
+The `reflect` operation performs a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as opinions and/or observations.
 
 Example use cases:
 - An AI Project Manager reflecting on what risks need to be mitigated
@@ -142,12 +142,12 @@ print(response)
 
 ## Memory Types
 
-Hindsight organizes memory into two types:
+Hindsight organizes memory into four networks to mimic human memory:
 
 - **World**: Facts about the world ("The stove gets hot")
-- **Experience**: Agent's own experiences and conversations ("I touched the stove and it really hurt")
-
-For structured knowledge, Hindsight uses **mental models**—organized containers with evidence-grounded observations. See [Mental Models](/developer/mental-models) for details.
+- **Experiences**: Agent's own experiences ("I touched the stove and it really hurt")
+- **Opinion**: Beliefs with confidence scores ("I shouldn't touch the stove again" - .99 confidence)
+- **Observation**: Complex mental models derived by reflecting on facts and experiences
 
 ## Cleanup
 

hindsight-docs/docs/developer/admin-cli.md

@@ -78,7 +78,7 @@ The backup includes:
 - Memory banks and their configuration
 - Documents and chunks
 - Entities and their relationships
-- Memory units (world facts, experiences)
+- Memory units (facts, experiences, opinions, observations)
 - Entity cooccurrences and memory links
 
 :::note Consistency
@@ -127,6 +127,53 @@ Restore will **delete all existing data** in the target schema before importing
 
 ---
 
+### decommission-worker
+
+Release all tasks owned by a worker, resetting them from "processing" back to "pending" status so they can be picked up by other workers.
+
+```bash
+hindsight-admin decommission-worker WORKER_ID [OPTIONS]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `WORKER_ID` | ID of the worker to decommission |
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--schema`, `-s` | Database schema | `public` |
+
+**Examples:**
+
+```bash
+# Before scaling down - release tasks from workers being removed
+hindsight-admin decommission-worker hindsight-worker-4
+hindsight-admin decommission-worker hindsight-worker-3
+
+# Release tasks from a crashed worker
+hindsight-admin decommission-worker worker-2
+
+# For a specific tenant schema
+hindsight-admin decommission-worker worker-1 --schema tenant_acme
+```
+
+**When to Use:**
+
+- **Scaling down**: Before removing worker replicas in Kubernetes
+- **Graceful removal**: When taking a worker offline for maintenance
+- **Crash recovery**: If a worker crashed while processing tasks
+- **Stuck worker**: When a worker is unresponsive
+
+:::tip Finding Worker IDs
+Worker IDs default to the hostname. In Kubernetes StatefulSets, this is the pod name (e.g., `hindsight-worker-0`). You can also set a custom ID with `HINDSIGHT_API_WORKER_ID` or `--worker-id`.
+:::
+
+---
+
 ## Environment Variables
 
 The admin CLI uses the same environment variables as the API service. The most important one is:

hindsight-docs/docs/developer/api/entities.md

@@ -91,18 +91,18 @@ This means:
 - Observations stay up-to-date as new information is retained
 - The system prioritizes entities that matter most to your memory bank
 
-### Entity observations vs mental models
+### Observations vs Opinions
 
-Entity observations are **brief summaries** attached to specific entities. [Mental models](./mental-models) are richer structured knowledge containers with evidence-grounded observations.
+Observations are **objective summaries**—they synthesize facts without any bias or perspective. This is different from [opinions](./opinions), which are influenced by the memory bank's disposition.
 
-| | Entity Observations | Mental Models |
+| | Observations | Opinions |
 |---|---|---|
-| **Purpose** | Quick entity context | Structured understanding of topics |
-| **Evidence** | No | Yes (exact quotes from memories) |
-| **Scope** | Per-entity | Any topic (people, projects, concepts) |
-| **Generation** | Automatic (top entities) | Manual refresh or agent-created |
+| **Purpose** | Summarize what's known about an entity | Express the bank's perspective on a topic |
+| **Disposition influence** | No | Yes |
+| **Scope** | Per-entity | Any topic |
+| **Generation** | Automatic (top entities) | On-demand via reflect |
 
-### Using observations
+### Using Observations
 
 Observations are included in recall results when you set `include_entities=True`. They provide quick context about key entities without retrieving all underlying facts.
 

hindsight-docs/docs/developer/api/main-methods.mdx

@@ -87,9 +87,9 @@ hindsight recall my-bank "Tell me about Alice" -v
 
 ---
 
-## Reflect: Reason with Mental Models
+## Reflect: Reason with Disposition
 
-Generate reasoned responses using mental models and memories.
+Generate disposition-aware responses that form opinions based on evidence.
 
 <Tabs>
 <TabItem value="python" label="Python">
@@ -104,7 +104,7 @@ Generate reasoned responses using mental models and memories.
 # Basic reflect
 hindsight reflect my-bank "Should we adopt TypeScript for our backend?"
 
-# Verbose output (shows sources and mental models)
+# Verbose output (shows sources and opinions)
 hindsight reflect my-bank "What are Alice's strengths for the team lead role?" -v
 
 # With higher reasoning budget
@@ -114,9 +114,9 @@ hindsight reflect my-bank "Analyze our tech stack" --budget high
 </TabItem>
 </Tabs>
 
-**What happens:** The agent explores mental models and memories, reasons through evidence with disposition, and may create new mental models when it discovers important patterns.
+**What happens:** Memories are recalled, bank disposition is loaded, LLM reasons through evidence, new opinions are formed and stored.
 
-**See:** [Reflect Details](./reflect) for mental models and disposition configuration.
+**See:** [Reflect Details](./reflect) for disposition configuration.
 
 ---
 
@@ -126,9 +126,9 @@ hindsight reflect my-bank "Analyze our tech stack" --budget high
 |---------|--------|--------|---------|
 | **Purpose** | Store information | Find information | Reason about information |
 | **Input** | Raw text/documents | Search query | Question/prompt |
-| **Output** | Memory IDs | Ranked facts | Reasoned response |
+| **Output** | Memory IDs | Ranked facts | Reasoned response + opinions |
 | **Uses LLM** | Yes (extraction) | No | Yes (generation) |
-| **Uses mental models** | No | No | Yes |
+| **Forms opinions** | No | No | Yes |
 | **Disposition** | No | No | Yes |
 
 ---
@@ -137,5 +137,5 @@ hindsight reflect my-bank "Analyze our tech stack" --budget high
 
 - [**Retain**](./retain) — Advanced options for storing memories
 - [**Recall**](./recall) — Tuning search quality and performance
-- [**Reflect**](./reflect) — Configuring mental models and disposition
+- [**Reflect**](./reflect) — Configuring disposition and opinions
 - [**Memory Banks**](./memory-banks) — Managing memory bank disposition

hindsight-docs/docs/developer/api/memory-banks.mdx

@@ -56,17 +56,17 @@ hindsight bank disposition my-bank \
 </TabItem>
 </Tabs>
 
-## Mission and Disposition
+## Background and Disposition
 
-Mission and disposition are optional settings that influence how the bank reasons during [reflect](./reflect) operations.
+Background and disposition are optional settings that influence how the bank forms opinions during [reflect](./reflect) operations.
 
 :::info
-Mission and disposition only affect the `reflect` operation. They do not impact `retain`, `recall`, or other memory operations.
+Background and disposition only affect the `reflect` operation (opinion formation). They do not impact `retain`, `recall`, or other memory operations.
 :::
 
-### Mission
+### Background
 
-The mission is a natural language description of what the agent is for. It's required for using [mental models](./mental-models):
+The background is a first-person narrative providing context for opinion formation:
 
 <Tabs>
 <TabItem value="python" label="Python">
@@ -79,7 +79,7 @@ The mission is a natural language description of what the agent is for. It's req
 
 ### Disposition Traits
 
-Disposition traits influence how the agent reasons during reflection. Each trait is scored 1 to 5:
+Disposition traits influence how opinions are formed during reflection. Each trait is scored 1 to 5:
 
 | Trait | Low (1) | High (5) |
 |-------|---------|----------|

hindsight-docs/docs/developer/api/mental-models.mdx

@@ -1,281 +0,0 @@
----
-sidebar_position: 6
----
-
-# Mental Models
-
-Manage mental models—structured knowledge containers that give agents broader understanding of important topics.
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import CodeSnippet from '@site/src/components/CodeSnippet';
-
-{/* Import raw source files */}
-import mentalModelsPy from '!!raw-loader!@site/examples/api/mental-models.py';
-import mentalModelsSh from '!!raw-loader!@site/examples/api/mental-models.sh';
-
-:::info How Mental Models Work
-Learn about the different types, observations, and refresh process in the [Mental Models Architecture](/developer/mental-models) guide.
-:::
-
-:::tip Prerequisites
-Make sure you've completed the [Quick Start](./quickstart) and set a mission for your bank.
-:::
-
-## Set mission
-
-A mission is required before using mental models. It defines what the agent should track:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-set-mission" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-set-mission" language="bash" />
-</TabItem>
-</Tabs>
-
----
-
-## List mental models
-
-List all mental models for a bank, optionally filtered by subtype or tags:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-list" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-list" language="bash" />
-</TabItem>
-</Tabs>
-
-### Response fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | string | Unique identifier |
-| `name` | string | Human-readable name |
-| `description` | string | One-liner description |
-| `subtype` | string | One of: structural, emergent, pinned, learned, directive |
-| `observations` | array | List of observations with evidence |
-| `tags` | array | Tags for scoping |
-| `version` | int | Current version number |
-| `freshness` | object | Freshness status (null for directives) |
-| `created_at` | string | ISO timestamp |
-| `last_updated` | string | ISO timestamp of last change |
-
----
-
-## Get mental model
-
-Get a specific mental model by ID:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-get" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-get" language="bash" />
-</TabItem>
-</Tabs>
-
-### Observation structure
-
-Each observation contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `title` | string | Short summary (5-10 words) |
-| `content` | string | Detailed explanation |
-| `evidence` | array | Supporting quotes from memories |
-| `trend` | string | new, strengthening, stable, weakening, stale |
-| `created_at` | string | When observation was formed |
-
-### Evidence structure
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `memory_id` | string | Source memory ID |
-| `quote` | string | Exact quote from memory |
-| `relevance` | string | Why this supports the observation |
-| `timestamp` | string | When the memory was created |
-
----
-
-## Create mental model
-
-Create a pinned or directive mental model:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-create" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-create" language="bash" />
-</TabItem>
-</Tabs>
-
-### Request fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Human-readable name |
-| `description` | string | Yes | One-liner description |
-| `subtype` | string | No | "pinned" (default) or "directive" |
-| `tags` | array | No | Tags for scoping |
-| `observations` | array | Directive only | Required for directives, ignored for pinned |
-
----
-
-## Delete mental model
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-delete" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-delete" language="bash" />
-</TabItem>
-</Tabs>
-
----
-
-## Refresh mental models
-
-Refresh operations run asynchronously and return an operation ID:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-refresh" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-refresh" language="bash" />
-</TabItem>
-</Tabs>
-
-### Refresh a single model
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-refresh-single" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-refresh-single" language="bash" />
-</TabItem>
-</Tabs>
-
-Use the [Operations API](./operations) to check progress.
-
----
-
-## Freshness check
-
-The `freshness` field on each mental model indicates whether it needs refresh:
-
-<CodeSnippet code={mentalModelsPy} section="mm-freshness" language="python" />
-
-### Freshness fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `is_up_to_date` | bool | Whether model is current |
-| `last_refresh_at` | string | ISO timestamp of last refresh |
-| `memories_since_refresh` | int | New memories since last refresh |
-| `reasons` | array | Why refresh is needed |
-
-### Refresh reasons
-
-| Reason | Description |
-|--------|-------------|
-| `never_refreshed` | Model was just created |
-| `new_memories` | New memories retained since last refresh |
-| `mission_changed` | Bank's mission was updated |
-| `disposition_changed` | Bank's disposition traits changed |
-| `directives_changed` | Directive mental models were modified |
-
----
-
-## Version history
-
-Every refresh creates a new version:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-versions" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-versions" language="bash" />
-</TabItem>
-</Tabs>
-
----
-
-## Tags and scoping
-
-Tags enable multi-user scenarios where a single bank serves multiple users with personalized mental models.
-
-### Which types support tags
-
-| Type | How tags are applied |
-|------|---------------------|
-| **Structural** | Applied during refresh via `tags` parameter |
-| **Emergent** | Applied during refresh via `tags` parameter |
-| **Pinned** | Set at creation time |
-| **Learned** | Inherited from the reflect call that created them |
-| **Directive** | Set at creation time |
-
-### Applying tags during refresh
-
-When refreshing, pass tags to apply them to newly created structural and emergent models:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-tags-refresh" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-tags-refresh" language="bash" />
-</TabItem>
-</Tabs>
-
-### Filtering by tags
-
-List mental models matching specific tags:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-tags-filter" language="python" />
-</TabItem>
-<TabItem value="curl" label="cURL">
-<CodeSnippet code={mentalModelsSh} section="mm-tags-filter" language="bash" />
-</TabItem>
-</Tabs>
-
-### tags_match options
-
-| Option | Description |
-|--------|-------------|
-| `any` | OR match: model has no tags OR model has at least one overlapping tag |
-| `all` | AND match: model has no tags OR model has all the specified tags |
-| `any_strict` | OR match: model must have at least one overlapping tag (excludes untagged) |
-| `all_strict` | AND match: model must have all the specified tags (excludes untagged) |
-
----
-
-## Using mental models in reflect
-
-Mental models are automatically available to the reflect agent. Use tags to scope which mental models and memories are considered:
-
-<Tabs>
-<TabItem value="python" label="Python">
-<CodeSnippet code={mentalModelsPy} section="mm-reflect" language="python" />
-</TabItem>
-</Tabs>
-
-The reflect agent can:
-- List available mental models
-- Read observations and evidence
-- Drill down to source memories
-- Create new "learned" mental models when it discovers important patterns
-
-See [Reflect API](./reflect) for more options.

hindsight-docs/docs/developer/api/operations.md

@@ -25,8 +25,10 @@ Support for external streaming platforms like Kafka for scale-out processing is
 | Operation | Trigger | Description |
 |-----------|---------|-------------|
 | **batch_retain** | `retain_batch` with `async=True` | Processes large content batches in the background |
-| **refresh_mental_models** | `refresh_mental_models` call | Updates mental model observations based on new memories |
+| **form_opinion** | After each `reflect` call | Extracts and stores new opinions formed during reflection |
+| **reinforce_opinion** | After `retain` | Updates opinion confidence based on new supporting evidence |
 | **access_count_update** | After `recall` | Tracks which memories are accessed for relevance scoring |
+| **regenerate_observations** | Bank profile update | Regenerates entity observations when disposition changes |
 
 ## Async Retain Example
 

hindsight-docs/docs/developer/api/opinions.mdx

@@ -0,0 +1,135 @@
+---
+sidebar_position: 5
+---
+
+# Opinions
+
+How memory banks form, store, and evolve beliefs.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeSnippet from '@site/src/components/CodeSnippet';
+
+{/* Import raw source files */}
+import opinionsPy from '!!raw-loader!@site/examples/api/opinions.py';
+import opinionsMjs from '!!raw-loader!@site/examples/api/opinions.mjs';
+
+:::tip Prerequisites
+Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
+:::
+
+## What Are Opinions?
+
+Opinions are beliefs formed by the memory bank based on evidence and disposition. Unlike world facts (objective information received) or experience (conversations and events), opinions are **judgments** with confidence scores.
+
+| Type | Example | Confidence |
+|------|---------|------------|
+| World Fact | "Python was created in 1991" | — |
+| Experience | "I recommended Python to Bob" | — |
+| Opinion | "Python is the best language for data science" | 0.85 |
+
+## How Opinions Form
+
+Opinions are created during `reflect` operations when the memory bank:
+1. Retrieves relevant facts
+2. Applies disposition traits
+3. Forms a judgment
+4. Assigns a confidence score
+
+```mermaid
+graph LR
+    F[Facts] --> D[Disposition Filter]
+    D --> J[Judgment]
+    J --> O[Opinion + Confidence]
+    O --> S[(Store)]
+```
+
+<Tabs>
+<TabItem value="python" label="Python">
+<CodeSnippet code={opinionsPy} section="opinion-form" language="python" />
+</TabItem>
+<TabItem value="node" label="Node.js">
+<CodeSnippet code={opinionsMjs} section="opinion-form" language="javascript" />
+</TabItem>
+</Tabs>
+
+## Searching Opinions
+
+<Tabs>
+<TabItem value="python" label="Python">
+<CodeSnippet code={opinionsPy} section="opinion-search" language="python" />
+</TabItem>
+<TabItem value="node" label="Node.js">
+<CodeSnippet code={opinionsMjs} section="opinion-search" language="javascript" />
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+```bash
+hindsight recall my-bank "programming" --types opinion
+```
+
+</TabItem>
+</Tabs>
+
+## Opinion Evolution
+
+Opinions change as new evidence arrives:
+
+| Evidence Type | Effect |
+|---------------|--------|
+| **Reinforcing** | Confidence increases (+0.1) |
+| **Weakening** | Confidence decreases (-0.15) |
+| **Contradicting** | Opinion revised, confidence reset |
+
+**Example evolution:**
+
+```
+t=0: "Python is best for data science" (0.70)
+     ↓ New evidence: Python dominates ML libraries
+t=1: "Python is best for data science" (0.85)
+     ↓ New evidence: Julia is 10x faster for numerical computing
+t=2: "Python is best for data science, though Julia is faster" (0.75)
+     ↓ New evidence: Most teams still use Python
+t=3: "Python is best for data science" (0.82)
+```
+
+## Disposition Influence
+
+Different dispositions form different opinions from the same facts:
+
+<Tabs>
+<TabItem value="python" label="Python">
+<CodeSnippet code={opinionsPy} section="opinion-disposition" language="python" />
+</TabItem>
+<TabItem value="node" label="Node.js">
+<CodeSnippet code={opinionsMjs} section="opinion-disposition" language="javascript" />
+</TabItem>
+</Tabs>
+
+## Opinions in Reflect Responses
+
+When `reflect` uses opinions, they appear in `based_on`:
+
+<Tabs>
+<TabItem value="python" label="Python">
+<CodeSnippet code={opinionsPy} section="opinion-in-reflect" language="python" />
+</TabItem>
+<TabItem value="node" label="Node.js">
+<CodeSnippet code={opinionsMjs} section="opinion-in-reflect" language="javascript" />
+</TabItem>
+</Tabs>
+
+## Confidence Thresholds
+
+Opinions below a confidence threshold may be:
+- Excluded from responses
+- Marked as uncertain
+- Revised more easily
+
+```python
+# Low confidence opinions are held loosely
+# "I think Python might be good for this" (0.45)
+
+# High confidence opinions are stated firmly
+# "Python is definitely the right choice" (0.92)
+```

hindsight-docs/docs/developer/api/recall.mdx

@@ -42,7 +42,7 @@ Make sure you've completed the [Quick Start](./quickstart) to install the client
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `query` | string | required | Natural language query |
-| `types` | list | all | Filter: `world`, `experience` |
+| `types` | list | all | Filter: `world`, `experience`, `opinion` |
 | `budget` | string | "mid" | Budget level: `low`, `mid`, `high` |
 | `max_tokens` | int | 4096 | Token budget for results |
 | `trace` | bool | false | Enable trace output for debugging |
@@ -68,12 +68,20 @@ Recall specific memory types:
 <TabItem value="python" label="Python">
 <CodeSnippet code={recallPy} section="recall-world-only" language="python" />
 <CodeSnippet code={recallPy} section="recall-experience-only" language="python" />
+<CodeSnippet code={recallPy} section="recall-opinions-only" language="python" />
 </TabItem>
 <TabItem value="cli" label="CLI">
 <CodeSnippet code={recallSh} section="recall-fact-type" language="bash" />
 </TabItem>
 </Tabs>
 
+:::warning About Opinions
+Opinions are beliefs formed during [reflect](/developer/api/reflect) operations. Unlike world facts and experience, opinions are subjective interpretations and may not represent objective truth. Depending on your use case:
+- **Exclude opinions** (`types=["world", "experience"]`) when you need factual, verifiable information
+- **Include opinions** when you want the agent's perspective or formed beliefs
+- **Use opinions alone** (`types=["opinion"]`) only when specifically asking about the agent's views
+:::
+
 ## Token Budget Management
 
 Hindsight is built for AI agents, not humans. Traditional retrieval systems return "top-k" results, but agents don't think in terms of result counts—they think in tokens. An agent's context window is measured in tokens, and that's exactly how Hindsight measures results.

hindsight-docs/docs/developer/api/reflect.mdx

@@ -4,15 +4,15 @@ sidebar_position: 3
 
 # Reflect
 
-Generate reasoned responses using mental models and memories.
+Generate disposition-aware responses using retrieved memories.
 
-When you call **reflect**, Hindsight runs an agentic reasoning loop:
-1. **Explores** mental models for structured understanding of key topics
-2. **Recalls** relevant memories from the bank based on the query
-3. **Reasons** through evidence applying the bank's disposition
-4. **Learns** by creating new mental models when important patterns are discovered
+When you call **reflect**, Hindsight performs a multi-step reasoning process:
+1. **Recalls** relevant memories from the bank based on your query
+2. **Applies** the bank's disposition traits to shape the reasoning style
+3. **Generates** a contextual answer grounded in the retrieved facts
+4. **Forms opinions** in the background based on the reasoning (available in subsequent calls)
 
-The response includes the generated answer along with the facts and mental models that were used, providing full transparency into how the answer was derived.
+The response includes the generated answer along with the facts that were used, providing full transparency into how the answer was derived.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -24,14 +24,14 @@ import reflectMjs from '!!raw-loader!@site/examples/api/reflect.mjs';
 import reflectSh from '!!raw-loader!@site/examples/api/reflect.sh';
 
 :::info How Reflect Works
-Learn about mental models and disposition-driven reasoning in the [Reflect Architecture](/developer/reflect) guide.
+Learn about disposition-driven reasoning and opinion formation in the [Reflect Architecture](/developer/reflect) guide.
 :::
 
 :::tip Prerequisites
 Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
 :::
 
-## Basic usage
+## Basic Usage
 
 <Tabs>
 <TabItem value="python" label="Python">
@@ -51,17 +51,18 @@ Make sure you've completed the [Quick Start](./quickstart) to install the client
 |-----------|------|---------|-------------|
 | `query` | string | required | Question or prompt |
 | `budget` | string | "low" | Budget level: `low`, `mid`, `high` |
+| `context` | string | None | Additional context for the query |
 | `max_tokens` | int | 4096 | Maximum tokens for the response |
 | `response_schema` | object | None | JSON Schema for [structured output](#structured-output) |
-| `tags` | list | None | Filter memories and mental models by tags |
+| `tags` | list | None | Filter memories by tags during reflection |
 | `tags_match` | string | "any" | How to match tags: `any`, `all`, `any_strict`, `all_strict` |
 
-### Response fields
+### Response Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `text` | string | The generated answer text |
-| `based_on` | object | Facts and mental models used to generate the response |
+| `based_on` | array | Facts used to generate the response |
 | `structured_output` | object | Parsed structured output (when `response_schema` provided) |
 | `usage` | TokenUsage | Token usage metrics for the LLM call |
 
@@ -79,29 +80,38 @@ The `usage` field contains:
 </TabItem>
 </Tabs>
 
-## Mental models
+## The Role of Context
 
-When a bank has a mission set, the reflect agent can draw on mental models—structured knowledge about key topics. The agent is agentic: it decides which mental models to consult based on the query.
+The `context` parameter steers how the reflection is performed without impacting the memory recall. It provides situational information that helps shape the reasoning and response.
 
-During reflect, the agent has access to these tools:
+**How context is used:**
+- **Shapes reasoning**: Helps understand the situation when formulating an answer
+- **Disambiguates intent**: Clarifies what aspect of the query matters most
+- **Does not affect recall**: The same memories are retrieved regardless of context
 
-| Tool | Purpose |
-|------|---------|
-| `list_mental_models()` | See available mental models |
-| `get_mental_model(id)` | Read observations and evidence |
-| `recall(query)` | Search raw memories |
-| `expand(memory_ids)` | Load full document context |
-| `learn(name, description)` | Create a new mental model to track a pattern |
+<Tabs>
+<TabItem value="python" label="Python">
+<CodeSnippet code={reflectPy} section="reflect-with-context" language="python" />
+</TabItem>
+<TabItem value="node" label="Node.js">
+<CodeSnippet code={reflectMjs} section="reflect-with-context" language="javascript" />
+</TabItem>
+</Tabs>
 
-### Learned mental models
+## Opinion Formation
 
-If the agent discovers an important pattern during reasoning, it can create a "learned" mental model to track it going forward. For example, if asked about customer pricing feedback and the agent finds scattered information, it might create a "Pricing Feedback" mental model for future systematic tracking.
+When reflect reasons about a question, it may form new **opinions** based on the evidence in the memory bank. These opinions are created in the background and become available in subsequent `reflect` and `recall` calls.
 
-See [Mental Models API](./mental-models) for managing mental models.
+**Why opinions matter:**
+- **Consistent thinking**: Opinions ensure the memory bank maintains a coherent perspective over time
+- **Evolving viewpoints**: As more information is retained, opinions can be refined or updated
+- **Grounded reasoning**: Opinions are always derived from factual evidence in the memory bank
 
-## Disposition influence
+Opinions are stored as a special memory type and are automatically retrieved when relevant to future queries. This creates a natural evolution of the bank's perspective, similar to how humans form and refine their views based on accumulated experience.
 
-The bank's disposition affects how reflect interprets information:
+## Disposition Influence
+
+The bank's disposition affects reflect responses:
 
 | Trait | Low (1) | High (5) |
 |-------|---------|----------|
@@ -118,9 +128,9 @@ The bank's disposition affects how reflect interprets information:
 </TabItem>
 </Tabs>
 
-## Using sources
+## Using Sources
 
-The `based_on` field shows which memories and mental models informed the response:
+The `based_on` field shows which memories informed the response:
 
 <Tabs>
 <TabItem value="python" label="Python">
@@ -136,7 +146,7 @@ This enables:
 - **Verification** — check if the response is grounded in facts
 - **Debugging** — understand retrieval quality
 
-## Structured output
+## Structured Output
 
 For applications that need to process responses programmatically, you can request structured output by providing a JSON Schema via `response_schema`. When provided, the response includes a `structured_output` field with the LLM response parsed according to the schema. The `text` field will be empty since only a single LLM call is made for efficiency.
 
@@ -240,9 +250,9 @@ hindsight memory reflect hiring-team \
 - Keep schemas focused — extract only what you need
 - Use `Optional` fields for data that may not always be available
 
-## Filter by tags
+## Filter by Tags
 
-Reflect supports tag filtering to scope which memories and mental models are considered during reasoning. This is essential for multi-user scenarios.
+Like [recall](./recall#filter-by-tags), reflect supports tag filtering to scope which memories are considered during reasoning. This is essential for multi-user scenarios where reflection should only consider memories relevant to a specific user.
 
 <Tabs>
 <TabItem value="python" label="Python">
@@ -250,13 +260,13 @@ Reflect supports tag filtering to scope which memories and mental models are con
 </TabItem>
 </Tabs>
 
-The `tags_match` parameter controls how tags are matched:
+The `tags_match` parameter works the same as in recall:
 
 | Mode | Behavior |
 |------|----------|
-| `any` | OR matching, includes untagged items |
-| `all` | AND matching, includes untagged items |
-| `any_strict` | OR matching, excludes untagged items |
-| `all_strict` | AND matching, excludes untagged items |
+| `any` | OR matching, includes untagged memories |
+| `all` | AND matching, includes untagged memories |
+| `any_strict` | OR matching, excludes untagged memories |
+| `all_strict` | AND matching, excludes untagged memories |
 
-See [Retain API](./retain#tagging-memories) for how to tag memories and [Mental Models API](./mental-models#tags-and-scoping) for tagging mental models.
+See [Retain API](./retain#tagging-memories) for how to tag memories and [Recall API](./recall#filter-by-tags) for more details on tag matching modes.

hindsight-docs/docs/developer/configuration.md

@@ -344,15 +344,18 @@ Configuration for the local MCP server (`hindsight-local-mcp` command).
 export HINDSIGHT_API_MCP_INSTRUCTIONS="Also store every action you take, including tool calls and decisions made."
 ```
 
-### Background Tasks
+### Distributed Workers
 
-Controls background task processing for async operations like mental model refresh and entity observations.
+Configuration for background task processing. By default, the API processes tasks internally. For high-throughput deployments, run dedicated workers. See [Services - Worker Service](./services#worker-service) for details.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_TASK_BACKEND` | Task backend implementation: `memory` (in-process queue) or `noop` (discard tasks, useful for tests) | `memory` |
-| `HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_SIZE` | Max tasks to process in one batch (memory backend only) | `10` |
-| `HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_INTERVAL` | Interval between batch processing in seconds (memory backend only) | `1.0` |
+| `HINDSIGHT_API_WORKER_ENABLED` | Enable internal worker in API process | `true` |
+| `HINDSIGHT_API_WORKER_ID` | Unique worker identifier | hostname |
+| `HINDSIGHT_API_WORKER_POLL_INTERVAL_MS` | Database polling interval in milliseconds | `500` |
+| `HINDSIGHT_API_WORKER_BATCH_SIZE` | Tasks to claim per poll cycle | `10` |
+| `HINDSIGHT_API_WORKER_MAX_RETRIES` | Max retries before marking task failed | `3` |
+| `HINDSIGHT_API_WORKER_HTTP_PORT` | HTTP port for worker metrics/health (worker CLI only) | `8889` |
 
 ### Performance Optimization
 

hindsight-docs/docs/developer/index.md

@@ -13,7 +13,7 @@ AI agents forget everything between sessions. Every conversation starts from zer
 
 - **Simple vector search isn't enough** — "What did Alice do last spring?" requires temporal reasoning, not just semantic similarity
 - **Facts get disconnected** — Knowing "Alice works at Google" and "Google is in Mountain View" should let you answer "Where does Alice work?" even if you never stored that directly
-- **AI Agents need to learn and reason** — A coding assistant that remembers "the user prefers functional programming" should weigh that when making recommendations
+- **AI Agents needs to form opinions** — A coding assistant that remembers "the user prefers functional programming" should weigh that when making recommendations
 - **Context matters** — The same information means different things to different memory banks with different personalities
 
 Hindsight solves these problems with a memory system designed specifically for AI agents.
@@ -49,14 +49,15 @@ graph TB
 
 ## Key Components
 
-### Two Memory Types
+### Three Memory Types
 
 Hindsight separates memories by type for epistemic clarity:
 
 | Type | What it stores | Example |
 |------|----------------|---------|
 | **World** | Objective facts received | "Alice works at Google" |
-| **Experience** | Bank's own actions and conversations | "I recommended Python to Bob" |
+| **Bank** | Bank's own actions | "I recommended Python to Bob" |
+| **Opinion** | Formed beliefs + confidence | "Python is best for ML" (0.85) |
 
 ### Multi-Strategy Retrieval (TEMPR)
 
@@ -87,7 +88,7 @@ graph LR
 
 ### Disposition Traits
 
-Memory banks have disposition traits that influence reasoning during Reflect:
+Memory banks have disposition traits that influence how opinions are formed during Reflect:
 
 | Trait | Scale | Low (1) | High (5) |
 |-------|-------|---------|----------|
@@ -106,7 +107,7 @@ These traits only affect the `reflect` operation, not `recall`.
 ### Core Concepts
 - [**Retain**](/developer/retain) — How memories are stored with multi-dimensional facts
 - [**Recall**](/developer/retrieval) — How TEMPR's 4-way search retrieves memories
-- [**Reflect**](/developer/reflect) — How mental models and disposition influence reasoning
+- [**Reflect**](/developer/reflect) — How disposition influences reasoning and opinion formation
 
 ### API Methods
 - [**Retain**](/developer/api/retain) — Store information in memory banks

hindsight-docs/docs/developer/installation.md

@@ -36,8 +36,6 @@ See [Models](./models) for detailed comparison and configuration.
 
 **Best for**: Quick start, development, small deployments
 
-### Single Container (Quickest)
-
 Run everything in one container with embedded PostgreSQL:
 
 ```bash
@@ -83,7 +81,19 @@ helm upgrade hindsight oci://ghcr.io/vectorize-io/charts/hindsight
 - Kubernetes cluster (GKE, EKS, AKS, or self-hosted)
 - Helm 3.8+
 
-See the [Helm chart documentation](https://github.com/vectorize-io/hindsight/tree/main/helm) for advanced configuration.
+### Distributed Workers
+
+For high-throughput deployments, enable dedicated worker pods to scale task processing independently:
+
+```bash
+helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
+  --set worker.enabled=true \
+  --set worker.replicaCount=3
+```
+
+See [Services - Worker Service](./services#worker-service) for configuration details and architecture.
+
+See the [Helm chart values.yaml](https://github.com/vectorize-io/hindsight/tree/main/helm/hindsight/values.yaml) for all chart options.
 
 ---
 

hindsight-docs/docs/developer/mental-models.mdx

@@ -1,193 +0,0 @@
----
-sidebar_position: 5
----
-
-# Mental Models
-
-Mental models are structured knowledge containers that give Hindsight agents a broader understanding of important topics. Instead of reasoning over raw memories alone, the agent builds and maintains synthesized knowledge about key people, projects, concepts, and decisions.
-
-import CodeSnippet from '@site/src/components/CodeSnippet';
-
-{/* Import raw source files */}
-import mentalModelsPy from '!!raw-loader!@site/examples/api/mental-models.py';
-
----
-
-## Mission: the foundation
-
-Before using mental models, you must set a **mission** for the memory bank. The mission is a natural language description of what the agent is for:
-
-<CodeSnippet code={mentalModelsPy} section="mm-set-mission-alt" language="python" />
-
-The mission tells the agent:
-- What topics are important to track
-- How to interpret incoming information
-- What kind of mental models to build automatically
-
-**Note:** A mission is required to use mental models, but mental models themselves are optional. You can still use `reflect()` without setting a mission—the agent will reason over raw memories. Mental models add structured understanding on top.
-
----
-
-## What's in a mental model
-
-Each mental model contains:
-
-- **Name**: Human-readable identifier ("Alice", "Tech Stack Decisions")
-- **Description**: One-liner for quick scanning
-- **Subtype**: How it was created (structural, emergent, pinned, learned, directive)
-- **Observations**: List of beliefs with evidence
-- **Version**: Current version number
-- **Tags**: For scoped visibility (multi-user scenarios)
-
----
-
-## Observations and evidence
-
-Observations are the beliefs within a mental model. Each observation requires **exact quotes** from source memories.
-
-An observation contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `title` | string | Short summary (5-10 words) |
-| `content` | string | Detailed explanation |
-| `evidence` | array | Supporting quotes from memories |
-| `trend` | string | new, strengthening, stable, weakening, stale |
-
-Each evidence item includes:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `memory_id` | string | Source memory ID |
-| `quote` | string | Exact quote from memory |
-| `relevance` | string | Why this supports the observation |
-| `timestamp` | string | When the memory was created |
-
-The system **verifies** that quoted text actually exists in the source memories, ensuring observations are always grounded in real data.
-
-### Computed trends
-
-Instead of numeric confidence values, mental models use computed trends based on evidence patterns:
-
-- **new**: Recently formed, limited evidence
-- **strengthening**: Recent evidence supports this observation
-- **stable**: Consistent evidence over time
-- **weakening**: Recent evidence contradicts or is absent
-- **stale**: No recent evidence, may be outdated
-
-Trends are determined by analyzing evidence timestamps and recency patterns.
-
----
-
-## Five types of mental models
-
-Mental models can be created through different pathways:
-
-### 1. Structural (mission-derived)
-
-Created automatically from the bank's mission statement. If your agent's mission is "Be a PM for the engineering team", Hindsight generates structural models for concepts any PM would need to track: Team Members, Sprint Goals, Technical Debt.
-
-### 2. Emergent (data-discovered)
-
-Created automatically when patterns emerge in the data. If "Alice" is mentioned frequently across many memories, Hindsight promotes her to a mental model and synthesizes observations about her.
-
-### 3. Pinned (user-created)
-
-Created explicitly by users for topics they want the agent to track:
-
-<CodeSnippet code={mentalModelsPy} section="mm-pinned" language="python" />
-
-Observations are generated by analyzing relevant memories during refresh.
-
-### 4. Learned (agent-created)
-
-Created by the reflect agent during reasoning when it identifies topics worth tracking long-term. As part of the agentic reflect loop, the agent considers whether a topic deserves deeper understanding going forward.
-
-For example, if a user asks "What are customers saying about our new pricing?" and the agent finds scattered feedback, it might create a "Pricing Feedback" mental model to track systematically.
-
-### 5. Directive (hard rules)
-
-User-defined constraints that the agent must follow. Unlike other mental models, directives are never modified by the system:
-
-<CodeSnippet code={mentalModelsPy} section="mm-directive" language="python" />
-
-Directives are injected into the system prompt during reflect with a "(MANDATORY)" marker.
-
----
-
-## How reflect uses mental models
-
-The reflect agent is **agentic**—it actively explores and drills down into information as needed. When answering a query, the agent can:
-
-1. **List mental models** to see what structured knowledge is available
-2. **Read a mental model** to get synthesized observations about a topic
-3. **Drill into evidence** by following an observation's source memories
-4. **Expand to full context** by loading the original document chunk
-5. **Create new mental models** via the `learn` tool when it discovers important patterns
-
-The agent decides how deep to go based on the query—simple questions may only need mental model summaries, while complex decisions may require drilling down to source documents.
-
-See [Reflect](./reflect) for more on how disposition and mental models work together.
-
----
-
-## Refreshing mental models
-
-Mental model refresh is **manual**—you decide when to update observations based on new memories:
-
-<CodeSnippet code={mentalModelsPy} section="mm-refresh-simple" language="python" />
-
-All refresh operations run asynchronously.
-
-### Freshness check
-
-Each mental model includes a `freshness` field:
-
-<CodeSnippet code={mentalModelsPy} section="mm-freshness-check" language="python" />
-
-Reasons for refresh:
-- **never_refreshed**: Model was just created
-- **new_memories**: New memories retained since last refresh
-- **mission_changed**: Bank's mission was updated
-- **disposition_changed**: Bank's disposition traits changed
-- **directives_changed**: Directive mental models were modified
-
-### The refresh process
-
-When a mental model refreshes, it runs a multi-phase pipeline:
-
-1. **Update existing**: Search for new supporting/contradicting evidence for current observations
-2. **Seed**: Generate candidate new observations from recent memories
-3. **Evidence hunt**: Find supporting/contradicting evidence for candidates
-4. **Validate**: Verify exact quotes exist in source memories
-5. **Merge**: Decide what to keep, remove, or merge
-
-Each refresh creates a new version.
-
----
-
-## Version history
-
-Every refresh creates a new version, preserving full history:
-
-<CodeSnippet code={mentalModelsPy} section="mm-versions-simple" language="python" />
-
-This enables auditing how beliefs evolved over time.
-
----
-
-## Tags and scoping
-
-Mental models support tags for multi-user scenarios. Tags let you create separate sets of mental models within the same bank:
-
-<CodeSnippet code={mentalModelsPy} section="mm-tags-scoping" language="python" />
-
-When calling reflect with tags, both memories and mental models are filtered to that scope.
-
----
-
-## Next steps
-
-- [**Reflect**](./reflect) — How disposition and mental models work together
-- [**Mental Models API**](./api/mental-models) — Full API reference
-- [**Memory Banks**](./api/memory-banks) — Managing bank configuration

hindsight-docs/docs/developer/models.md

@@ -16,7 +16,7 @@ All local models (embedding, cross-encoder) are automatically downloaded from Hu
 
 ## LLM
 
-Used for fact extraction, entity resolution, mental model generation, and answer synthesis.
+Used for fact extraction, entity resolution, opinion generation, and answer synthesis.
 
 **Supported providers:** OpenAI, Anthropic, Gemini, Groq, Ollama, LM Studio, and **any OpenAI-compatible API**
 

hindsight-docs/docs/developer/rag-vs-hindsight.md

@@ -14,7 +14,7 @@ Traditional RAG (Retrieval-Augmented Generation) retrieves documents similar to
 | **Multi-hop reasoning** | Limited to retrieved chunks | Graph traversal across entity relationships |
 | **Temporal queries** | Keyword matching ("spring") | Date parsing and range filtering |
 | **Entity understanding** | None | Entity resolution, observations, co-occurrence |
-| **Structured knowledge** | Stateless | Mental models with evidence-grounded observations |
+| **Belief formation** | Stateless | Opinions with confidence scores that evolve |
 | **Disposition** | None | 3 traits (skepticism, literalism, empathy) influence interpretation |
 
 ## Architecture Comparison
@@ -96,7 +96,7 @@ Multiple retrieval strategies. Persistent state across sessions.
 | System | Behavior |
 |--------|----------|
 | RAG | No memory of progression |
-| Hindsight | Builds mental model tracking user's coding patterns, observations evolve as evidence changes |
+| Hindsight | Forms opinion "user prefers sync" (0.7) → updates to "user growing comfortable with async" (0.6) |
 
 ## When to Use Each
 

hindsight-docs/docs/developer/reflect.md

@@ -2,99 +2,59 @@
 sidebar_position: 4
 ---
 
-# Reflect: How Hindsight Reasons
+# Reflect: How Hindsight Reasons with Disposition
 
-When you call `reflect()`, Hindsight doesn't just retrieve facts — it **reasons** about them through the lens of mental models and disposition, generating contextual responses.
+When you call `reflect()`, Hindsight doesn't just retrieve facts — it **reasons** about them through the lens of the bank's unique disposition, forming new opinions and generating contextual responses.
 
 ```mermaid
 graph LR
-    Q[Query] --> A[Reflect Agent]
-    A <--> MM[Mental Models]
-    A <--> M[Memories]
-    A --> R[Response]
+    A[Query] --> B[Recall Memories]
+    B --> C[Load Disposition]
+    C --> D[Reason]
+    D --> E[Form Opinions]
+    E --> F[Response]
 ```
 
-The reflect agent is **agentic**—it runs a reasoning loop, deciding which tools to use based on the query. It can explore mental models, search memories, drill into documents, or create new mental models when it discovers important patterns.
-
 ---
 
-## Why reflect?
+## Why Reflect?
 
-Hindsight provides two ways to query memories: `recall()` returns raw facts, while `reflect()` reasons about them.
+Most AI systems can retrieve facts, but they can't **reason** about them in a consistent way. Every response is generated fresh without a stable perspective or evolving beliefs.
 
-### recall() vs reflect()
+### The Problem
 
-**recall()** is a retrieval operation. It returns ranked facts matching your query—you get raw data and build your own reasoning on top.
+Without reflect:
+- **No consistent character**: "Should we adopt remote work?" gets a different answer each time based on the LLM's randomness
+- **No opinion formation**: The system never develops beliefs based on accumulated evidence
+- **No reasoning context**: Responses don't reflect what the bank has learned or its perspective
+- **Generic responses**: Every AI sounds the same — no disposition, no point of view
 
-**reflect()** is a reasoning operation. It runs an agentic loop that:
-- Explores **mental models** for structured understanding of key topics
-- Searches **memories** for specific evidence
-- **Learns** by creating new mental models when it discovers important patterns
-- Reasons through evidence to form grounded responses
+### The Value
 
-The key difference: recall gives you facts, reflect gives you understanding. When the agent reasons, it draws on everything the bank has learned—not just matching facts, but synthesized knowledge about people, projects, and concepts.
+With reflect:
+- **Consistent character**: A bank configured as "detail-oriented, cautious" will consistently emphasize risks and thorough planning
+- **Evolving opinions**: As the bank learns more about a topic, its opinions strengthen, weaken, or change — just like a real expert
+- **Contextual reasoning**: Responses reflect the bank's accumulated knowledge and perspective: "Based on what I know about your team's remote work success..."
+- **Differentiated behavior**: Customer support bots sound diplomatic, code reviewers sound direct, creative assistants sound open-minded
 
-### When to use reflect
+### When to Use Reflect
 
 | Use `recall()` when... | Use `reflect()` when... |
 |------------------------|-------------------------|
 | You need raw facts | You need reasoned interpretation |
-| You're building your own reasoning | You want the bank to "think" for itself |
-| You need maximum control | Forming recommendations or judgments |
-| Simple fact lookup | Complex questions requiring synthesis |
+| You're building your own reasoning | You want disposition-consistent responses |
+| You need maximum control | You want the bank to "think" for itself |
+| Simple fact lookup | Forming recommendations or opinions |
 
 **Example:**
 - `recall("Alice")` → Returns all Alice facts
-- `reflect("Should we hire Alice?")` → Reasons about Alice's fit based on accumulated knowledge and mental models
+- `reflect("Should we hire Alice?")` → Reasons about Alice's fit based on accumulated knowledge, weighs evidence, forms opinion
 
 ---
 
-## Mental models
+## Disposition Traits
 
-When a bank has a mission set, mental models provide structured knowledge that the reflect agent can draw on. A **mission** is a natural language description of what the agent is for:
-
-```python
-client.set_mission(
-    bank_id="pm-agent",
-    mission="Be a PM for the engineering team, tracking sprint progress, team capacity, and technical decisions"
-)
-```
-
-The mission tells the agent what topics are important and what kind of mental models to build. Mental models are then created automatically (structural and emergent) or manually (pinned and directive).
-
-**Note:** A mission is required to use mental models, but mental models are optional for reflect. Without a mission, the agent reasons over raw memories.
-
-### Available tools
-
-During reflect, the agent has access to:
-
-| Tool | Purpose |
-|------|---------|
-| `list_mental_models()` | See available mental models |
-| `get_mental_model(id)` | Read observations and evidence |
-| `recall(query)` | Search raw memories |
-| `expand(memory_ids)` | Load full document context |
-| `learn(name, description)` | Create a new mental model to track a pattern |
-
-The agent decides how deep to go based on the query—simple questions may only need mental model summaries, while complex decisions may require drilling down to source documents.
-
-### Creating learned mental models
-
-If the agent discovers an important pattern during reasoning, it can create a "learned" mental model to track it going forward:
-
-> User: "What are customers saying about our new pricing?"
->
-> Agent thinks: "I found scattered feedback about pricing across many memories. This seems like something I should track systematically."
->
-> Agent creates: Mental model "Pricing Feedback" for future tracking
-
-See [Mental Models](./mental-models) for more on types, observations, and refresh.
-
----
-
-## Disposition
-
-Disposition configures the bank's character—how it interprets information during reflect. Three traits shape reasoning:
+When you create a memory bank, you can configure its disposition using three traits. These traits influence how the bank interprets information and forms opinions during `reflect()`:
 
 | Trait | Scale | Low (1) | High (5) |
 |-------|-------|---------|----------|
@@ -102,18 +62,35 @@ Disposition configures the bank's character—how it interprets information duri
 | **Literalism** | 1-5 | Flexible interpretation, reads between the lines | Literal interpretation, takes things at face value |
 | **Empathy** | 1-5 | Detached, focuses on facts | Empathetic, considers emotional context |
 
+### Background: Natural Language Identity
+
+Beyond numeric traits, you can provide a natural language **background** that describes the bank's identity:
+
 ```python
-client.update_disposition(
+client.create_bank(
     bank_id="my-bank",
+    background="I am a senior software architect with 15 years of distributed "
+               "systems experience. I prefer simplicity over cutting-edge technology.",
     disposition={
-        "skepticism": 4,   # Questions claims
+        "skepticism": 4,   # Questions new technologies
         "literalism": 4,   # Focuses on concrete specs
         "empathy": 2       # Prioritizes technical facts
     }
 )
 ```
 
-### Same facts, different conclusions
+The background provides context that shapes how disposition traits are applied:
+- "I prefer simplicity" + high skepticism → questions complex solutions
+- "15 years experience" → responses reference this expertise
+- First-person perspective → creates consistent voice
+
+---
+
+## Opinion Formation
+
+When `reflect()` encounters a question that warrants forming an opinion, disposition shapes the response.
+
+### Same Facts, Different Opinions
 
 Two banks with different dispositions, given identical facts about remote work:
 
@@ -125,7 +102,34 @@ Two banks with different dispositions, given identical facts about remote work:
 
 **Same facts → Different conclusions** because disposition shapes interpretation.
 
-### Presets by use case
+---
+
+## Opinion Evolution
+
+Opinions aren't static — they evolve as new evidence arrives. Here's a real-world example with a database library:
+
+| Event | What the bank learns | Opinion formed |
+|-------|---------------------|----------------|
+| **Day 1** | "Redis is open source under BSD license" | "Redis is excellent for caching — fast, reliable, and OSS-friendly" (confidence: 0.85) |
+| **Day 2** | "Redis has great community support and documentation" | Opinion reinforced (confidence: 0.90) |
+| **Day 30** | "Redis changed license to SSPL, restricting cloud usage" | "Redis is still technically strong, but license concerns for cloud deployments" (confidence: 0.65) |
+| **Day 45** | "Valkey forked Redis under BSD license with Linux Foundation backing" | "Consider Valkey for new projects requiring true OSS; Redis for existing deployments" (confidence: 0.80) |
+
+**Before the license change:**
+> "Should we use Redis for our caching layer?"
+> → "Yes, Redis is the industry standard — fast, battle-tested, and fully open source."
+
+**After the license change:**
+> "Should we use Redis for our caching layer?"
+> → "It depends. For cloud deployments, consider Valkey (the BSD-licensed fork). For on-premise, Redis remains excellent technically."
+
+This **continuous learning** ensures recommendations stay current with real-world changes.
+
+---
+
+## Disposition Presets by Use Case
+
+Different use cases benefit from different disposition configurations:
 
 | Use Case | Recommended Traits | Why |
 |----------|-------------------|-----|
@@ -137,13 +141,13 @@ Two banks with different dispositions, given identical facts about remote work:
 
 ---
 
-## What you get from reflect
+## What You Get from Reflect
 
 When you call `reflect()`:
 
 **Returns:**
-- **Response text** — Reasoned answer informed by mental models and disposition
-- **Based on** — Which memories and mental models were used
+- **Response text** — Disposition-influenced answer
+- **Based on** — Which memories were used (with relevance scores)
 
 **Example:**
 ```json
@@ -153,19 +157,30 @@ When you call `reflect()`:
     "world": [
       {"text": "Alice works at Google...", "weight": 0.95},
       {"text": "Alice specializes in ML...", "weight": 0.88}
-    ],
-    "mental_models": [
-      {"id": "alice", "name": "Alice"}
     ]
   }
 }
 ```
 
+**Note:** New opinions are formed asynchronously in the background. They'll influence future `reflect()` calls but aren't returned directly.
+
 ---
 
-## Next steps
+## Why Disposition Matters
+
+Without disposition, all AI assistants sound the same. With disposition:
+
+- **Customer support bots** can be diplomatic and empathetic
+- **Code review assistants** can be direct and thorough
+- **Creative assistants** can be open to unconventional ideas
+- **Risk analysts** can be appropriately cautious
+
+Disposition creates **consistent character** across conversations while allowing opinions to **evolve with evidence**.
+
+---
+
+## Next Steps
 
-- [**Mental Models**](./mental-models) — How structured knowledge is organized
 - [**Retain**](./retain) — How rich facts are stored
 - [**Recall**](./retrieval) — How multi-strategy search works
 - [**Reflect API**](./api/reflect) — Code examples, parameters, and tag filtering

hindsight-docs/docs/developer/retain.md

@@ -63,6 +63,7 @@ Hindsight distinguishes between **world** facts (about others) and **experience*
 | **experience** | Conversations and events         | "I recommended Python to Alice" |
 
 
+**Note:** Opinions aren't created during `retain()` — only during `reflect()` when the bank forms beliefs.
 This separation is important for `reflect()` — the bank can reason about what it knows versus what happened in conversations.
 
 ---
@@ -196,5 +197,5 @@ All stored in your isolated **memory bank**, ready for `recall()` and `reflect()
 ## Next Steps
 
 - [**Recall**](./retrieval) — How multi-strategy search retrieves relevant memories
-- [**Reflect**](./reflect) — How mental models and disposition influence reasoning
+- [**Reflect**](./reflect) — How disposition influences reasoning and opinion formation
 - [**Retain API**](./api/retain) — Code examples and parameters

hindsight-docs/docs/developer/retrieval.md

@@ -112,9 +112,9 @@ After the four strategies run, results are **fused together**:
 
 Consider the query: **"What did Alice think about Python last spring?"**
 
-- **Semantic** finds facts about Alice's views on programming
+- **Semantic** finds facts about Alice's opinions on programming
 - **Keyword** ensures "Python" is actually mentioned
-- **Graph** connects Alice → preferences → programming languages
+- **Graph** connects Alice → opinions → programming languages
 - **Temporal** filters to "last spring" timeframe
 
 The **fusion** of all four gives you exactly what you're looking for, even though no single strategy would suffice.
@@ -133,7 +133,7 @@ Hindsight is built for AI agents, not humans. Traditional search systems return
 **Parameters you control:**
 - `max_tokens`: How much memory content to return (default: 4096 tokens)
 - `budget`: Search depth level (low, mid, high)
-- `types`: Filter by world, experience, or all
+- `types`: Filter by world, experience, opinion, or all
 - `tags`: Filter memories by visibility tags
 - `tags_match`: How to match tags (see [Recall API](./api/recall) for all options)
 

hindsight-docs/docs/developer/services.md

@@ -1,6 +1,6 @@
 # Services
 
-Hindsight consists of two services that can run together or separately depending on your deployment needs.
+Hindsight consists of three services that can run together or separately depending on your deployment needs.
 
 ## API Service
 
@@ -10,12 +10,48 @@ The core memory engine. Handles all memory operations:
 - **Recall**: Semantic search across memories
 - **Reflect**: Disposition-aware answer generation
 
-```
+```bash
 hindsight-api        # Default port: 8888
 ```
 
 The API service is stateless and can be horizontally scaled behind a load balancer. All state is stored in PostgreSQL.
 
+By default, the API also processes background tasks (opinion formation, entity observations) internally. For high-throughput deployments, you can disable this and run dedicated workers instead.
+
+## Worker Service
+
+Dedicated task processor for background operations. Uses the **same package and Docker image** as the API service, just with a different entry point.
+
+```bash
+hindsight-worker     # Default metrics port: 8889
+```
+
+Workers use PostgreSQL as a task broker, polling for pending tasks. Multiple workers can run simultaneously without conflicts.
+
+| Deployment | Internal Worker | Dedicated Workers |
+|------------|-----------------|-------------------|
+| **Development** | ✅ Simple, all-in-one | ❌ Overkill |
+| **Small production** | ✅ Less infrastructure | ❌ Overkill |
+| **High throughput** | ❌ API bottleneck | ✅ Scale independently |
+| **Long-running tasks** | ❌ Blocks API resources | ✅ Isolated processing |
+
+To use dedicated workers, disable the internal worker in the API and start worker processes:
+
+```bash
+# Disable internal worker in API
+HINDSIGHT_API_WORKER_ENABLED=false hindsight-api
+
+# Start dedicated workers (run multiple instances)
+hindsight-worker --worker-id worker-1
+hindsight-worker --worker-id worker-2
+```
+
+Each worker exposes `/health` and `/metrics` endpoints for monitoring.
+
+Before scaling down or removing workers, release their tasks with `hindsight-admin decommission-worker <worker-id>`.
+
+See [Configuration - Distributed Workers](./configuration#distributed-workers) for all worker settings and [Installation - Helm](./installation#distributed-workers) for Kubernetes deployment.
+
 ## Control Plane
 
 Web UI for managing and exploring your memory banks:
@@ -28,13 +64,3 @@ Web UI for managing and exploring your memory banks:
 The Control Plane connects to the API service and provides a visual interface for development and debugging.
 
 For bare metal deployments, you can run the Control Plane standalone using npx. See [Installation - Bare Metal](./installation#control-plane) for details.
-
-## Deployment Options
-
-| Deployment | Services | Use Case |
-|------------|----------|----------|
-| **Docker (single container)** | Both bundled | Development, quick start |
-| **Helm / Kubernetes** | Separate pods | Production, scaling |
-| **Bare metal** | Run independently | Custom deployments |
-
-In the Docker quickstart, both services run in a single container. For production Kubernetes deployments, they run as separate pods with independent scaling. For bare metal, you can run the API via pip and the Control Plane via npx.

hindsight-docs/docs/sdks/cli.md

@@ -74,7 +74,7 @@ hindsight memory recall <bank_id> "hiking recommendations" \
   --max-tokens 8192
 
 # Filter by fact type
-hindsight memory recall <bank_id> "query" --fact-type world,experience
+hindsight memory recall <bank_id> "query" --fact-type world,opinion
 
 # Show trace information
 hindsight memory recall <bank_id> "query" --trace
@@ -209,7 +209,7 @@ The explorer provides an interactive terminal interface to:
 - **Browse memory banks** — View all banks and their statistics
 - **Search memories** — Run recall queries with real-time results
 - **Inspect entities** — Explore the knowledge graph and entity relationships
-- **View facts** — Browse world facts and experiences
+- **View facts** — Browse world facts, experiences, and opinions
 - **Navigate documents** — See source documents and their extracted memories
 
 ### Keyboard Shortcuts

hindsight-docs/docs/sdks/integrations/litellm.md

@@ -108,7 +108,7 @@ hindsight_litellm.configure(
     bank_id="my-agent",
     use_reflect=False,  # Default
 )
-# Injects: "1. [WORLD] User prefers Python\n2. [EXPERIENCE] Discussed Java alternatives..."
+# Injects: "1. [WORLD] User prefers Python\n2. [OPINION] User dislikes Java..."
 
 # Reflect mode - synthesized context
 hindsight_litellm.configure(

hindsight-docs/docs/sdks/nodejs.md

@@ -83,7 +83,7 @@ for (const r of response.results) {
 
 // With options
 const response = await client.recall('my-bank', 'What does Alice do?', {
-    types: ['world', 'experience'],  // Filter by fact type
+    types: ['world', 'opinion'],  // Filter by fact type
     maxTokens: 4096,
     budget: 'high',  // 'low', 'mid', or 'high'
 });

hindsight-docs/docs/sdks/python.md

@@ -150,7 +150,7 @@ for r in results.results:
 results = client.recall(
     bank_id="my-bank",
     query="What does Alice do?",
-    types=["world", "experience"],  # Filter by fact type
+    types=["world", "opinion"],  # Filter by fact type
     max_tokens=4096,
     budget="high",  # low, mid, or high
 )

hindsight-docs/docusaurus.config.ts

@@ -68,32 +68,8 @@ const config: Config = {
           sidebarPath: './sidebars.ts',
           editUrl: 'https://github.com/vectorize-io/hindsight/tree/main/hindsight-docs/',
           routeBasePath: '/',
-          // Hide "next" (current) version in production, show only released versions
-          onlyIncludeVersions:
-            process.env.NODE_ENV === 'development' || process.env.INCLUDE_CURRENT_VERSION === 'true'
-              ? undefined
-              : (() => {
-                  try {
-                    return require('./versions.json');
-                  } catch {
-                    return undefined; // No versions yet, show current
-                  }
-                })(),
-        },
-        blog: {
-          path: 'blog',
-          routeBasePath: 'blog',
-          blogTitle: 'Hindsight Blog',
-          blogDescription: 'Updates and announcements from the Hindsight team',
-          showReadingTime: true,
-          blogSidebarTitle: 'Recent Posts',
-          blogSidebarCount: 'ALL',
-          editUrl: 'https://github.com/vectorize-io/hindsight/tree/main/hindsight-docs/',
-          feedOptions: {
-            type: 'all',
-          },
-          onInlineAuthors: 'ignore',
         },
+        blog: false,
         theme: {
           customCss: './src/css/custom.css',
         },
@@ -147,7 +123,7 @@ const config: Config = {
       {
         hashed: true,
         docsRouteBasePath: '/',
-        indexBlog: true,
+        indexBlog: false,
         highlightSearchTermsOnTargetPage: false,
       },
     ],
@@ -209,12 +185,6 @@ const config: Config = {
           label: 'Changelog',
           className: 'navbar-item-changelog',
         },
-        {
-          to: '/blog',
-          position: 'left',
-          label: 'Blog',
-          className: 'navbar-item-blog',
-        },
         {
           href: 'https://vectorize.io/hindsight/cloud',
           position: 'right',
@@ -236,55 +206,30 @@ const config: Config = {
           title: 'Documentation',
           items: [
             {
-              label: 'Developer Guide',
+              label: 'Introduction',
               to: '/',
             },
+            {
+              label: 'SDKs',
+              to: '/sdks/python',
+            },
             {
               label: 'API Reference',
               to: '/api-reference/',
             },
-            {
-              label: 'Cookbook',
-              to: '/cookbook',
-            },
           ],
         },
         {
-          title: 'SDKs',
-          items: [
-            {
-              label: 'Python',
-              to: '/sdks/python',
-            },
-            {
-              label: 'Node.js',
-              to: '/sdks/nodejs',
-            },
-            {
-              label: 'CLI',
-              to: '/sdks/cli',
-            },
-          ],
-        },
-        {
-          title: 'Community',
+          title: 'More',
           items: [
             {
               label: 'GitHub',
               href: 'https://github.com/vectorize-io/hindsight',
             },
-            {
-              label: 'Blog',
-              to: '/blog',
-            },
-            {
-              label: 'Changelog',
-              to: '/changelog',
-            },
           ],
         },
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} Vectorize, Inc.`,
+      copyright: `Copyright © ${new Date().getFullYear()} Hindsight.`,
     },
     prism: {
       theme: prismThemes.github,

hindsight-docs/examples/api/README.md

@@ -18,7 +18,7 @@ This directory contains runnable example scripts that serve as the source of tru
 | `reflect.py/mjs/sh` | reflect.md | AI reflection examples |
 | `memory-banks.py/mjs` | memory-banks.md | Bank management examples |
 | `documents.py/mjs` | documents.md | Document CRUD examples |
-| `mental-models.py/sh` | mental-models.md | Mental models API examples |
+| `opinions.py` | opinions.md | Opinion management examples |
 | `main-methods.py` | main-methods.md | Core method examples |
 | `cli-reference.sh` | cli.md | CLI command examples |
 

hindsight-docs/examples/api/cli-reference.sh

@@ -65,7 +65,7 @@ hindsight memory recall $BANK_ID "hiking recommendations" \
 
 
 # [docs:cli-recall-fact-type]
-hindsight memory recall $BANK_ID "query" --fact-type world,experience
+hindsight memory recall $BANK_ID "query" --fact-type world,opinion
 # [/docs:cli-recall-fact-type]
 
 

hindsight-docs/examples/api/mental-models.py

@@ -1,269 +0,0 @@
-"""Mental Models API examples for documentation."""
-
-from hindsight_client import Hindsight
-
-client = Hindsight()
-
-# [docs:mm-set-mission]
-client.set_mission(
-    bank_id="my-agent",
-    mission="Be a PM for the engineering team, tracking sprint progress and team capacity"
-)
-# [/docs:mm-set-mission]
-
-
-# [docs:mm-set-mission-alt]
-client.set_mission(
-    bank_id="pm-agent",
-    mission="Be a PM for the engineering team, tracking sprint progress, team capacity, and technical decisions"
-)
-# [/docs:mm-set-mission-alt]
-
-
-# [docs:mm-list]
-# List all mental models
-models = client.list_mental_models(bank_id="my-agent")
-
-# Filter by subtype
-structural_models = client.list_mental_models(
-    bank_id="my-agent",
-    subtype="structural"
-)
-
-# Filter by tags
-user_models = client.list_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice"],
-    tags_match="any"  # "any", "all", "any_strict", "all_strict"
-)
-# [/docs:mm-list]
-
-
-# [docs:mm-get]
-model = client.get_mental_model(bank_id="my-agent", model_id="alice")
-
-print(f"Name: {model.name}")
-print(f"Description: {model.description}")
-print(f"Version: {model.version}")
-
-for obs in model.observations:
-    print(f"- {obs.title} ({obs.trend})")
-    for evidence in obs.evidence:
-        print(f"  Quote: {evidence.quote}")
-# [/docs:mm-get]
-
-
-# [docs:mm-create]
-# Create a pinned model (observations generated on refresh)
-model = client.create_mental_model(
-    bank_id="my-agent",
-    name="Product Roadmap",
-    description="Track product priorities and feature decisions",
-    tags=["project_alpha"]
-)
-
-# Create a directive (user-defined observations, never auto-modified)
-directive = client.create_mental_model(
-    bank_id="my-agent",
-    name="Response Guidelines",
-    subtype="directive",
-    tags=["user_alice"],
-    observations=[
-        {
-            "title": "Always respond in French",
-            "content": "All responses must be in French regardless of input language"
-        },
-        {
-            "title": "Never mention competitors",
-            "content": "Do not reference or compare to competitor products"
-        }
-    ]
-)
-# [/docs:mm-create]
-
-
-# [docs:mm-pinned]
-client.create_mental_model(
-    bank_id="my-agent",
-    name="Product Roadmap",
-    description="Track product priorities and feature decisions"
-)
-# [/docs:mm-pinned]
-
-
-# [docs:mm-directive]
-client.create_mental_model(
-    bank_id="support-agent",
-    name="Response Guidelines",
-    subtype="directive",
-    observations=[
-        {"title": "Always respond in French", "content": "All responses must be in French"},
-        {"title": "Never mention competitors", "content": "Do not reference competitor products"}
-    ]
-)
-# [/docs:mm-directive]
-
-
-# [docs:mm-delete]
-client.delete_mental_model(bank_id="my-agent", model_id="old-model")
-# [/docs:mm-delete]
-
-
-# [docs:mm-refresh]
-# Refresh all mental models
-result = client.refresh_mental_models(bank_id="my-agent")
-print(f"Operation ID: {result.operation_id}")
-
-# Refresh only structural models (from mission)
-client.refresh_mental_models(bank_id="my-agent", subtype="structural")
-
-# Refresh only emergent models (from data patterns)
-client.refresh_mental_models(bank_id="my-agent", subtype="emergent")
-
-# Apply tags to newly created models
-client.refresh_mental_models(bank_id="my-agent", tags=["user_alice"])
-# [/docs:mm-refresh]
-
-
-# [docs:mm-refresh-simple]
-# Refresh all mental models
-client.refresh_mental_models(bank_id="my-agent")
-
-# Refresh only structural models
-client.refresh_mental_models(bank_id="my-agent", subtype="structural")
-
-# Refresh a single mental model
-client.refresh_mental_model(bank_id="my-agent", model_id="alice")
-# [/docs:mm-refresh-simple]
-
-
-# [docs:mm-refresh-single]
-result = client.refresh_mental_model(bank_id="my-agent", model_id="alice")
-print(f"Operation ID: {result.operation_id}")
-# [/docs:mm-refresh-single]
-
-
-# [docs:mm-freshness]
-model = client.get_mental_model(bank_id="my-agent", model_id="alice")
-
-if not model.freshness.is_up_to_date:
-    print(f"Needs refresh: {model.freshness.reasons}")
-    print(f"Memories since last refresh: {model.freshness.memories_since_refresh}")
-
-    # Trigger refresh
-    client.refresh_mental_model(bank_id="my-agent", model_id="alice")
-# [/docs:mm-freshness]
-
-
-# [docs:mm-freshness-check]
-model = client.get_mental_model(bank_id="my-agent", model_id="alice")
-print(model.freshness)
-# {
-#   "is_up_to_date": false,
-#   "last_refresh_at": "2025-12-01T10:30:00Z",
-#   "memories_since_refresh": 47,
-#   "reasons": ["new_memories", "mission_changed"]
-# }
-# [/docs:mm-freshness-check]
-
-
-# [docs:mm-versions]
-# List all versions
-versions = client.list_mental_model_versions(
-    bank_id="my-agent",
-    model_id="alice"
-)
-
-for v in versions:
-    print(f"Version {v.version}: {v.created_at}")
-
-# Get a specific version
-v2 = client.get_mental_model_version(
-    bank_id="my-agent",
-    model_id="alice",
-    version=2
-)
-
-print(f"Observations at v2: {len(v2.observations)}")
-# [/docs:mm-versions]
-
-
-# [docs:mm-versions-simple]
-# List all versions
-versions = client.list_mental_model_versions(bank_id="my-agent", model_id="alice")
-
-# Get specific historical version
-v2 = client.get_mental_model_version(bank_id="my-agent", model_id="alice", version=2)
-# [/docs:mm-versions-simple]
-
-
-# [docs:mm-tags-refresh]
-# Create structural/emergent models tagged for a specific user
-client.refresh_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice"]
-)
-
-# Refresh only structural models with tags
-client.refresh_mental_models(
-    bank_id="my-agent",
-    subtype="structural",
-    tags=["user_alice"]
-)
-# [/docs:mm-tags-refresh]
-
-
-# [docs:mm-tags-filter]
-# Get all models for a user
-models = client.list_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice"],
-    tags_match="any"
-)
-
-# Get models matching all specified tags
-models = client.list_mental_models(
-    bank_id="my-agent",
-    tags=["user_alice", "project_alpha"],
-    tags_match="all"
-)
-# [/docs:mm-tags-filter]
-
-
-# [docs:mm-reflect]
-# Reflect with all mental models
-response = client.reflect(
-    bank_id="my-agent",
-    query="Should we promote Alice to team lead?"
-)
-
-# Reflect scoped to a specific user's mental models
-response = client.reflect(
-    bank_id="my-agent",
-    query="What should I focus on today?",
-    tags=["user_alice"],
-    tags_match="any"
-)
-# [/docs:mm-reflect]
-
-
-# [docs:mm-tags-scoping]
-# Create models for a specific user
-client.refresh_mental_models(bank_id="my-agent", tags=["user_alice"])
-
-# Create a directive scoped to a user
-client.create_mental_model(
-    bank_id="my-agent",
-    name="Alice's Guidelines",
-    subtype="directive",
-    tags=["user_alice"],
-    observations=[{"title": "Prefer detailed explanations", "content": "Alice prefers thorough explanations"}]
-)
-
-# Reflect using only Alice's context
-response = client.reflect(
-    bank_id="my-agent",
-    query="What should I focus on?",
-    tags=["user_alice"]
-)
-# [/docs:mm-tags-scoping]

hindsight-docs/examples/api/mental-models.sh

@@ -1,103 +0,0 @@
-#!/bin/bash
-# Mental Models API cURL examples for documentation.
-
-BANK_ID="my-agent"
-BASE_URL="${HINDSIGHT_API_URL:-http://localhost:8080}"
-
-# [docs:mm-set-mission]
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mission" \
-  -H "Content-Type: application/json" \
-  -d '{"mission": "Be a PM for the engineering team, tracking sprint progress and team capacity"}'
-# [/docs:mm-set-mission]
-
-
-# [docs:mm-list]
-# List all
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models"
-
-# Filter by subtype
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models?subtype=structural"
-
-# Filter by tags
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models?tags=user_alice&tags_match=any"
-# [/docs:mm-list]
-
-
-# [docs:mm-get]
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models/alice"
-# [/docs:mm-get]
-
-
-# [docs:mm-create]
-# Create pinned model
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Product Roadmap",
-    "description": "Track product priorities and feature decisions",
-    "tags": ["project_alpha"]
-  }'
-
-# Create directive
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Response Guidelines",
-    "subtype": "directive",
-    "tags": ["user_alice"],
-    "observations": [
-      {"title": "Always respond in French", "content": "All responses must be in French"}
-    ]
-  }'
-# [/docs:mm-create]
-
-
-# [docs:mm-delete]
-curl -X DELETE "$BASE_URL/v1/default/banks/my-agent/mental-models/old-model"
-# [/docs:mm-delete]
-
-
-# [docs:mm-refresh]
-# Refresh all
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models/refresh"
-
-# Refresh only structural
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models/refresh" \
-  -H "Content-Type: application/json" \
-  -d '{"subtype": "structural"}'
-
-# With tags
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models/refresh" \
-  -H "Content-Type: application/json" \
-  -d '{"tags": ["user_alice"]}'
-# [/docs:mm-refresh]
-
-
-# [docs:mm-refresh-single]
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models/alice/refresh"
-# [/docs:mm-refresh-single]
-
-
-# [docs:mm-versions]
-# List versions
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models/alice/versions"
-
-# Get specific version
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models/alice/versions/2"
-# [/docs:mm-versions]
-
-
-# [docs:mm-tags-refresh]
-curl -X POST "$BASE_URL/v1/default/banks/my-agent/mental-models/refresh" \
-  -H "Content-Type: application/json" \
-  -d '{"tags": ["user_alice"]}'
-# [/docs:mm-tags-refresh]
-
-
-# [docs:mm-tags-filter]
-# Filter by tags
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models?tags=user_alice&tags_match=any"
-
-# Multiple tags with all match
-curl "$BASE_URL/v1/default/banks/my-agent/mental-models?tags=user_alice,project_alpha&tags_match=all"
-# [/docs:mm-tags-filter]

hindsight-docs/examples/api/opinions.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Opinions API examples for Hindsight (Node.js)
+ * Run: node examples/api/opinions.mjs
+ */
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+
+const HINDSIGHT_URL = process.env.HINDSIGHT_API_URL || 'http://localhost:8888';
+
+// =============================================================================
+// Setup (not shown in docs)
+// =============================================================================
+const client = new HindsightClient({ baseUrl: HINDSIGHT_URL });
+
+// Seed some data about programming languages
+await client.retain('my-bank', 'Python is widely used for data science and machine learning');
+await client.retain('my-bank', 'Functional programming emphasizes immutability and pure functions');
+await client.retain('my-bank', 'Rust has better memory safety than C++');
+await client.retain('my-bank', 'C++ has a larger ecosystem and more libraries');
+
+// =============================================================================
+// Doc Examples
+// =============================================================================
+
+// [docs:opinion-form]
+// Ask a question - the system may form opinions based on stored facts
+const answer = await client.reflect('my-bank', 'What do you think about functional programming?');
+
+console.log(answer.text);
+// [/docs:opinion-form]
+
+
+// [docs:opinion-search]
+// Search for facts about a topic
+const results = await client.recall('my-bank', 'programming languages');
+
+for (const result of results.results) {
+    console.log(`- ${result.text}`);
+}
+// [/docs:opinion-search]
+
+
+// [docs:opinion-disposition]
+// Create two memory banks with different dispositions
+await client.createBank('open-minded', {
+    name: 'Open Minded',
+    disposition: { skepticism: 2, literalism: 2, empathy: 4 }
+});
+
+await client.createBank('conservative', {
+    name: 'Conservative',
+    disposition: { skepticism: 5, literalism: 5, empathy: 2 }
+});
+
+// Store the same facts to both
+const facts = [
+    'Rust has better memory safety than C++',
+    'C++ has a larger ecosystem and more libraries',
+    'Rust compile times are longer than C++'
+];
+for (const fact of facts) {
+    await client.retain('open-minded', fact);
+    await client.retain('conservative', fact);
+}
+
+// Ask both the same question - different dispositions lead to different responses
+const q = 'Should we rewrite our C++ codebase in Rust?';
+
+const answer1 = await client.reflect('open-minded', q);
+console.log('Open-minded response:', answer1.text.slice(0, 100), '...');
+
+const answer2 = await client.reflect('conservative', q);
+console.log('Conservative response:', answer2.text.slice(0, 100), '...');
+// [/docs:opinion-disposition]
+
+
+// [docs:opinion-in-reflect]
+const reflectAnswer = await client.reflect('my-bank', 'What language should I learn?');
+
+console.log('Response:', reflectAnswer.text);
+
+// See which facts influenced the response
+if (reflectAnswer.based_on) {
+    console.log('\nBased on these facts:');
+    for (const fact of reflectAnswer.based_on) {
+        console.log(`  - ${fact.text}`);
+    }
+}
+// [/docs:opinion-in-reflect]
+
+
+// =============================================================================
+// Cleanup (not shown in docs)
+// =============================================================================
+await fetch(`${HINDSIGHT_URL}/v1/default/banks/my-bank`, { method: 'DELETE' });
+await fetch(`${HINDSIGHT_URL}/v1/default/banks/open-minded`, { method: 'DELETE' });
+await fetch(`${HINDSIGHT_URL}/v1/default/banks/conservative`, { method: 'DELETE' });
+
+console.log('opinions.mjs: All examples passed');

hindsight-docs/examples/api/opinions.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Opinions API examples for Hindsight.
+Run: python examples/api/opinions.py
+"""
+import os
+import requests
+
+HINDSIGHT_URL = os.getenv("HINDSIGHT_API_URL", "http://localhost:8888")
+
+# =============================================================================
+# Setup (not shown in docs)
+# =============================================================================
+from hindsight_client import Hindsight
+
+client = Hindsight(base_url=HINDSIGHT_URL)
+
+# Seed some data about programming languages
+client.retain(bank_id="my-bank", content="Python is widely used for data science and machine learning")
+client.retain(bank_id="my-bank", content="Functional programming emphasizes immutability and pure functions")
+client.retain(bank_id="my-bank", content="Rust has better memory safety than C++")
+client.retain(bank_id="my-bank", content="C++ has a larger ecosystem and more libraries")
+
+# =============================================================================
+# Doc Examples
+# =============================================================================
+
+# [docs:opinion-form]
+# Ask a question - the system may form opinions based on stored facts
+answer = client.reflect(
+    bank_id="my-bank",
+    query="What do you think about functional programming?"
+)
+
+print(answer.text)
+# [/docs:opinion-form]
+
+
+# [docs:opinion-search]
+# Search for facts about a topic
+results = client.recall(
+    bank_id="my-bank",
+    query="programming languages"
+)
+
+for result in results.results:
+    print(f"- {result.text}")
+# [/docs:opinion-search]
+
+
+# [docs:opinion-disposition]
+# Create two memory banks with different dispositions
+client.create_bank(
+    bank_id="open-minded",
+    name="Open Minded",
+    disposition={"skepticism": 2, "literalism": 2, "empathy": 4}
+)
+
+client.create_bank(
+    bank_id="conservative",
+    name="Conservative",
+    disposition={"skepticism": 5, "literalism": 5, "empathy": 2}
+)
+
+# Store the same facts to both
+facts = [
+    "Rust has better memory safety than C++",
+    "C++ has a larger ecosystem and more libraries",
+    "Rust compile times are longer than C++"
+]
+for fact in facts:
+    client.retain(bank_id="open-minded", content=fact)
+    client.retain(bank_id="conservative", content=fact)
+
+# Ask both the same question - different dispositions lead to different responses
+q = "Should we rewrite our C++ codebase in Rust?"
+
+answer1 = client.reflect(bank_id="open-minded", query=q)
+print("Open-minded response:", answer1.text[:100], "...")
+
+answer2 = client.reflect(bank_id="conservative", query=q)
+print("Conservative response:", answer2.text[:100], "...")
+# [/docs:opinion-disposition]
+
+
+# [docs:opinion-in-reflect]
+answer = client.reflect(bank_id="my-bank", query="What language should I learn?")
+
+print("Response:", answer.text)
+
+# See which facts influenced the response
+if answer.based_on:
+    print("\nBased on these facts:")
+    for fact in answer.based_on:
+        print(f"  - {fact.text}")
+# [/docs:opinion-in-reflect]
+
+
+# =============================================================================
+# Cleanup (not shown in docs)
+# =============================================================================
+requests.delete(f"{HINDSIGHT_URL}/v1/default/banks/my-bank")
+requests.delete(f"{HINDSIGHT_URL}/v1/default/banks/open-minded")
+requests.delete(f"{HINDSIGHT_URL}/v1/default/banks/conservative")
+
+print("opinions.py: All examples passed")

hindsight-docs/examples/api/recall.py

@@ -74,6 +74,16 @@ experience = client.recall(
 # [/docs:recall-experience-only]
 
 
+# [docs:recall-opinions-only]
+# Only opinions (formed beliefs)
+opinions = client.recall(
+    bank_id="my-bank",
+    query="What do I think about Python?",
+    types=["opinion"]
+)
+# [/docs:recall-opinions-only]
+
+
 # [docs:recall-token-budget]
 # Fill up to 4K tokens of context with relevant memories
 results = client.recall(bank_id="my-bank", query="What do I know about Alice?", max_tokens=4096)

hindsight-docs/examples/api/recall.sh

@@ -29,7 +29,7 @@ hindsight memory recall my-bank "hiking recommendations" \
 
 
 # [docs:recall-fact-type]
-hindsight memory recall my-bank "query" --fact-type world,experience
+hindsight memory recall my-bank "query" --fact-type world,opinion
 # [/docs:recall-fact-type]
 
 

hindsight-docs/sidebars.ts

@@ -27,11 +27,6 @@ const sidebars: SidebarsConfig = {
           id: 'developer/reflect',
           label: 'Reflect',
         },
-        {
-          type: 'doc',
-          id: 'developer/mental-models',
-          label: 'Mental Models',
-        },
         {
           type: 'doc',
           id: 'developer/multilingual',
@@ -79,11 +74,6 @@ const sidebars: SidebarsConfig = {
           id: 'developer/api/reflect',
           label: 'Reflect',
         },
-        {
-          type: 'doc',
-          id: 'developer/api/mental-models',
-          label: 'Mental Models',
-        },
         {
           type: 'doc',
           id: 'developer/api/memory-banks',

hindsight-docs/src/css/custom.css

@@ -100,56 +100,58 @@
   .navbar-item-sdks::before,
   .navbar-item-api::before,
   .navbar-item-cookbook::before,
-  .navbar-item-changelog::before,
-  .navbar-item-blog::before {
+  .navbar-item-changelog::before {
     display: inline-block;
-    width: 18px;
-    height: 18px;
-    margin-right: 8px;
+    width: 16px;
+    height: 16px;
+    margin-right: 6px;
     vertical-align: middle;
     background-size: contain;
     background-repeat: no-repeat;
     background-position: center;
     content: '';
-    opacity: 0.85;
-    transition: opacity 0.15s ease;
   }
 
-  .navbar__link:hover::before {
-    opacity: 1;
-  }
-
-  /* Developer - code brackets icon with gradient blue */
   .navbar-item-developer::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad1' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad1)' d='M69.12 94.15 28.5 128l40.62 33.85a8 8 0 1 1-10.24 12.29l-48-40a8 8 0 0 1 0-12.29l48-40a8 8 0 0 1 10.24 12.3Zm176 27.7-48-40a8 8 0 1 0-10.24 12.3L227.5 128l-40.62 33.85a8 8 0 1 0 10.24 12.29l48-40a8 8 0 0 0 0-12.29ZM162.73 32.48a8 8 0 0 0-10.25 4.79l-64 176a8 8 0 0 0 4.79 10.26A8.14 8.14 0 0 0 96 224a8 8 0 0 0 7.52-5.27l64-176a8 8 0 0 0-4.79-10.25Z'/%3E%3C/svg%3E");
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23666' d='M71.68 97.22 34.74 128l36.94 30.78a12 12 0 1 1-15.36 18.44l-48-40a12 12 0 0 1 0-18.44l48-40a12 12 0 0 1 15.36 18.44Zm176 21.56-48-40a12 12 0 1 0-15.36 18.44L221.26 128l-36.94 30.78a12 12 0 1 0 15.36 18.44l48-40a12 12 0 0 0 0-18.44ZM164.1 28.72a12 12 0 0 0-15.38 7.18l-64 176a12 12 0 0 0 7.18 15.37 11.79 11.79 0 0 0 4.1.73 12 12 0 0 0 11.28-7.9l64-176a12 12 0 0 0-7.18-15.38Z'/%3E%3C/svg%3E");
   }
 
-  /* SDKs - package/box icon */
   .navbar-item-sdks::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad2' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad2)' d='m223.68 66.15-88-48.15a15.88 15.88 0 0 0-15.36 0l-88 48.17a16 16 0 0 0-8.32 14v95.64a16 16 0 0 0 8.32 14l88 48.17a15.88 15.88 0 0 0 15.36 0l88-48.17a16 16 0 0 0 8.32-14V80.18a16 16 0 0 0-8.32-14.03ZM128 32l80.34 44-29.77 16.3-80.35-44Zm0 88L47.66 76l33.9-18.56 80.34 44ZM40 90l80 43.78v85.79l-80-43.75Zm96 129.57v-85.75L216 90v85.78Z'/%3E%3C/svg%3E");
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23666' d='m225.6 62.64-88-48.17a19.91 19.91 0 0 0-19.2 0l-88 48.17A20 20 0 0 0 20 80.19v95.62a20 20 0 0 0 10.4 17.55l88 48.17a19.89 19.89 0 0 0 19.2 0l88-48.17a20 20 0 0 0 10.4-17.55V80.19a20 20 0 0 0-10.4-17.55ZM128 36.57 200 76l-72 39.42L56 76ZM44 96.82l72 39.43v76.89l-72-39.42Zm96 116.32v-76.89l72-39.43v76.89Z'/%3E%3C/svg%3E");
   }
 
-  /* API Reference - document with brackets */
   .navbar-item-api::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad3' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad3)' d='M213.66 82.34l-56-56A8 8 0 0 0 152 24H56a16 16 0 0 0-16 16v176a16 16 0 0 0 16 16h144a16 16 0 0 0 16-16V88a8 8 0 0 0-2.34-5.66ZM160 51.31 188.69 80H160ZM200 216H56V40h88v48a8 8 0 0 0 8 8h48v120Zm-42.34-77.66a8 8 0 0 1 0 11.32l-24 24a8 8 0 0 1-11.32-11.32L140.69 144l-18.35-18.34a8 8 0 0 1 11.32-11.32Zm-48-11.32a8 8 0 0 1 0 11.32L91.31 156.69l18.35 18.35a8 8 0 0 1-11.32 11.32l-24-24a8 8 0 0 1 0-11.32l24-24a8 8 0 0 1 11.32 0Z'/%3E%3C/svg%3E");
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23666' d='M180.49 143.51a12 12 0 0 1 0 17l-24 24a12 12 0 0 1-17-17L155 152l-15.52-15.51a12 12 0 0 1 17-17ZM112.49 120.49a12 12 0 0 0-17 0l-24 24a12 12 0 0 0 0 17l24 24a12 12 0 0 0 17-17L97 153l15.52-15.51a12 12 0 0 0-.03-17ZM220 88v24a12 12 0 0 1-24 0v-16h-44a12 12 0 0 1-12-12V40H60v68a12 12 0 0 1-24 0V40a20 20 0 0 1 20-20h96a12 12 0 0 1 8.49 3.52l56 56A12 12 0 0 1 220 88Zm-60-8h23L160 57Zm-4 132H60v-12a12 12 0 0 0-24 0v12a20 20 0 0 0 20 20h100a12 12 0 0 0 0-24Zm64-44a12 12 0 0 0-12 12v36h-44a12 12 0 0 0 0 24h44a20 20 0 0 0 20-20v-40a12 12 0 0 0-8-12Z'/%3E%3C/svg%3E");
   }
 
-  /* Cookbook - book icon */
   .navbar-item-cookbook::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad4' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad4)' d='M208 24H72a32 32 0 0 0-32 32v168a8 8 0 0 0 8 8h144a8 8 0 0 0 0-16H56a16 16 0 0 1 16-16h136a8 8 0 0 0 8-8V32a8 8 0 0 0-8-8Zm-8 160H72a31.82 31.82 0 0 0-16 4.29V56a16 16 0 0 1 16-16h128Z'/%3E%3C/svg%3E");
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23666' d='M224 44H160a43.86 43.86 0 0 0-32 13.85A43.86 43.86 0 0 0 96 44H32a20 20 0 0 0-20 20v128a20 20 0 0 0 20 20h64a20 20 0 0 1 20 20 12 12 0 0 0 24 0 20 20 0 0 1 20-20h64a20 20 0 0 0 20-20V64a20 20 0 0 0-20-20ZM96 188H36V68h60a20 20 0 0 1 20 20v108.69A43.74 43.74 0 0 0 96 188Zm124 0h-60a43.74 43.74 0 0 0-20 8.69V88a20 20 0 0 1 20-20h60Z'/%3E%3C/svg%3E");
   }
 
-  /* Changelog - clipboard/list icon */
   .navbar-item-changelog::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad5' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad5)' d='M200 32h-40a48 48 0 0 0-96 0H56a16 16 0 0 0-16 16v168a16 16 0 0 0 16 16h144a16 16 0 0 0 16-16V48a16 16 0 0 0-16-16Zm-72-8a32 32 0 0 1 32 32H96a32 32 0 0 1 32-32Zm72 192H56V48h24v8a8 8 0 0 0 8 8h80a8 8 0 0 0 8-8v-8h24Zm-32-104a8 8 0 0 1-8 8H96a8 8 0 0 1 0-16h64a8 8 0 0 1 8 8Zm0 32a8 8 0 0 1-8 8H96a8 8 0 0 1 0-16h64a8 8 0 0 1 8 8Zm0 32a8 8 0 0 1-8 8H96a8 8 0 0 1 0-16h64a8 8 0 0 1 8 8Z'/%3E%3C/svg%3E");
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23666' d='M140 80v41.21l34.17 20.5a12 12 0 1 1-12.34 20.58l-40-24A12 12 0 0 1 116 128V80a12 12 0 0 1 24 0Zm-12-52a99.38 99.38 0 0 0-70.76 29.34c-4.69 4.74-9 9.37-13.24 14V64a12 12 0 0 0-24 0v40a12 12 0 0 0 12 12h40a12 12 0 0 0 0-24H53.41c4.24-5.95 8.53-11.93 13.49-16.95A76 76 0 1 1 52 128a12 12 0 0 0-24 0 100 100 0 1 0 100-100Z'/%3E%3C/svg%3E");
   }
 
-  /* Blog - article/newspaper icon */
-  .navbar-item-blog::before {
-    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cdefs%3E%3ClinearGradient id='grad6' x1='0%25' y1='0%25' x2='100%25' y2='100%25'%3E%3Cstop offset='0%25' style='stop-color:%230074d9'/%3E%3Cstop offset='100%25' style='stop-color:%23009296'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23grad6)' d='M216 40H40a16 16 0 0 0-16 16v144a16 16 0 0 0 16 16h176a16 16 0 0 0 16-16V56a16 16 0 0 0-16-16Zm0 160H40V56h176v144ZM184 96a8 8 0 0 1-8 8H80a8 8 0 0 1 0-16h96a8 8 0 0 1 8 8Zm0 32a8 8 0 0 1-8 8H80a8 8 0 0 1 0-16h96a8 8 0 0 1 8 8Zm0 32a8 8 0 0 1-8 8H80a8 8 0 0 1 0-16h96a8 8 0 0 1 8 8Z'/%3E%3C/svg%3E");
+  /* Dark mode icons */
+  [data-theme='dark'] .navbar-item-developer::before {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23ccc' d='M71.68 97.22 34.74 128l36.94 30.78a12 12 0 1 1-15.36 18.44l-48-40a12 12 0 0 1 0-18.44l48-40a12 12 0 0 1 15.36 18.44Zm176 21.56-48-40a12 12 0 1 0-15.36 18.44L221.26 128l-36.94 30.78a12 12 0 1 0 15.36 18.44l48-40a12 12 0 0 0 0-18.44ZM164.1 28.72a12 12 0 0 0-15.38 7.18l-64 176a12 12 0 0 0 7.18 15.37 11.79 11.79 0 0 0 4.1.73 12 12 0 0 0 11.28-7.9l64-176a12 12 0 0 0-7.18-15.38Z'/%3E%3C/svg%3E");
   }
 
-  /* Dark mode - same gradient icons work well on dark backgrounds */
+  [data-theme='dark'] .navbar-item-sdks::before {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23ccc' d='m225.6 62.64-88-48.17a19.91 19.91 0 0 0-19.2 0l-88 48.17A20 20 0 0 0 20 80.19v95.62a20 20 0 0 0 10.4 17.55l88 48.17a19.89 19.89 0 0 0 19.2 0l88-48.17a20 20 0 0 0 10.4-17.55V80.19a20 20 0 0 0-10.4-17.55ZM128 36.57 200 76l-72 39.42L56 76ZM44 96.82l72 39.43v76.89l-72-39.42Zm96 116.32v-76.89l72-39.43v76.89Z'/%3E%3C/svg%3E");
+  }
+
+  [data-theme='dark'] .navbar-item-api::before {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23ccc' d='M180.49 143.51a12 12 0 0 1 0 17l-24 24a12 12 0 0 1-17-17L155 152l-15.52-15.51a12 12 0 0 1 17-17ZM112.49 120.49a12 12 0 0 0-17 0l-24 24a12 12 0 0 0 0 17l24 24a12 12 0 0 0 17-17L97 153l15.52-15.51a12 12 0 0 0-.03-17ZM220 88v24a12 12 0 0 1-24 0v-16h-44a12 12 0 0 1-12-12V40H60v68a12 12 0 0 1-24 0V40a20 20 0 0 1 20-20h96a12 12 0 0 1 8.49 3.52l56 56A12 12 0 0 1 220 88Zm-60-8h23L160 57Zm-4 132H60v-12a12 12 0 0 0-24 0v12a20 20 0 0 0 20 20h100a12 12 0 0 0 0-24Zm64-44a12 12 0 0 0-12 12v36h-44a12 12 0 0 0 0 24h44a20 20 0 0 0 20-20v-40a12 12 0 0 0-8-12Z'/%3E%3C/svg%3E");
+  }
+
+  [data-theme='dark'] .navbar-item-cookbook::before {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23ccc' d='M224 44H160a43.86 43.86 0 0 0-32 13.85A43.86 43.86 0 0 0 96 44H32a20 20 0 0 0-20 20v128a20 20 0 0 0 20 20h64a20 20 0 0 1 20 20 12 12 0 0 0 24 0 20 20 0 0 1 20-20h64a20 20 0 0 0 20-20V64a20 20 0 0 0-20-20ZM96 188H36V68h60a20 20 0 0 1 20 20v108.69A43.74 43.74 0 0 0 96 188Zm124 0h-60a43.74 43.74 0 0 0-20 8.69V88a20 20 0 0 1 20-20h60Z'/%3E%3C/svg%3E");
+  }
+
+  [data-theme='dark'] .navbar-item-changelog::before {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 256 256'%3E%3Cpath fill='%23ccc' d='M140 80v41.21l34.17 20.5a12 12 0 1 1-12.34 20.58l-40-24A12 12 0 0 1 116 128V80a12 12 0 0 1 24 0Zm-12-52a99.38 99.38 0 0 0-70.76 29.34c-4.69 4.74-9 9.37-13.24 14V64a12 12 0 0 0-24 0v40a12 12 0 0 0 12 12h40a12 12 0 0 0 0-24H53.41c4.24-5.95 8.53-11.93 13.49-16.95A76 76 0 1 1 52 128a12 12 0 0 0-24 0 100 100 0 1 0 100-100Z'/%3E%3C/svg%3E");
+  }
 }
 
 /* GitHub icon link */
@@ -458,7 +460,6 @@ div[class*="codeBlockContent"] .prism-code {
   max-width: 100%;
 }
 
-
 /* Page title with gradient */
 article h1,
 .markdown h1,
@@ -499,7 +500,7 @@ article p {
 }
 
 /* Links with gradient */
-article a:not(.button):not([class*="hash-link"]):not([class*="author"]):not([class*="avatar"]) {
+article a:not(.button):not([class*="hash-link"]) {
   background: var(--hindsight-gradient);
   -webkit-background-clip: text;
   -webkit-text-fill-color: transparent;
@@ -508,14 +509,6 @@ article a:not(.button):not([class*="hash-link"]):not([class*="author"]):not([cla
   font-weight: 500;
 }
 
-/* Blog author links - ensure visible */
-[class*="author"] a,
-[class*="blogPost"] [class*="author"] {
-  color: var(--ifm-font-color-base) !important;
-  -webkit-text-fill-color: var(--ifm-font-color-base) !important;
-  background: none !important;
-}
-
 /* Links containing code - the code inherits the transparent text-fill from the link */
 article a code {
   -webkit-text-fill-color: #3396e8 !important;
@@ -629,67 +622,11 @@ th {
 
 /* Footer */
 .footer {
-  background: #09090b !important;
   border-top: 1px solid var(--ifm-toc-border-color);
-  padding: 3rem 0 2rem;
-}
-
-.footer__links {
-  margin-bottom: 2rem;
 }
 
 .footer__title {
-  font-family: 'Space Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
   font-weight: 700;
-  font-size: 0.875rem;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: #a1a1aa !important;
-  margin-bottom: 1rem;
-}
-
-.footer__item {
-  margin-bottom: 0.5rem;
-}
-
-.footer__link-item {
-  font-size: 0.875rem;
-  color: #d4d4d8 !important;
-  transition: color 0.15s ease;
-}
-
-.footer__link-item:hover {
-  color: #ffffff !important;
-  text-decoration: none;
-}
-
-.footer__copyright {
-  font-size: 0.8125rem;
-  color: #71717a !important;
-  border-top: 1px solid #27272a;
-  padding-top: 1.5rem;
-  margin-top: 1rem;
-}
-
-/* Light mode footer - keep dark style */
-[data-theme='light'] .footer {
-  background: #09090b !important;
-}
-
-[data-theme='light'] .footer__title {
-  color: #a1a1aa !important;
-}
-
-[data-theme='light'] .footer__link-item {
-  color: #d4d4d8 !important;
-}
-
-[data-theme='light'] .footer__link-item:hover {
-  color: #ffffff !important;
-}
-
-[data-theme='light'] .footer__copyright {
-  color: #71717a !important;
 }
 
 /* Tabs styling */

hindsight-integrations/litellm/README.md

@@ -78,7 +78,7 @@ Here's what happens under the hood when you call `completion()`:
 │          # Relevant Memories                                                │
 │          1. [WORLD] User prefers pytest for testing                         │
 │          2. [WORLD] User is building a FastAPI app                          │
-│          3. [WORLD] User likes type hints                                 │
+│          3. [OPINION] User likes type hints                                 │
 │      """},                                                                  │
 │      {"role": "user", "content": "Help me with my Python project"}          │
 │  ]                                                                          │
@@ -137,7 +137,7 @@ hindsight_litellm.configure(
     max_memories=None,             # Maximum memories to inject (None = unlimited)
     max_memory_tokens=4096,        # Maximum tokens for memory context
     recall_budget="mid",           # Recall budget: "low", "mid", "high"
-    fact_types=["world", "experience"], # Filter fact types to inject
+    fact_types=["world", "agent"], # Filter fact types to inject
 
     # Optional - Bank Configuration
     bank_name="My Agent",          # Human-readable display name for the memory bank
@@ -182,7 +182,7 @@ hindsight_litellm.configure(
     bank_id="my-agent",
     use_reflect=False,  # Default
 )
-# Injects: "1. [WORLD] User prefers Python\n2. [EXPERIENCE] User struggled with Java..."
+# Injects: "1. [WORLD] User prefers Python\n2. [OPINION] User dislikes Java..."
 
 # Reflect mode - synthesized context
 hindsight_litellm.configure(
@@ -240,7 +240,7 @@ for m in memories:
 
 # Output:
 # - [world] User is building a FastAPI project
-# - [world] User prefers Python over JavaScript
+# - [opinion] User prefers Python over JavaScript
 ```
 
 ### Reflect - Get synthesized context

hindsight-integrations/openai/README.md

@@ -108,7 +108,7 @@ messages = [
 messages = [
     {
         "role": "system",
-        "content": "Relevant context from your memory:\n\n1. User prefers Python for its simplicity\n   (Date: 2024-01-15)\n   (Type: world)"
+        "content": "Relevant context from your memory:\n\n1. User prefers Python for its simplicity\n   (Date: 2024-01-15)\n   (Type: opinion)"
     },
     {"role": "user", "content": "What's my favorite programming language?"}
 ]

scripts/dev/start-worker.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")/../.."
+
+ENV_FILE=".env"
+if [ ! -f "$ENV_FILE" ]; then
+  echo "Error: Environment file $ENV_FILE not found at project root."
+  exit 1
+fi
+
+echo "Loading environment from $ENV_FILE"
+echo ""
+
+# Export all variables from env file
+set -a
+source "$ENV_FILE"
+set +a
+
+uv run hindsight-worker "$@"